docorm/dist/postgresql/db.d.ts

Persistence layer with ORM features for JSON documents

/**
 * PostgreSQL database connection management and query utilities
 *
 * @module lib/db/postgresql/db
 */
import pg from 'pg';
import QueryStream from 'pg-query-stream';
export type Client = pg.PoolClient & {
    lastQuery?: any[];
    numQueriesInTransaction?: number;
};
export declare function initDb(): void;
/**
 * Obtain a database client for the current CLS context.
 *
 * The database client is a node-postgres client Client object managed by the node-postgres connection pool.
 *
 * Each Continuation Local Storage (CLS) context uses at most one database client at a time. A CLS context typicall
 * represents an API request in progress or a worker task. In typical usage, once requested, the client will remain
 * checked out by that context until the API request or worker task finishes. However, it is possible to release the
 * client and request a new one; this pattern may be appropriate for long-running worker tasks that do not need to use
 * a single transaction and only access the database intermittently.
 *
 * The CLS context is identified by the namespace "lims.db.transaction".
 *
 * This function either returns the client associated with the current CLS context or obtains a new client and
 * associates it with the context.
 *
 * This function is asynchronous, and it may need to wait (a) until a new connection is allocated and added to the pool,
 * if all connections are in use and the maximum pool size has not been reached, or (b) until a connection is released
 * back to the pool, in case the pool is full and all connections are in use.
 *
 * @param options
 * @param options.transactional - A flag indicating whether to start a transaction when obtaining a new client. This has
 *   no effect if a client is already associated with the CLS context.
 * @param options.useClientFromCLS - A flag indicating whether to use an existing client obtained from Continuation
 *   Local Storage. If false, a new client will be requested from the pool.
 * @return - A database client from the pool.
 */
export declare function getClient({ transactional, useClientFromCLS }?: {
    transactional?: boolean | undefined;
    useClientFromCLS?: boolean | undefined;
}): Promise<Client>;
export declare function commit(client?: Client): Promise<void>;
export declare function commitAndBeginTransaction(client?: Client | null): Promise<void>;
export declare function rollback(client?: Client | null): Promise<void>;
export declare function releaseClient(client?: Client | null): void;
/**
 * Insert multiple rows, with no transaction.
 *
 * Unlike the query() function, this uses the pg-promise package instead of node-postgres. pg-promise offers more
 * efficient handling of bulk inserts than node-postgres, on which it is based.
 *
 * If we migrate fully to pg-promise, we can add support for transactions, which are not currently needed in the one
 * context where we perform bulk inserts.
 *
 * @param table - The name of the table.
 * @param columns - An array of names of columns to be populated.
 * @param rows - An array of row objects to insert. Each row object should have properties whose names match the column
 *   names.
 */
export declare function insertMultipleRows(table: string, columns: string[], rows: object[]): Promise<void>;
export declare function updateMultipleRows(table: string, idColumn: string, columnsToUpdate: string[], rows: object[]): Promise<void>;
/**
 * Perform a database query.
 *
 * The query is run by the current node-postgres client, obtained by calling getClient(). TODO UPDATE for client param.
 *
 * @param sqlQuery - The query text, which may include numbered parameters of the form $1, $2, etc.
 * @param params - An array of parameter values. The first array element (at index 0) fills parameter $1, and so forth.
 * @param client - A database client to use. If null, then a client will be obtained by calling {@link getClient}.
 * @return - The query result as returned by node-postgres which may include a rows property.
 */
export declare function query(sqlQuery: string, params?: any[], client?: Client | null): Promise<pg.QueryResult<any>>;
/**
 * Perform a database query and return results in a stream, using a database cursor.
 *
 * The query is run by the current node-postgres client, obtained by calling getClient().
 *
 * Streaming is accomplished using the pg-query-stream library. By using a database cursor, we are minimize the number
 * of records in memory.
 *
 * Notice that if other queries may be run to process this query's results while its cursor is still open, this
 * stream-based query should be run using a different database cursor. Otherwise deadlock may occur.
 *
 * @param text - The query text, which may include numbered parameters of the form $1, $2, etc.
 * @param params - An array of parameter values. The first array element (at index 0) fills parameter $1, and so forth.
 * @param client - A database client to use. If null, then a client will be obtained by calling {@link getClient}.
 * @return A stream of query result rows.
 */
export declare function queryStream(sqlQuery: string, params?: any[], client?: Client | null): Promise<{
    run: () => Promise<QueryStream>;
    stream: QueryStream;
}>;
export declare function customizeClient(client: Client): Promise<Client>;
export declare function closePool(): Promise<void>;
//# sourceMappingURL=db.d.ts.map