@prairielearn/postgres 3.0.0 → 4.0.1

package/dist/pool.d.ts

@@ -1,5 +1,4 @@
 import pg, { type QueryResult } from 'pg';
-import Cursor from 'pg-cursor';
 import { z } from 'zod';
 export type QueryParams = Record<string, any> | any[];
 export interface CursorIterator<T> {
@@ -31,68 +30,36 @@ export declare class PostgresPool {
      * Creates a new connection pool and attempts to connect to the database.
      */
     initAsync(pgConfig: PostgresPoolConfig, idleErrorHandler: (error: Error, client: pg.PoolClient) => void): Promise<void>;
-    /**
-     * Creates a new connection pool and attempts to connect to the database.
-     */
-    init: (arg1: PostgresPoolConfig, arg2: (error: Error, client: pg.PoolClient) => void, callback: (err: NodeJS.ErrnoException) => void) => void;
     /**
      * Closes the connection pool.
      */
     closeAsync(): Promise<void>;
     /**
-     * Closes the connection pool.
-     */
-    close: (callback: (err: NodeJS.ErrnoException) => void) => void;
-    /**
-     * Gets a new client from the connection pool. If `err` is not null
-     * then `client` and `done` are undefined. If `err` is null then
-     * `client` is valid and can be used. The caller MUST call `done()` to
+     * Gets a new client from the connection pool. The caller MUST call `release()` to
      * release the client, whether or not errors occurred while using
      * `client`. The client can call `done(truthy_value)` to force
      * destruction of the client, but this should not be used except in
      * unusual circumstances.
      */
     getClientAsync(): Promise<pg.PoolClient>;
-    /**
-     * Gets a new client from the connection pool.
-     */
-    getClient(callback: (error: Error | null, client?: pg.PoolClient, done?: () => void) => void): void;
     /**
      * Performs a query with the given client.
      */
     queryWithClientAsync(client: pg.PoolClient, sql: string, params: QueryParams): Promise<pg.QueryResult>;
-    /**
-     * Performs a query with the given client.
-     */
-    queryWithClient: (arg1: import("pg").PoolClient, arg2: string, arg3: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
      */
     queryWithClientOneRowAsync(client: pg.PoolClient, sql: string, params: QueryParams): Promise<pg.QueryResult>;
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientOneRow: (arg1: import("pg").PoolClient, arg2: string, arg3: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
      */
     queryWithClientZeroOrOneRowAsync(client: pg.PoolClient, sql: string, params: QueryParams): Promise<QueryResult>;
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientZeroOrOneRow: (arg1: import("pg").PoolClient, arg2: string, arg3: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: QueryResult<any>) => void) => void;
     /**
      * Rolls back the current transaction for the given client.
      */
     rollbackWithClientAsync(client: pg.PoolClient): Promise<void>;
-    /**
-     * Rolls back the current transaction for the given client.
-     */
-    rollbackWithClient(client: pg.PoolClient, _done: (release?: any) => void, callback: (err: Error | null) => void): void;
     /**
      * Begins a new transaction.
      */
@@ -102,11 +69,6 @@ export declare class PostgresPool {
      * Also releases the client.
      */
     endTransactionAsync(client: pg.PoolClient, err: Error | null | undefined): Promise<void>;
-    /**
-     * Commits the transaction if err is null, otherwise rollbacks the transaction.
-     * Also releases the client.
-     */
-    endTransaction(client: pg.PoolClient, _done: (rollback?: any) => void, err: Error | null | undefined, callback: (error: Error | null) => void): void;
     /**
      * Runs the specified function inside of a transaction. The function will
      * receive a database client as an argument, but it can also make queries
@@ -120,86 +82,44 @@ export declare class PostgresPool {
      * Executes a query with the specified parameters.
      */
     queryAsync(sql: string, params: QueryParams): Promise<QueryResult>;
-    /**
-     * Executes a query with the specified parameters.
-     */
-    query: (arg1: string, arg2: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: QueryResult<any>) => void) => void;
     /**
      * Executes a query with the specified parameters. Errors if the query does
      * not return exactly one row.
      */
     queryOneRowAsync(sql: string, params: QueryParams): Promise<pg.QueryResult>;
-    /**
-     * Executes a query with the specified parameters. Errors if the query does
-     * not return exactly one row.
-     */
-    queryOneRow: (arg1: string, arg2: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
     /**
      * Executes a query with the specified parameters. Errors if the query
      * returns more than one row.
      */
     queryZeroOrOneRowAsync(sql: string, params: QueryParams): Promise<pg.QueryResult>;
     /**
-     * Executes a query with the specified parameters. Errors if the query
-     * returns more than one row.
-     */
-    queryZeroOrOneRow: (arg1: string, arg2: QueryParams, callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls the given function with the specified parameters.
+     * Calls the given sproc with the specified parameters.
      */
     callAsync(functionName: string, params: any[]): Promise<pg.QueryResult>;
     /**
-     * Calls the given function with the specified parameters.
-     */
-    call: (arg1: string, arg2: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc does not return exactly one row.
      */
     callOneRowAsync(functionName: string, params: any[]): Promise<pg.QueryResult>;
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
-     */
-    callOneRow: (arg1: string, arg2: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc returns more than one row.
      */
     callZeroOrOneRowAsync(functionName: string, params: any[]): Promise<pg.QueryResult>;
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
-     */
-    callZeroOrOneRow: (arg1: string, arg2: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls a function with the specified parameters using a specific client.
+     * Calls a sproc with the specified parameters using a specific client.
      */
     callWithClientAsync(client: pg.PoolClient, functionName: string, params: any[]): Promise<pg.QueryResult>;
     /**
-     * Calls a function with the specified parameters using a specific client.
-     */
-    callWithClient: (arg1: import("pg").PoolClient, arg2: string, arg3: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
+     * Calls a sproc with the specified parameters using a specific client.
+     * Errors if the sproc does not return exactly one row.
      */
     callWithClientOneRowAsync(client: pg.PoolClient, functionName: string, params: any[]): Promise<pg.QueryResult>;
     /**
      * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
-     */
-    callWithClientOneRow: (arg1: import("pg").PoolClient, arg2: string, arg3: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
+     * Errors if the sproc returns more than one row.
      */
     callWithClientZeroOrOneRowAsync(client: pg.PoolClient, functionName: string, params: any[]): Promise<pg.QueryResult>;
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
-     */
-    callWithClientZeroOrOneRow: (arg1: import("pg").PoolClient, arg2: string, arg3: any[], callback: (err: NodeJS.ErrnoException | null, result: pg.QueryResult<any>) => void) => void;
     queryRows<Model extends z.ZodTypeAny>(sql: string, model: Model): Promise<z.infer<Model>[]>;
     queryRows<Model extends z.ZodTypeAny>(sql: string, params: QueryParams, model: Model): Promise<z.infer<Model>[]>;
     queryRow<Model extends z.ZodTypeAny>(sql: string, model: Model): Promise<z.infer<Model>>;
@@ -216,19 +136,14 @@ export declare class PostgresPool {
      * Returns a {@link Cursor} for the given query. The cursor can be used to
      * read results in batches, which is useful for large result sets.
      */
-    queryCursorWithClient(client: pg.PoolClient, sql: string, params: QueryParams): Promise<Cursor>;
-    /**
-     * Returns an {@link CursorIterator} that can be used to iterate over the
-     * results of the query in batches, which is useful for large result sets.
-     */
-    queryCursor<Model extends z.ZodTypeAny>(sql: string, params: QueryParams): Promise<CursorIterator<z.infer<Model>>>;
+    private queryCursorWithClient;
     /**
      * Returns an {@link CursorIterator} that can be used to iterate over the
      * results of the query in batches, which is useful for large result sets.
      * Each row will be parsed by the given Zod schema.
      */
-    queryValidatedCursor<Model extends z.ZodTypeAny>(sql: string, params: QueryParams, model: Model): Promise<CursorIterator<z.infer<Model>>>;
-    private queryValidatedCursorInternal;
+    queryCursor<Model extends z.ZodTypeAny>(sql: string, params: QueryParams, model: Model): Promise<CursorIterator<z.infer<Model>>>;
+    private queryCursorInternal;
     /**
      * Set the schema to use for the search path.
      *
@@ -238,7 +153,7 @@ export declare class PostgresPool {
     /**
      * Get the schema that is currently used for the search path.
      *
-     * @return schema in use (may be `null` to indicate no schema)
+     * @returns schema in use (may be `null` to indicate no schema)
      */
     getSearchSchema(): string | null;
     /**
@@ -248,10 +163,6 @@ export declare class PostgresPool {
      * @returns The randomly-generated search schema.
      */
     setRandomSearchSchemaAsync(prefix: string): Promise<string>;
-    /**
-     * Generate, set, and return a random schema name.
-     */
-    setRandomSearchSchema: (arg1: string, callback: (err: NodeJS.ErrnoException, result: string) => void) => void;
     /** The number of established connections. */
     get totalCount(): number;
     /** The number of idle connections. */

package/dist/pool.js

@@ -1,6 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Readable, Transform } from 'node:stream';
-import { callbackify } from 'node:util';
 import debugfn from 'debug';
 import _ from 'lodash';
 import multipipe from 'multipipe';
@@ -188,10 +187,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Creates a new connection pool and attempts to connect to the database.
-     */
-    init = callbackify(this.initAsync);
     /**
      * Closes the connection pool.
      */
@@ -202,13 +197,7 @@ export class PostgresPool {
         this.pool = null;
     }
     /**
-     * Closes the connection pool.
-     */
-    close = callbackify(this.closeAsync);
-    /**
-     * Gets a new client from the connection pool. If `err` is not null
-     * then `client` and `done` are undefined. If `err` is null then
-     * `client` is valid and can be used. The caller MUST call `done()` to
+     * Gets a new client from the connection pool. The caller MUST call `release()` to
      * release the client, whether or not errors occurred while using
      * `client`. The client can call `done(truthy_value)` to force
      * destruction of the client, but this should not be used except in
@@ -253,14 +242,6 @@ export class PostgresPool {
         }
         return client;
     }
-    /**
-     * Gets a new client from the connection pool.
-     */
-    getClient(callback) {
-        this.getClientAsync()
-            .then((client) => callback(null, client, client.release))
-            .catch((err) => callback(err));
-    }
     /**
      * Performs a query with the given client.
      */
@@ -279,10 +260,6 @@ export class PostgresPool {
             throw enhanceError(err, sql, params);
         }
     }
-    /**
-     * Performs a query with the given client.
-     */
-    queryWithClient = callbackify(this.queryWithClientAsync);
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
@@ -301,11 +278,6 @@ export class PostgresPool {
         debug('queryWithClientOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientOneRow = callbackify(this.queryWithClientOneRowAsync);
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
@@ -324,11 +296,6 @@ export class PostgresPool {
         debug('queryWithClientZeroOrOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientZeroOrOneRow = callbackify(this.queryWithClientZeroOrOneRowAsync);
     /**
      * Rolls back the current transaction for the given client.
      */
@@ -351,16 +318,6 @@ export class PostgresPool {
             client.release(err);
         }
     }
-    /**
-     * Rolls back the current transaction for the given client.
-     */
-    rollbackWithClient(client, _done, callback) {
-        // Note that we can't use `util.callbackify` here because this function
-        // has an additional unused `done` parameter for backwards compatibility.
-        this.rollbackWithClientAsync(client)
-            .then(() => callback(null))
-            .catch((err) => callback(err));
-    }
     /**
      * Begins a new transaction.
      */
@@ -406,15 +363,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Commits the transaction if err is null, otherwise rollbacks the transaction.
-     * Also releases the client.
-     */
-    endTransaction(client, _done, err, callback) {
-        this.endTransactionAsync(client, err)
-            .then(() => callback(null))
-            .catch((error) => callback(error));
-    }
     /**
      * Runs the specified function inside of a transaction. The function will
      * receive a database client as an argument, but it can also make queries
@@ -469,10 +417,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Executes a query with the specified parameters.
-     */
-    query = callbackify(this.queryAsync);
     /**
      * Executes a query with the specified parameters. Errors if the query does
      * not return exactly one row.
@@ -490,11 +434,6 @@ export class PostgresPool {
         debug('queryOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Executes a query with the specified parameters. Errors if the query does
-     * not return exactly one row.
-     */
-    queryOneRow = callbackify(this.queryOneRowAsync);
     /**
      * Executes a query with the specified parameters. Errors if the query
      * returns more than one row.
@@ -513,12 +452,7 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Executes a query with the specified parameters. Errors if the query
-     * returns more than one row.
-     */
-    queryZeroOrOneRow = callbackify(this.queryZeroOrOneRowAsync);
-    /**
-     * Calls the given function with the specified parameters.
+     * Calls the given sproc with the specified parameters.
      */
     async callAsync(functionName, params) {
         debug('call()', 'function:', functionName);
@@ -530,12 +464,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters.
-     */
-    call = callbackify(this.callAsync);
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc does not return exactly one row.
      */
     async callOneRowAsync(functionName, params) {
         debug('callOneRow()', 'function:', functionName);
@@ -551,13 +481,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
-     */
-    callOneRow = callbackify(this.callOneRowAsync);
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc returns more than one row.
      */
     async callZeroOrOneRowAsync(functionName, params) {
         debug('callZeroOrOneRow()', 'function:', functionName);
@@ -573,12 +498,7 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
-     */
-    callZeroOrOneRow = callbackify(this.callZeroOrOneRowAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
+     * Calls a sproc with the specified parameters using a specific client.
      */
     async callWithClientAsync(client, functionName, params) {
         debug('callWithClient()', 'function:', functionName);
@@ -590,12 +510,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls a function with the specified parameters using a specific client.
-     */
-    callWithClient = callbackify(this.callWithClientAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
+     * Calls a sproc with the specified parameters using a specific client.
+     * Errors if the sproc does not return exactly one row.
      */
     async callWithClientOneRowAsync(client, functionName, params) {
         debug('callWithClientOneRow()', 'function:', functionName);
@@ -612,12 +528,7 @@ export class PostgresPool {
     }
     /**
      * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
-     */
-    callWithClientOneRow = callbackify(this.callWithClientOneRowAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
+     * Errors if the sproc returns more than one row.
      */
     async callWithClientZeroOrOneRowAsync(client, functionName, params) {
         debug('callWithClientZeroOrOneRow()', 'function:', functionName);
@@ -633,10 +544,11 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
+     * Executes a query with the specified parameters. Returns an array of rows
+     * that conform to the given Zod schema.
+     *
+     * If the query returns a single column, the return value will be a list of column values.
      */
-    callWithClientZeroOrOneRow = callbackify(this.callWithClientZeroOrOneRowAsync);
     async queryRows(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -650,6 +562,11 @@ export class PostgresPool {
             return z.array(model).parse(results.rows);
         }
     }
+    /**
+     * Executes a query with the specified parameters. Returns exactly one row that conforms to the given Zod schema.
+     *
+     * If the query returns a single column, the return value will be the column value itself.
+     */
     async queryRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -662,6 +579,12 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Executes a query with the specified parameters. Returns either null or a
+     * single row that conforms to the given Zod schema, and errors otherwise.
+     *
+     * If the query returns a single column, the return value will be the column value itself.
+     */
     async queryOptionalRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -677,6 +600,10 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters.
+     * Errors if the sproc does not return anything.
+     */
     async callRows(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -690,6 +617,10 @@ export class PostgresPool {
             return z.array(model).parse(results.rows);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters.
+     * Returns exactly one row from the sproc that conforms to the given Zod schema.
+     */
     async callRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -702,6 +633,10 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters. Returns either null
+     * or a single row that conforms to the given Zod schema.
+     */
     async callOptionalRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -729,22 +664,15 @@ export class PostgresPool {
         lastQueryMap.set(client, processedSql);
         return client.query(new Cursor(processedSql, paramsArray));
     }
-    /**
-     * Returns an {@link CursorIterator} that can be used to iterate over the
-     * results of the query in batches, which is useful for large result sets.
-     */
-    async queryCursor(sql, params) {
-        return this.queryValidatedCursorInternal(sql, params);
-    }
     /**
      * Returns an {@link CursorIterator} that can be used to iterate over the
      * results of the query in batches, which is useful for large result sets.
      * Each row will be parsed by the given Zod schema.
      */
-    async queryValidatedCursor(sql, params, model) {
-        return this.queryValidatedCursorInternal(sql, params, model);
+    async queryCursor(sql, params, model) {
+        return this.queryCursorInternal(sql, params, model);
     }
-    async queryValidatedCursorInternal(sql, params, model) {
+    async queryCursorInternal(sql, params, model) {
         const client = await this.getClientAsync();
         const cursor = await this.queryCursorWithClient(client, sql, params);
         let iterateCalled = false;
@@ -827,7 +755,7 @@ export class PostgresPool {
     /**
      * Get the schema that is currently used for the search path.
      *
-     * @return schema in use (may be `null` to indicate no schema)
+     * @returns schema in use (may be `null` to indicate no schema)
      */
     getSearchSchema() {
         return this.searchSchema;
@@ -855,10 +783,6 @@ export class PostgresPool {
         await this.setSearchSchema(schema);
         return schema;
     }
-    /**
-     * Generate, set, and return a random schema name.
-     */
-    setRandomSearchSchema = callbackify(this.setRandomSearchSchemaAsync);
     /** The number of established connections. */
     get totalCount() {
         return this.pool?.totalCount ?? 0;