Skip to main content

PostgreSQLDatabaseClient

PostgreSQL database client. Extends @perseid/server AbstractDatabaseClient class.

SQL_TYPES_MAPPING​

Data model types <> SQL types mapping, for tables creation.

protected readonly SQL_TYPES_MAPPING: Record<string, string>;

SQL_SORT_MAPPING​

SQL sorting keywords.

protected readonly SQL_SORT_MAPPING: Record<1 | -1, string>;

client​

PostgreSQL client instance.

protected client: pg.Pool;

textDecoder​

Used to format ArrayBuffers into strings.

protected textDecoder: TextDecoder;

textEncoder​

Used to format strings into ArrayBuffers.

protected textEncoder: TextEncoder;

generateResourceMetadat​

Generates metadata for resource, including fields, indexes, and constraints, necessary to generate the database structure and handle resources deletion.

protected generateResourceMetadata<Resource extends keyof DataModel & string>(
  resource: Resource,
): void;

Parameters​

  • resource: Type of resource for which to generate metadata.

Returns​

Resource metadata.

Usage​

TODO

parseFields​

Returns DBMS-specific formatted query metadata and projections from fields.

protected parseFields<Resource extends keyof DataModel & string>(
  resource: Resource,
  fields: Set<string>,
  maximumDepth: number,
  searchBody?: SearchBody | null,
  sortBy?: Partial<Record<string, 1 | -1>>,
): { projections: unknown; formattedQuery: FormattedQuery; };

Parameters​

  • resource: Type of resource for which to generate metadata.
  • resource: Type of resource to query.
  • fields: List of fields to fetch from database.
  • maximumDepth: Maximum allowed level of resources depth.
  • searchBody: Optional search body to apply to the request. Defaults to null.
  • sortBy: Optional sorting to apply to the request. Defaults to {}.

Returns​

Formatted query, along with projections.

Throws​

  • If field path does not exist in data model.
  • If field path is not a leaf in data model.
  • If any field path in search body is not indexed.
  • If any field path in sorting is not sortable.

Usage​

TODO

generateQuery​

Generates the final DBMS-specific query from formattedQuery.

protected generateQuery<Resource extends keyof DataModel>(
  resource: Resource,
  formattedQuery: FormattedQuery,
  textIndent?: string,
): string;

Parameters​

  • sortBy: Optional sorting to apply to the request. Defaults to {}.
  • resource: Type of resource for which to generate database query.
  • formattedQuery: Formatted query to generate database query from.
  • isSearchQuery: Whether query is a search query or a simple SELECT. Defaults to false.
  • textIndent: Current indent. Used to improve SQL statement legibility. Defaults to "".

Returns​

Final DBMS-specific query.

Usage​

TODO

structurePayload​

Recursively formats payload into a structured format for database storage.

protected structurePayload<Resource extends keyof DataModel & string>(
  resource: Resource,
  resourceId: Id,
  payload: Payload<DataModel[Resource]>,
  mode: 'CREATE' | 'UPDATE',
): StructuredPayload;

Parameters​

  • textIndent: Current indent. Used to improve SQL statement legibility. Defaults to "".
  • resource: Type of resource to format.
  • resourceId: Id of the related resource.
  • payload: Payload to format.
  • mode: Whether to structure payload for creation, or just a partial update.

Returns​

Structured format for database storage.

Usage​

TODO

formatResources​

Formats results into a database-agnostic structure, containing only requested fields.

protected formatResources<Resource extends keyof DataModel & string>(
  resource: Resource,
  results: unknown[],
  fields: unknown,
  mapping: Map<string, string>,
): DataModel[Resource][];

Parameters​

  • mode: Whether to structure payload for creation, or just a partial update.
  • resource: Type of resource to format.
  • results: List of database raw results to format.
  • fields: Fields tree used to format results.
  • mapping: Mapping between DBMS-specific field name and real field path.

Returns​

Formatted results.

Usage​

TODO

handleError​

Connects database client to the database server before performing any query, and handles common database server errors. You should always use this method to wrap your code.

protected handleError<T>(callback: () => Promise<T>): Promise<T>;

Parameters​

  • mapping: Mapping between DBMS-specific field name and real field path.
  • callback: Callback to wrap in the error handler.

Throws​

  • If maximum level of resources depth is exceeded.
  • If connection to the server failed.

Usage​

TODO

constructor​

Class constructor.

public constructor(
  model: Model,
  logger: Logger,
  cache: CacheClient,
  settings: DatabaseClientSettings,
);

Parameters​

  • callback: Callback to wrap in the error handler.
  • model: Data model to use.
  • logger: Logging system to use.
  • cache: Cache client instance to use for results caching.
  • settings: Database client settings.

Usage​

TODO

dropDatabase​

Drops the entire database.

public dropDatabase(): Promise<void>;

Parameters​

  • settings: Database client settings.

Usage​

TODO

createDatabase​

Creates the database.

public createDatabase(): Promise<void>;

Parameters​

  • settings: Database client settings.

Usage​

TODO

createMissingStructures​

Creates missing database structures for current data model.

public createMissingStructures(): Promise<void>;

Parameters​

  • settings: Database client settings.

Usage​

TODO

reset​

Resets the whole underlying database, re-creating structures, indexes, and such.

public reset(): Promise<void>;

Parameters​

  • settings: Database client settings.

Usage​

TODO

checkForeignIds​

Makes sure that foreignIds reference existing resources that match specific conditions.

public checkForeignIds<Resource extends keyof DataModel & string>(
  _resource: Resource,
  foreignIds: Map<string, { resource: keyof DataModel & string; filters: SearchFilters; }>,
): Promise<void>;

Parameters​

  • settings: Database client settings.
  • foreignIds: Foreign ids to check in database.

Throws​

  • Transformed database error if applicable, original error otherwise.

Usage​

TODO

create​

Creates a new resource in database.

public create<Resource extends keyof DataModel & string>(
  resource: Resource,
  payload: DataModel[Resource],
): Promise<void>;

Parameters​

  • foreignIds: Foreign ids to check in database.
  • resource: Type of resource to create.
  • payload: New resource payload.

Usage​

TODO

update​

Updates resource with id id in database.

public update<Resource extends keyof DataModel & string>(
resource: Resource,
id: Id,
payload: Payload<DataModel[Resource]>,
): Promise<boolean>;

Parameters​

  • payload: New resource payload.
  • resource: Type of resource to update.
  • id: Resource id.
  • payload: Updated resource payload.

Returns​

true if resource has been successfully updated, false otherwise.

Usage​

TODO

view​

Fetches resource with id id from database.

public view<Resource extends keyof DataModel & string>(
  resource: Resource,
  id: Id,
  options?: ViewCommandOptions,
): Promise<DataModel[Resource] | null>;

Parameters​

  • payload: Updated resource payload.
  • resource: Type of resource to fetch.
  • id: Id of the resource to fetch.
  • options: Query options. Defaults to {}.

Returns​

Resource if it exists, null otherwise.

Usage​

TODO

Fetches a paginated list of resources from database, that match specific filters/query.

public search<Resource extends keyof DataModel & string>(
  resource: Resource,
  body: SearchBody,
  options?: SearchCommandOptions,
): Promise<Results<DataModel[Resource]>>;

Parameters​

  • options: Query options. Defaults to {}.
  • resource: Type of resources to fetch.
  • body: Search/filters body.
  • options: Query options. Defaults to {}.

Returns​

Paginated list of resources.

Usage​

TODO

list​

Fetches a paginated list of resources from database.

public list<Resource extends keyof DataModel & string>(
  resource: Resource,
  options?: ListCommandOptions,
): Promise<Results<DataModel[Resource]>>;

Parameters​

  • options: Query options. Defaults to {}.
  • resource: Type of resources to fetch.
  • options: Query options. Defaults to {}.

Returns​

Paginated list of resources.

Usage​

TODO

delete​

Deletes resource with id id from database.

public delete<Resource extends keyof DataModel & string>(
  resource: Resource,
  id: Id,
): Promise<boolean>;

Parameters​

  • options: Query options. Defaults to {}.
  • resource: Type of resource to delete.
  • id: Resource id.

Returns​

true if resource has been successfully deleted, false otherwise.

Usage​

TODO