postgrejs 3.3.0 → 3.5.0

package/connection/pool.d.ts

@@ -70,6 +70,22 @@ export declare class Pool extends SafeEventEmitter {
      * Executes a query
      */
     query(sql: string | QueryRequest, options?: PoolQueryOptions): Promise<QueryResult>;
+    /**
+     * Takes a connection out of the pool, runs `fn` inside a transaction on
+     * it, and gives the connection back however that ends.
+     *
+     * ```ts
+     * await pool.transaction(async tx => {
+     *   await tx.query('insert into orders (total) values ($1)', { params: [total] });
+     *   await tx.query('update stock set n = n - 1 where sku = $1', { params: [sku] });
+     * });
+     * ```
+     *
+     * A transaction cannot be spread over pool.query() calls - each of those
+     * is free to pick a different connection, and a transaction lives on
+     * one. This is the way to get several statements onto the same one.
+     */
+    transaction<T>(fn: (connection: Connection) => Promise<T>): Promise<T>;
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
     release(connection: Connection): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;

package/connection/pool.js

@@ -222,6 +222,30 @@ export class Pool extends SafeEventEmitter {
             slot.load--;
         }
     }
+    /**
+     * Takes a connection out of the pool, runs `fn` inside a transaction on
+     * it, and gives the connection back however that ends.
+     *
+     * ```ts
+     * await pool.transaction(async tx => {
+     *   await tx.query('insert into orders (total) values ($1)', { params: [total] });
+     *   await tx.query('update stock set n = n - 1 where sku = $1', { params: [sku] });
+     * });
+     * ```
+     *
+     * A transaction cannot be spread over pool.query() calls - each of those
+     * is free to pick a different connection, and a transaction lives on
+     * one. This is the way to get several statements onto the same one.
+     */
+    async transaction(fn) {
+        const connection = await this.acquire();
+        try {
+            return await connection.transaction(fn);
+        }
+        finally {
+            await this.release(connection);
+        }
+    }
     async prepare(sql, options) {
         const connection = await this.acquire();
         const statement = await connection.prepare(sql, options);

package/connection/prepared-statement.d.ts

@@ -1,3 +1,4 @@
+import type { BatchResult } from '../interfaces/batch-result.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
 import type { QueryResult } from '../interfaces/query-result.js';
 import type { StatementPrepareOptions } from '../interfaces/statement-prepare-options.js';
@@ -20,7 +21,69 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
     get sql(): string;
     get paramTypes(): Maybe<Maybe<OID>[]>;
     execute(options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Runs this statement once per parameter set, sending every Bind/Execute
+     * before waiting for any of them and closing the lot with a single Sync.
+     *
+     * ```ts
+     * const st = await connection.prepare('update users set name = $1 where id = $2');
+     * const batch = await st.executeBatch([
+     *   ['John', 1],
+     *   ['Jane', 2],
+     *   ['Bob', 3],
+     * ]);
+     * batch.results.map(r => r.rowsAffected); // [1, 1, 0]
+     * batch.totalRowsAffected;                // 2
+     * ```
+     *
+     * Three things follow from the single Sync, and they are the reasons to
+     * reach for this over a loop or a Promise.all() of execute() calls:
+     *
+     * - **Speed.** Per-set Sync makes the server close an implicit
+     *   transaction and answer ReadyForQuery every time. Collapsing that to
+     *   one turned 1000 updates from 194ms (pipelined execute() calls) into
+     *   21ms locally, with socket reads dropping from 972 to 3.
+     * - **One transaction.** Unless an explicit transaction is already open,
+     *   the whole batch commits or rolls back together. This differs from N
+     *   separate execute() calls, where each commits on its own.
+     * - **A failing set stops the rest.** PostgreSQL discards everything
+     *   between an error and the Sync, so sets after a rejected one never
+     *   run. The error carries `failedIndex` (which set was rejected) and
+     *   `batchResults` (the ones that had completed) so the caller can see
+     *   how far it got.
+     *
+     * Every set runs the same statement, so results map to sets by position.
+     * Sets that return rows get them decoded into `rows` exactly as
+     * `execute()` would, `rowDecoder` included; `fetchCount` does not apply,
+     * since a portal suspended mid-batch would break that mapping - each set
+     * runs to completion and buffers its rows.
+     *
+     * For a bulk INSERT specifically, `connection.copyFrom()` is faster
+     * still, and a single `UPDATE ... FROM (VALUES ...)` beats this for bulk
+     * updates of one shape - at the cost of PostgreSQL's 65535-parameter
+     * ceiling. This is the general answer when neither fits.
+     *
+     * @param paramSets One array of bind parameters per execution.
+     * @param options Applied to every set - the same options `execute()`
+     *   takes, minus `fetchCount` and `cursor`, which a batch cannot honour.
+     */
+    executeBatch(paramSets: any[][], options?: QueryOptions): Promise<BatchResult>;
+    protected _executeBatchWithTransaction(paramSets: any[][], options: QueryOptions): Promise<BatchResult>;
     protected _executeWithTransaction(options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Runs `fn` inside whatever transaction handling the connection's config
+     * and `options` call for: an implicit BEGIN when autoCommit is off, a
+     * SAVEPOINT to roll back to when one is already open, a COMMIT when the
+     * call is the one turning autoCommit back on.
+     *
+     * Generic over `fn` rather than calling _execute() directly so that
+     * executeBatch() gets the same handling for the batch as a whole. Per
+     * set would be wrong twice over: the savepoints alone would add two
+     * statements per set, and the batch already shares one transaction by
+     * virtue of its single Sync, so a per-set savepoint could not roll one
+     * set back independently anyway.
+     */
+    protected _withTransaction<T>(options: QueryOptions | undefined, fn: (inlineSavepoint?: string) => Promise<T>, canInlineSavepoint?: boolean): Promise<T>;
     close(): Promise<void>;
     /**
      * Asks the server to cancel whatever this statement's connection is
@@ -28,7 +91,7 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      * option, which reports the abort to the caller that asked for it.
      */
     cancel(): Promise<void>;
-    protected _execute(options?: QueryOptions): Promise<QueryResult>;
+    protected _execute(options?: QueryOptions, savepoint?: string): Promise<QueryResult>;
     /**
      * Called by Cursor.close() instead of separately awaiting
      * Portal.close() then this.close(). Returns false (no wire action taken,

package/connection/prepared-statement.js

@@ -55,7 +55,89 @@ export class PreparedStatement extends SafeEventEmitter {
             return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeWithTransaction(options));
         return this._executeWithTransaction(options);
     }
+    /**
+     * Runs this statement once per parameter set, sending every Bind/Execute
+     * before waiting for any of them and closing the lot with a single Sync.
+     *
+     * ```ts
+     * const st = await connection.prepare('update users set name = $1 where id = $2');
+     * const batch = await st.executeBatch([
+     *   ['John', 1],
+     *   ['Jane', 2],
+     *   ['Bob', 3],
+     * ]);
+     * batch.results.map(r => r.rowsAffected); // [1, 1, 0]
+     * batch.totalRowsAffected;                // 2
+     * ```
+     *
+     * Three things follow from the single Sync, and they are the reasons to
+     * reach for this over a loop or a Promise.all() of execute() calls:
+     *
+     * - **Speed.** Per-set Sync makes the server close an implicit
+     *   transaction and answer ReadyForQuery every time. Collapsing that to
+     *   one turned 1000 updates from 194ms (pipelined execute() calls) into
+     *   21ms locally, with socket reads dropping from 972 to 3.
+     * - **One transaction.** Unless an explicit transaction is already open,
+     *   the whole batch commits or rolls back together. This differs from N
+     *   separate execute() calls, where each commits on its own.
+     * - **A failing set stops the rest.** PostgreSQL discards everything
+     *   between an error and the Sync, so sets after a rejected one never
+     *   run. The error carries `failedIndex` (which set was rejected) and
+     *   `batchResults` (the ones that had completed) so the caller can see
+     *   how far it got.
+     *
+     * Every set runs the same statement, so results map to sets by position.
+     * Sets that return rows get them decoded into `rows` exactly as
+     * `execute()` would, `rowDecoder` included; `fetchCount` does not apply,
+     * since a portal suspended mid-batch would break that mapping - each set
+     * runs to completion and buffers its rows.
+     *
+     * For a bulk INSERT specifically, `connection.copyFrom()` is faster
+     * still, and a single `UPDATE ... FROM (VALUES ...)` beats this for bulk
+     * updates of one shape - at the cost of PostgreSQL's 65535-parameter
+     * ceiling. This is the general answer when neither fits.
+     *
+     * @param paramSets One array of bind parameters per execution.
+     * @param options Applied to every set - the same options `execute()`
+     *   takes, minus `fetchCount` and `cursor`, which a batch cannot honour.
+     */
+    async executeBatch(paramSets, options = {}) {
+        if (!Array.isArray(paramSets))
+            throw new TypeError('executeBatch() requires an array of parameter sets');
+        if (options.cursor)
+            throw new Error('executeBatch() cannot return a cursor - a batch runs every set to ' +
+                'completion under one Sync, so there is no portal left to fetch from');
+        const intlCon = getIntlConnection(this.connection);
+        if (!paramSets.length)
+            return { results: [], totalRowsAffected: 0 };
+        if (options.signal)
+            return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeBatchWithTransaction(paramSets, options));
+        return this._executeBatchWithTransaction(paramSets, options);
+    }
+    _executeBatchWithTransaction(paramSets, options) {
+        const intlCon = getIntlConnection(this.connection);
+        return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets, options));
+    }
     async _executeWithTransaction(options = {}) {
+        // The Bind+Execute+Sync path can carry the rollbackOnError savepoint
+        // in its own round trip; the cursor path cannot, because the portal it
+        // opens outlives this call and the savepoint has to outlive it too.
+        return this._withTransaction(options, savepoint => this._execute(options, savepoint), !(options.cursor && this._fields));
+    }
+    /**
+     * Runs `fn` inside whatever transaction handling the connection's config
+     * and `options` call for: an implicit BEGIN when autoCommit is off, a
+     * SAVEPOINT to roll back to when one is already open, a COMMIT when the
+     * call is the one turning autoCommit back on.
+     *
+     * Generic over `fn` rather than calling _execute() directly so that
+     * executeBatch() gets the same handling for the batch as a whole. Per
+     * set would be wrong twice over: the savepoints alone would add two
+     * statements per set, and the batch already shares one transaction by
+     * virtue of its single Sync, so a per-set savepoint could not roll one
+     * set back independently anyway.
+     */
+    async _withTransaction(options = {}, fn, canInlineSavepoint = false) {
         const intlCon = getIntlConnection(this.connection);
         const transactionCommand = this.sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
         let beginFirst = false;
@@ -77,13 +159,21 @@ export class PreparedStatement extends SafeEventEmitter {
         const rollbackOnError = !transactionCommand &&
             intlCon.inTransaction &&
             (options?.rollbackOnError ?? intlCon.config.rollbackOnError ?? true);
-        if (rollbackOnError && intlCon.inTransaction)
+        // When `fn` can put the savepoint on the wire itself, SAVEPOINT and
+        // RELEASE ride along inside its single Sync instead of costing a round
+        // trip each - measured at 51us for the pair that way against 511us as
+        // two separate round trips. The error path is unchanged either way:
+        // PostgreSQL discards everything between a failed statement and the
+        // Sync, so an inlined RELEASE never runs, and ROLLBACK TO goes out on
+        // its own below exactly as before.
+        const inlineSavepoint = canInlineSavepoint && rollbackOnError && intlCon.inTransaction;
+        if (rollbackOnError && intlCon.inTransaction && !inlineSavepoint)
             await intlCon.execute('SAVEPOINT ' + this._onErrorSavePoint);
         try {
-            const result = await this._execute(options);
+            const result = await fn(inlineSavepoint ? this._onErrorSavePoint : undefined);
             if (commitLast)
                 await intlCon.execute('COMMIT');
-            else if (rollbackOnError && intlCon.inTransaction) {
+            else if (rollbackOnError && intlCon.inTransaction && !inlineSavepoint) {
                 await intlCon.execute('RELEASE ' + this._onErrorSavePoint + ';');
             }
             return result;
@@ -112,7 +202,7 @@ export class PreparedStatement extends SafeEventEmitter {
     async cancel() {
         return getIntlConnection(this.connection).cancel();
     }
-    async _execute(options = {}) {
+    async _execute(options = {}, savepoint) {
         const intlCon = getIntlConnection(this.connection);
         if (options.cursor && this._fields) {
             intlCon.ref();
@@ -142,7 +232,7 @@ export class PreparedStatement extends SafeEventEmitter {
         // unnamed portal, reusing the RowDescription prepare() already fetched
         // instead of re-Describing (and re-Close-ing) a fresh named portal on
         // every call.
-        return intlCon.executeReused(this.name, this._fields, this.paramTypes, options.params, options);
+        return intlCon.executeReused(this.name, this._fields, this.paramTypes, options.params, options, savepoint);
     }
     /**
      * Called by Cursor.close() instead of separately awaiting

package/data-types/float4-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertCoercedNumber } from '../util/assert-integer.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
 export const Float4Type = {
     name: 'float4',
@@ -8,7 +9,7 @@ export const Float4Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeFloatBE(typeof v === 'number' ? v : parseFloat(v));
+        buf.writeFloatBE(typeof v === 'number' ? v : assertCoercedNumber(parseFloat(v), 'float4'));
     },
     decodeBinary(v, offset = 0) {
         return v.readFloatBE(offset);

package/data-types/float8-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertCoercedNumber } from '../util/assert-integer.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
 export const Float8Type = {
     name: 'float8',
@@ -9,7 +10,7 @@ export const Float8Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeDoubleBE(typeof v === 'number' ? v : parseFloat(v));
+        buf.writeDoubleBE(typeof v === 'number' ? v : assertCoercedNumber(parseFloat(v), 'float8'));
     },
     decodeBinary(v, offset = 0) {
         return v.readDoubleBE(offset);

package/data-types/int2-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertInteger } from '../util/assert-integer.js';
 import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
 export const Int2Type = {
     name: 'int2',
@@ -8,7 +9,7 @@ export const Int2Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeInt16BE(fastParseInt(v));
+        buf.writeInt16BE(assertInteger(fastParseInt(v), 'int2'));
     },
     decodeBinary(v, offset = 0) {
         return v.readInt16BE(offset);

package/data-types/int4-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertInteger } from '../util/assert-integer.js';
 import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
 export const Int4Type = {
     name: 'int4',
@@ -8,7 +9,7 @@ export const Int4Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeInt32BE(fastParseInt(v));
+        buf.writeInt32BE(assertInteger(fastParseInt(v), 'int4'));
     },
     decodeBinary(v, offset = 0) {
         return v.readInt32BE(offset);

package/data-types/int8-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertBigIntSource } from '../util/assert-integer.js';
 import { readBigInt64BE } from '../util/bigint-methods.js';
 import { fastParseIntBuffer } from '../util/fast-parseint.js';
 const maxSafeInteger = BigInt(Number.MAX_SAFE_INTEGER);
@@ -10,7 +11,7 @@ export const Int8Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeBigInt64BE(v);
+        buf.writeBigInt64BE(assertBigIntSource(v, 'int8'));
     },
     decodeBinary(buf, offset = 0) {
         const v = typeof buf.readBigInt64BE === 'function'

package/data-types/numeric-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertCoercedNumber } from '../util/assert-integer.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
 const NUMERIC_NEG = 0x4000;
 const NUMERIC_NAN = 0xc000;
@@ -37,6 +38,12 @@ export const NumericType = {
             return writeHeader(0, 0, NUMERIC_PINF, 0);
         if (str === '-Infinity')
             return writeHeader(0, 0, NUMERIC_NINF, 0);
+        // Anything with no numeric reading at all - `{}` stringifies to
+        // "[object Object]", `true` to "true" - would otherwise be walked
+        // digit by digit below and stored as 0.
+        // Number('') is 0, not NaN, so an empty string - what `[]` and `null`
+        // stringify to - would slip past the NaN check below.
+        assertCoercedNumber(str.length ? Number(str) : NaN, 'numeric');
         // Exponent form has no place in the wire format; go through Number to
         // get it back into plain notation. toFixed() cannot do this itself -
         // per spec it falls back to exponential notation once the magnitude

package/data-types/oid-type.js

@@ -1,4 +1,5 @@
 import { DataTypeNames, DataTypeOIDs } from '../constants.js';
+import { assertInteger } from '../util/assert-integer.js';
 import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
 export const OidType = {
     name: 'oid',
@@ -8,7 +9,7 @@ export const OidType = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeUInt32BE(fastParseInt(v));
+        buf.writeUInt32BE(assertInteger(fastParseInt(v), 'oid'));
     },
     decodeBinary(v, offset = 0) {
         return v.readUInt32BE(offset);

package/index.d.ts

@@ -8,13 +8,16 @@ export * from './connection/pool.js';
 export * from './connection/prepared-statement.js';
 export * from './constants.js';
 export * from './data-type-map.js';
+export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
+export * from './interfaces/copy-from-rows-options.js';
 export * from './interfaces/data-mapping-options.js';
 export * from './interfaces/data-type.js';
 export * from './interfaces/database-connection-params.js';
 export * from './interfaces/field-info.js';
 export * from './interfaces/function-call-options.js';
 export * from './interfaces/function-call-result.js';
+export * from './interfaces/pipeline-request.js';
 export * from './interfaces/query-options.js';
 export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';

package/index.js

@@ -8,13 +8,16 @@ export * from './connection/pool.js';
 export * from './connection/prepared-statement.js';
 export * from './constants.js';
 export * from './data-type-map.js';
+export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
+export * from './interfaces/copy-from-rows-options.js';
 export * from './interfaces/data-mapping-options.js';
 export * from './interfaces/data-type.js';
 export * from './interfaces/database-connection-params.js';
 export * from './interfaces/field-info.js';
 export * from './interfaces/function-call-options.js';
 export * from './interfaces/function-call-result.js';
+export * from './interfaces/pipeline-request.js';
 export * from './interfaces/query-options.js';
 export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';

package/interfaces/batch-result.d.ts

@@ -0,0 +1,42 @@
+import type { FieldInfo } from './field-info.js';
+/**
+ * What one parameter set in a batch produced. There is exactly one of
+ * these per set handed to `PreparedStatement.executeBatch()`, in the same
+ * order - the server answers each Execute with its own CommandComplete,
+ * so the mapping is positional and does not depend on the statement.
+ */
+export interface BatchCommandResult {
+    /** The command tag PostgreSQL reported for this set (INSERT/UPDATE/...). */
+    command?: string;
+    /** Rows affected, for INSERT/UPDATE/DELETE - as in QueryResult. */
+    rowsAffected?: number;
+    /**
+     * Rows this set returned, decoded the same way `execute()` decodes them
+     * (including any `rowDecoder` given in the options). Only present when
+     * the statement actually returns rows - a plain UPDATE without RETURNING
+     * leaves this undefined rather than setting it to an empty array.
+     */
+    rows?: any[];
+}
+/**
+ * The result of `PreparedStatement.executeBatch()`.
+ *
+ * `results` is always the full set of *completed* sets. On success that is
+ * every set that was submitted; when the server rejects one, the batch
+ * stops there (see the class doc) and the completed prefix is attached to
+ * the thrown error as `batchResults` instead.
+ */
+export interface BatchResult {
+    /** One entry per parameter set, in submission order. */
+    results: BatchCommandResult[];
+    /** Sum of every set's `rowsAffected`, for the common bulk-write case. */
+    totalRowsAffected: number;
+    /**
+     * Column descriptions, when the statement returns rows. One copy for the
+     * whole batch rather than per set: every set runs the same prepared
+     * statement, so the shape cannot differ between them.
+     */
+    fields?: FieldInfo[];
+    /** Wall time for the whole batch, when `timing` is enabled. */
+    executeTime?: number;
+}

package/interfaces/batch-result.js

@@ -0,0 +1 @@
+export {};

package/interfaces/copy-from-rows-options.d.ts

@@ -0,0 +1,58 @@
+import type { DataTypeMap } from '../data-type-map.js';
+import type { OID } from '../types.js';
+import type { DataMappingOptions } from './data-mapping-options.js';
+export interface CopyFromRowsOptions extends DataMappingOptions {
+    /** Type registry used to encode values; defaults to GlobalTypeMap. */
+    typeMap?: DataTypeMap;
+    /**
+     * Destination columns, in the order the rows supply them. Omitted means
+     * every column of the table, in table order - the same default `COPY
+     * table FROM STDIN` has without a column list.
+     */
+    columns?: string[];
+    /**
+     * Type OIDs for those columns, skipping the round trip that would
+     * otherwise ask the server for them.
+     *
+     * Only worth setting to avoid that probe on a hot path, and only when the
+     * OIDs are known to match the table: binary COPY does no conversion, so a
+     * wrong OID here is not a mismatch the server can reconcile - it either
+     * rejects the stream or, for two types that happen to share a width,
+     * stores the bytes as the wrong value.
+     */
+    columnTypes?: OID[];
+    /**
+     * Bytes to accumulate before sending a CopyData message. Defaults to
+     * 128KB; anything from 64KB to 256KB measures much the same, while a
+     * message per row is roughly ten times slower.
+     */
+    chunkSize?: number;
+    /**
+     * What to do with a value the destination column's type cannot encode -
+     * `'abc'` for an integer column, `{}` for a numeric one.
+     *
+     * `'throw'` (default) aborts the copy, naming the row and column. The
+     * other two exist for a load big enough that abandoning it over one bad
+     * record costs more than the record is worth: `'null'` writes NULL in
+     * that column and keeps the row, `'skip'` drops the row entirely. Both
+     * report how many they touched, so a tolerant load still says what it
+     * swallowed rather than looking clean.
+     *
+     * None of them apply to NaN or Infinity in a float or numeric column -
+     * PostgreSQL stores those as values distinct from NULL, so they encode
+     * normally and are never "invalid".
+     */
+    onInvalidValue?: 'throw' | 'null' | 'skip';
+}
+/** What `copyFromRows()` reports back. */
+export interface CopyFromRowsResult {
+    /** Rows actually sent to the server. */
+    rowCount: number;
+    /**
+     * Rows dropped under `onInvalidValue: 'skip'`. Always 0 otherwise, and a
+     * non-zero value here is the only sign a tolerant load lost anything.
+     */
+    skippedRows: number;
+    /** Values replaced with NULL under `onInvalidValue: 'null'`. */
+    nulledValues: number;
+}

package/interfaces/copy-from-rows-options.js

@@ -0,0 +1 @@
+export {};

package/interfaces/database-connection-params.d.ts

@@ -83,6 +83,31 @@ export interface DatabaseConnectionParams {
      * @default false
      */
     autoCommit?: boolean;
+    /**
+     * Reuse a server-side prepared statement for SQL this connection has run
+     * before, instead of parsing it again every time.
+     *
+     * On by default. A repeated query then costs Bind/Execute rather than
+     * Parse/Bind/Describe/Execute, which on fifty concurrent calls of one
+     * statement measured 0.97ms against 3.13ms.
+     *
+     * Turn it off when named prepared statements cannot survive between
+     * calls - the usual case being PgBouncer in transaction pooling mode
+     * before 1.21, which hands each transaction a different backend, so a
+     * statement prepared on one is missing on the next.
+     *
+     * @default true
+     */
+    prepare?: boolean;
+    /**
+     * How many prepared statements one connection keeps. The least recently
+     * used is closed when the limit is reached, so an application that
+     * builds SQL text dynamically cannot accumulate statements on the server
+     * without bound.
+     *
+     * @default 64
+     */
+    preparedStatementCacheSize?: number;
     /**
      * When on, if a statement in a transaction block generates an error,
      * the error is ignored and the transaction continues.

package/interfaces/pipeline-request.d.ts

@@ -0,0 +1,16 @@
+import type { Maybe, OID } from '../types.js';
+/**
+ * One statement in a `Connection.pipeline()` call. The `sql` tag's own
+ * output satisfies this shape, so a pipeline can be written straight from
+ * tagged templates without any conversion.
+ */
+export interface PipelineRequest {
+    sql: string;
+    params?: any[];
+    /**
+     * Parameter type OIDs for this statement. Per statement rather than per
+     * pipeline: the statements differ, so one shared list could only ever be
+     * right for one of them.
+     */
+    paramTypes?: Maybe<OID>[];
+}

package/interfaces/pipeline-request.js

@@ -0,0 +1 @@
+export {};

package/interfaces/query-options.d.ts

@@ -16,6 +16,12 @@ export interface QueryOptions extends DataMappingOptions {
      * @default false
      */
     objectRows?: boolean;
+    /**
+     * Overrides the connection's `prepare` setting for this call - `false`
+     * to keep a one-off statement out of the cache, `true` to use it on a
+     * connection that has caching off.
+     */
+    prepare?: boolean;
     /**
      * Controls how each row's raw column data is turned into the value handed back to the
      * caller. `'array'` and `'object'` select the built-in decoders (the same output

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
@@ -29,7 +29,10 @@
   },
   "homepage": "https://www.postgrejs.com/",
   "contributors": [
-    "Eray Hanoglu <e.hanoglu@panates.com>"
+    "Eray Hanoglu <e.hanoglu@panates.com>",
+    "Ilker Gurelli <i.gurelli@panates.com>",
+    "Onur Tokel <o.tokel@panates.com>",
+    "Bircan Yuruk <b.yuruk@panates.com>"
   ],
   "repository": {
     "type": "git",

package/protocol/database-error.d.ts

@@ -1,5 +1,21 @@
+import type { BatchCommandResult } from '../interfaces/batch-result.js';
 import { Protocol } from './protocol.js';
 export declare class DatabaseError extends Error {
+    /**
+     * Which entry of a multi-statement submission the server rejected -
+     * PreparedStatement.executeBatch()'s parameter sets, or the statements
+     * given to Connection.pipeline(). Entries after this index never ran:
+     * PostgreSQL discards everything between an error and the single Sync
+     * that closes such a submission.
+     */
+    failedIndex?: number;
+    /**
+     * The sets that had already completed when the batch failed, in
+     * submission order - only set by PreparedStatement.executeBatch(). They
+     * did run, but the batch shares one implicit transaction, so unless an
+     * explicit transaction was already open they are rolled back with it.
+     */
+    batchResults?: BatchCommandResult[];
     severity?: string;
     code?: string;
     detail?: string;