postgrejs 3.3.0 → 3.5.0

package/protocol/database-error.js

@@ -1,5 +1,20 @@
 import { Protocol } from './protocol.js';
 export 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;
+    /**
+     * 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;
     severity;
     code;
     detail;

package/protocol/pg-socket.d.ts

@@ -93,6 +93,37 @@ export declare class PgSocket extends SafeEventEmitter {
         bind: Frontend.BindMessageArgs;
         describe: Frontend.DescribeMessageArgs;
         execute: Frontend.ExecuteMessageArgs;
+        before?: string;
+        after?: string;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Parse + Bind + Describe(portal) + Execute per statement, then a SINGLE
+     * Sync for the lot - the wire shape behind Connection.pipeline().
+     *
+     * The same framing as sendBatchBindExecuteMessages(), and the same
+     * consequences, except that each statement carries its own Parse rather
+     * than reusing one prepared statement: the statements share one implicit
+     * transaction, and PostgreSQL discards everything between an error and
+     * the Sync, so a rejected statement stops the ones behind it.
+     *
+     * Describe is not optional here even though nothing caches its answer.
+     * Without it the server sends DataRows for a row-returning statement with
+     * no RowDescription in front of them, leaving the column names and types
+     * unknown - the reason the one-shot path in sendExtendedQueryMessages()
+     * includes it too. It costs about a quarter of a millisecond across
+     * twenty statements, measured.
+     *
+     * Every Execute is unlimited (fetchCount 0): a portal that suspended
+     * mid-pipeline would answer PortalSuspended instead of CommandComplete
+     * and desynchronise the positional statement-to-result mapping.
+     */
+    sendPipelineMessages(args: {
+        statements: {
+            parse?: Frontend.ParseMessageArgs;
+            bind: Frontend.BindMessageArgs;
+            describe?: Frontend.DescribeMessageArgs;
+            execute: Frontend.ExecuteMessageArgs;
+        }[];
     }, cb: CaptureCallback): Promise<any>;
     /**
      * Parse + Describe(statement) + Sync as a single round trip - used by
@@ -117,6 +148,33 @@ export declare class PgSocket extends SafeEventEmitter {
     sendBindExecuteMessages(args: {
         bind: Frontend.BindMessageArgs;
         execute: Frontend.ExecuteMessageArgs;
+        before?: string;
+        after?: string;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * One Bind+Execute pair per parameter set against the same prepared
+     * statement, then a SINGLE Sync for the lot - the wire shape behind
+     * PreparedStatement.executeBatch().
+     *
+     * The single Sync is the whole point, and it is also what gives the
+     * batch its semantics. Sending Bind/Execute/Sync per set (what N
+     * separate execute() calls do, even pipelined) makes the server finish
+     * an implicit transaction and answer ReadyForQuery every time; one Sync
+     * at the end collapses that to one, which is where the bulk of the
+     * speedup comes from. It also means the sets share one implicit
+     * transaction, and that PostgreSQL discards everything between an error
+     * and the Sync - so a set that fails stops the ones behind it from
+     * running at all. Both of those are inherent to this framing rather
+     * than choices made above it.
+     *
+     * Every Execute here must be unlimited (fetchCount 0): a portal that
+     * suspends mid-batch would answer PortalSuspended instead of
+     * CommandComplete and desynchronise the positional set-to-result
+     * mapping the caller relies on.
+     */
+    sendBatchBindExecuteMessages(args: {
+        binds: Frontend.BindMessageArgs[];
+        execute: Frontend.ExecuteMessageArgs;
     }, cb: CaptureCallback): Promise<any>;
     /**
      * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
@@ -193,6 +251,24 @@ export declare class PgSocket extends SafeEventEmitter {
      * "start listening" step to race or misuse.
      */
     private _sendAndCapture;
+    /**
+     * Parse + Bind + Execute for a parameterless utility statement, appended
+     * to a message list that is about to be closed by one Sync - how
+     * sendBindExecuteMessages() and sendExtendedQueryMessages() carry their
+     * `before`/`after` SQL (today, SAVEPOINT and RELEASE) in the same round
+     * trip as the statement itself rather than as a round trip each.
+     *
+     * Everything here goes through the unnamed statement and the unnamed
+     * portal. That is safe in this order: the caller's own Bind names a
+     * prepared statement rather than the unnamed one, and PostgreSQL
+     * processes the messages in sequence, so each Bind only ever discards an
+     * unnamed portal whose Execute has already run.
+     *
+     * No Describe: neither statement returns rows, so there is no
+     * RowDescription worth asking for. Result formats come from the caller's
+     * own Bind args, which likewise cost nothing against no columns.
+     */
+    private _pushUtilityStatement;
     protected _removeListeners(): void;
     protected _reset(): void;
     protected _handleConnect(): void;

package/protocol/pg-socket.js

@@ -238,15 +238,67 @@ export class PgSocket extends SafeEventEmitter {
      * statement/portal at the next Parse/Bind referencing the unnamed name.
      */
     sendExtendedQueryMessages(args, cb) {
-        const data = [
-            this._frontend.getParseMessage(args.parse),
-            this._frontend.getBindMessage(args.bind),
-            this._frontend.getDescribeMessage(args.describe),
-            this._frontend.getExecuteMessage(args.execute),
-            this._frontend.getSyncMessage(),
-        ];
+        if (!args.before && !args.after) {
+            const data = [
+                this._frontend.getParseMessage(args.parse),
+                this._frontend.getBindMessage(args.bind),
+                this._frontend.getDescribeMessage(args.describe),
+                this._frontend.getExecuteMessage(args.execute),
+                this._frontend.getSyncMessage(),
+            ];
+            return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
+        }
+        const data = [];
+        if (args.before)
+            this._pushUtilityStatement(data, args.before, args.bind);
+        data.push(this._frontend.getParseMessage(args.parse), this._frontend.getBindMessage(args.bind), this._frontend.getDescribeMessage(args.describe), this._frontend.getExecuteMessage(args.execute));
+        if (args.after)
+            this._pushUtilityStatement(data, args.after, args.bind);
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
     }
+    /**
+     * Parse + Bind + Describe(portal) + Execute per statement, then a SINGLE
+     * Sync for the lot - the wire shape behind Connection.pipeline().
+     *
+     * The same framing as sendBatchBindExecuteMessages(), and the same
+     * consequences, except that each statement carries its own Parse rather
+     * than reusing one prepared statement: the statements share one implicit
+     * transaction, and PostgreSQL discards everything between an error and
+     * the Sync, so a rejected statement stops the ones behind it.
+     *
+     * Describe is not optional here even though nothing caches its answer.
+     * Without it the server sends DataRows for a row-returning statement with
+     * no RowDescription in front of them, leaving the column names and types
+     * unknown - the reason the one-shot path in sendExtendedQueryMessages()
+     * includes it too. It costs about a quarter of a millisecond across
+     * twenty statements, measured.
+     *
+     * Every Execute is unlimited (fetchCount 0): a portal that suspended
+     * mid-pipeline would answer PortalSuspended instead of CommandComplete
+     * and desynchronise the positional statement-to-result mapping.
+     */
+    sendPipelineMessages(args, cb) {
+        const l = args.statements.length;
+        const data = [];
+        let i;
+        let st;
+        for (i = 0; i < l; i++) {
+            st = args.statements[i];
+            // Parse and Describe are both optional: a statement bound to one the
+            // connection has already prepared needs neither, since the server
+            // still holds the plan and IntlConnection still holds the
+            // RowDescription that came with it.
+            if (st.parse)
+                data.push(this._frontend.getParseMessage(st.parse));
+            data.push(this._frontend.getBindMessage(st.bind));
+            if (st.describe)
+                data.push(this._frontend.getDescribeMessage(st.describe));
+            data.push(this._frontend.getExecuteMessage(st.execute));
+        }
+        data.push(this._frontend.getSyncMessage());
+        return this._sendAndCapture(data, cb, 'sendPipelineMessages', args);
+    }
     /**
      * Parse + Describe(statement) + Sync as a single round trip - used by
      * PreparedStatement.prepare() instead of a separate awaited Parse then a
@@ -272,13 +324,56 @@ export class PgSocket extends SafeEventEmitter {
      * auto-clears an unnamed portal at the next Bind naming it.
      */
     sendBindExecuteMessages(args, cb) {
-        const data = [
-            this._frontend.getBindMessage(args.bind),
-            this._frontend.getExecuteMessage(args.execute),
-            this._frontend.getSyncMessage(),
-        ];
+        if (!args.before && !args.after) {
+            const data = [
+                this._frontend.getBindMessage(args.bind),
+                this._frontend.getExecuteMessage(args.execute),
+                this._frontend.getSyncMessage(),
+            ];
+            return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
+        }
+        const data = [];
+        if (args.before)
+            this._pushUtilityStatement(data, args.before, args.bind);
+        data.push(this._frontend.getBindMessage(args.bind), this._frontend.getExecuteMessage(args.execute));
+        if (args.after)
+            this._pushUtilityStatement(data, args.after, args.bind);
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
     }
+    /**
+     * One Bind+Execute pair per parameter set against the same prepared
+     * statement, then a SINGLE Sync for the lot - the wire shape behind
+     * PreparedStatement.executeBatch().
+     *
+     * The single Sync is the whole point, and it is also what gives the
+     * batch its semantics. Sending Bind/Execute/Sync per set (what N
+     * separate execute() calls do, even pipelined) makes the server finish
+     * an implicit transaction and answer ReadyForQuery every time; one Sync
+     * at the end collapses that to one, which is where the bulk of the
+     * speedup comes from. It also means the sets share one implicit
+     * transaction, and that PostgreSQL discards everything between an error
+     * and the Sync - so a set that fails stops the ones behind it from
+     * running at all. Both of those are inherent to this framing rather
+     * than choices made above it.
+     *
+     * Every Execute here must be unlimited (fetchCount 0): a portal that
+     * suspends mid-batch would answer PortalSuspended instead of
+     * CommandComplete and desynchronise the positional set-to-result
+     * mapping the caller relies on.
+     */
+    sendBatchBindExecuteMessages(args, cb) {
+        const binds = args.binds;
+        const l = binds.length;
+        const data = new Array(l * 2 + 1);
+        let i;
+        for (i = 0; i < l; i++) {
+            data[i * 2] = this._frontend.getBindMessage(binds[i]);
+            data[i * 2 + 1] = this._frontend.getExecuteMessage(args.execute);
+        }
+        data[l * 2] = this._frontend.getSyncMessage();
+        return this._sendAndCapture(data, cb, 'sendBatchBindExecuteMessages', args);
+    }
     /**
      * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
      * Portal.bindAndRetrieveFields()'s doc comment for why a Sync here would
@@ -405,6 +500,29 @@ export class PgSocket extends SafeEventEmitter {
             }
         });
     }
+    /**
+     * Parse + Bind + Execute for a parameterless utility statement, appended
+     * to a message list that is about to be closed by one Sync - how
+     * sendBindExecuteMessages() and sendExtendedQueryMessages() carry their
+     * `before`/`after` SQL (today, SAVEPOINT and RELEASE) in the same round
+     * trip as the statement itself rather than as a round trip each.
+     *
+     * Everything here goes through the unnamed statement and the unnamed
+     * portal. That is safe in this order: the caller's own Bind names a
+     * prepared statement rather than the unnamed one, and PostgreSQL
+     * processes the messages in sequence, so each Bind only ever discards an
+     * unnamed portal whose Execute has already run.
+     *
+     * No Describe: neither statement returns rows, so there is no
+     * RowDescription worth asking for. Result formats come from the caller's
+     * own Bind args, which likewise cost nothing against no columns.
+     */
+    _pushUtilityStatement(data, sql, bind) {
+        data.push(this._frontend.getParseMessage({ sql }), this._frontend.getBindMessage({
+            typeMap: bind.typeMap,
+            queryOptions: bind.queryOptions,
+        }), this._frontend.getExecuteMessage({}));
+    }
     _removeListeners() {
         if (!this._socket)
             return;

package/util/assert-integer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Returns `v` coerced to an integer, or throws when it cannot be one.
+ *
+ * `fastParseInt()` already answers NaN for a value with no integer reading
+ * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
+ * stores a silent zero, so the answer is lost exactly where it matters.
+ * Nothing downstream can tell that apart from a real zero afterwards: the
+ * row inserts, the copy succeeds, and the wrong number is in the table.
+ *
+ * Floats are deliberately not rejected: truncating 3.7 to 3 is the
+ * long-standing behaviour of these encoders and is usually what a caller
+ * writing into an integer column means. Only "this is not a number at all"
+ * is refused.
+ *
+ * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
+ * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
+ * supported server version.
+ */
+export declare function assertInteger(v: number, typeName: string): number;
+/**
+ * Returns `parsed` when a value that was NOT already a number coerced to
+ * one, and throws when it did not.
+ *
+ * Kept apart from assertInteger() because the two families disagree about
+ * NaN on purpose. float4/float8/numeric all store NaN as a value distinct
+ * from NULL, so a caller passing the number NaN means it and it never
+ * reaches here - the encoders take `typeof v === 'number'` straight
+ * through. What does reach here is `'abc'`, `{}` or `true`, whose coercion
+ * produced NaN because they have no numeric reading at all; writing those
+ * as NaN would be indistinguishable afterwards from a NaN that was meant.
+ */
+export declare function assertCoercedNumber(parsed: number, typeName: string): number;
+/**
+ * Refuses a value that only has an integer reading through a coercion
+ * nobody asked for.
+ *
+ * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
+ * happy to convert things that are not numbers at all: `BigInt([])` is 0n
+ * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
+ * bad value in a bigint column would land as a plausible-looking 0 or 1,
+ * so only the types that genuinely carry an integer are let through.
+ */
+export declare function assertBigIntSource(v: any, typeName: string): bigint | number;

package/util/assert-integer.js

@@ -0,0 +1,58 @@
+/**
+ * Returns `v` coerced to an integer, or throws when it cannot be one.
+ *
+ * `fastParseInt()` already answers NaN for a value with no integer reading
+ * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
+ * stores a silent zero, so the answer is lost exactly where it matters.
+ * Nothing downstream can tell that apart from a real zero afterwards: the
+ * row inserts, the copy succeeds, and the wrong number is in the table.
+ *
+ * Floats are deliberately not rejected: truncating 3.7 to 3 is the
+ * long-standing behaviour of these encoders and is usually what a caller
+ * writing into an integer column means. Only "this is not a number at all"
+ * is refused.
+ *
+ * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
+ * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
+ * supported server version.
+ */
+export function assertInteger(v, typeName) {
+    if (Number.isNaN(v)) {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    return v;
+}
+/**
+ * Returns `parsed` when a value that was NOT already a number coerced to
+ * one, and throws when it did not.
+ *
+ * Kept apart from assertInteger() because the two families disagree about
+ * NaN on purpose. float4/float8/numeric all store NaN as a value distinct
+ * from NULL, so a caller passing the number NaN means it and it never
+ * reaches here - the encoders take `typeof v === 'number'` straight
+ * through. What does reach here is `'abc'`, `{}` or `true`, whose coercion
+ * produced NaN because they have no numeric reading at all; writing those
+ * as NaN would be indistinguishable afterwards from a NaN that was meant.
+ */
+export function assertCoercedNumber(parsed, typeName) {
+    if (Number.isNaN(parsed)) {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no numeric value`);
+    }
+    return parsed;
+}
+/**
+ * Refuses a value that only has an integer reading through a coercion
+ * nobody asked for.
+ *
+ * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
+ * happy to convert things that are not numbers at all: `BigInt([])` is 0n
+ * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
+ * bad value in a bigint column would land as a plausible-looking 0 or 1,
+ * so only the types that genuinely carry an integer are let through.
+ */
+export function assertBigIntSource(v, typeName) {
+    const t = typeof v;
+    if (t === 'bigint' || t === 'number' || t === 'string')
+        return v;
+    throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+}

package/util/copy-from-rows.d.ts

@@ -0,0 +1,56 @@
+import type { Readable } from 'node:stream';
+import type { CopyFromRowsOptions } from '../interfaces/copy-from-rows-options.js';
+import type { OID } from '../types.js';
+/** Default bytes accumulated before a CopyData message goes out. */
+export declare const DEFAULT_COPY_CHUNK_SIZE: number;
+export type CopyRow = any[] | Record<string, any>;
+export type CopyRowSource = Iterable<CopyRow> | AsyncIterable<CopyRow> | Readable;
+/**
+ * Quotes a possibly schema-qualified name. A single dot separates schema
+ * from table, which is what PostgreSQL's own client tools assume for a name
+ * given as one string; a table whose name genuinely contains a dot has to
+ * be reached through a view or a plain (unqualified) name instead.
+ */
+export declare function quoteQualifiedName(name: string): string;
+/**
+ * The statement whose RowDescription tells us the destination columns'
+ * type OIDs. `where false` keeps the server from producing rows for a
+ * Describe that is never followed by an Execute, and letting PostgreSQL
+ * resolve the name is the point: schemas, quoting, search_path and views
+ * all behave exactly as they will for the COPY itself, which parsing the
+ * name here could only approximate.
+ */
+export declare function buildProbeSql(table: string, columns?: string[]): string;
+export declare function buildCopySql(table: string, columns?: string[]): string;
+export interface CopyFromRowsContext {
+    columns: string[];
+    dataTypeIds: OID[];
+    options: CopyFromRowsOptions;
+    /**
+     * Sends one CopyData message, resolving once the socket has taken it -
+     * immediately when it had room, and only after it drains when it did
+     * not. Awaiting this is what makes backpressure reach the source: the
+     * `for await` below cannot ask for another row until it settles.
+     */
+    write: (chunk: Buffer) => Promise<void>;
+}
+/**
+ * Encodes `source` into binary COPY chunks and hands them to `write`,
+ * accumulating rows until a chunk is worth sending.
+ *
+ * The chunk size is the difference between this being fast and being
+ * pointless: one CopyData per row costs a message header and a socket write
+ * each time, which measured 1208ms against 129ms at 64KB for the same
+ * 200,000 rows. Sizes from 64KB to 256KB all land near the floor, so the
+ * default sits inside that range rather than at either edge.
+ *
+ * Pulls from `source` rather than being pushed into, so an async iterable -
+ * which every Readable is - only produces the next row once the previous
+ * chunk has been accepted, making backpressure the caller's own loop
+ * pausing rather than an unbounded queue here.
+ */
+export declare function writeCopyBinaryRows(source: CopyRowSource, ctx: CopyFromRowsContext): Promise<{
+    rowCount: number;
+    skippedRows: number;
+    nulledValues: number;
+}>;

package/util/copy-from-rows.js

@@ -0,0 +1,95 @@
+import { GlobalTypeMap } from '../data-type-map.js';
+import { SmartBuffer } from '../protocol/smart-buffer.js';
+import { assertCopyBinaryEncodable, COPY_BINARY_HEADER, COPY_BINARY_TRAILER, encodeCopyBinaryRow, } from './encode-copy-binary.js';
+import { escapeIdentifier } from './escape-identifier.js';
+/** Default bytes accumulated before a CopyData message goes out. */
+export const DEFAULT_COPY_CHUNK_SIZE = 128 * 1024;
+/**
+ * Quotes a possibly schema-qualified name. A single dot separates schema
+ * from table, which is what PostgreSQL's own client tools assume for a name
+ * given as one string; a table whose name genuinely contains a dot has to
+ * be reached through a view or a plain (unqualified) name instead.
+ */
+export function quoteQualifiedName(name) {
+    const dot = name.indexOf('.');
+    return dot < 0
+        ? escapeIdentifier(name)
+        : escapeIdentifier(name.slice(0, dot)) +
+            '.' +
+            escapeIdentifier(name.slice(dot + 1));
+}
+/**
+ * The statement whose RowDescription tells us the destination columns'
+ * type OIDs. `where false` keeps the server from producing rows for a
+ * Describe that is never followed by an Execute, and letting PostgreSQL
+ * resolve the name is the point: schemas, quoting, search_path and views
+ * all behave exactly as they will for the COPY itself, which parsing the
+ * name here could only approximate.
+ */
+export function buildProbeSql(table, columns) {
+    const cols = columns?.length ? columns.map(escapeIdentifier).join(', ') : '*';
+    return `select ${cols} from ${quoteQualifiedName(table)} where false`;
+}
+export function buildCopySql(table, columns) {
+    const cols = columns?.length
+        ? ' (' + columns.map(escapeIdentifier).join(', ') + ')'
+        : '';
+    return (`copy ${quoteQualifiedName(table)}${cols} ` +
+        `from stdin with (format binary)`);
+}
+/** Positional array, or an object read by column name. */
+function toValues(row, columns) {
+    if (Array.isArray(row))
+        return row;
+    const l = columns.length;
+    const out = new Array(l);
+    let i;
+    for (i = 0; i < l; i++)
+        out[i] = row[columns[i]];
+    return out;
+}
+/**
+ * Encodes `source` into binary COPY chunks and hands them to `write`,
+ * accumulating rows until a chunk is worth sending.
+ *
+ * The chunk size is the difference between this being fast and being
+ * pointless: one CopyData per row costs a message header and a socket write
+ * each time, which measured 1208ms against 129ms at 64KB for the same
+ * 200,000 rows. Sizes from 64KB to 256KB all land near the floor, so the
+ * default sits inside that range rather than at either edge.
+ *
+ * Pulls from `source` rather than being pushed into, so an async iterable -
+ * which every Readable is - only produces the next row once the previous
+ * chunk has been accepted, making backpressure the caller's own loop
+ * pausing rather than an unbounded queue here.
+ */
+export async function writeCopyBinaryRows(source, ctx) {
+    const { columns, dataTypeIds, options } = ctx;
+    const typeMap = options.typeMap || GlobalTypeMap;
+    assertCopyBinaryEncodable(dataTypeIds, columns, typeMap);
+    const chunkSize = options.chunkSize || DEFAULT_COPY_CHUNK_SIZE;
+    const io = new SmartBuffer();
+    io.start();
+    io.writeBytes(COPY_BINARY_HEADER);
+    const onInvalidValue = options.onInvalidValue || 'throw';
+    let rowCount = 0;
+    let skippedRows = 0;
+    const stats = { nulled: 0 };
+    let index = 0;
+    for await (const row of source) {
+        const written = encodeCopyBinaryRow(io, toValues(row, columns), dataTypeIds, columns, typeMap, options, index, onInvalidValue, stats);
+        index++;
+        if (!written) {
+            skippedRows++;
+            continue;
+        }
+        rowCount++;
+        if (io.size >= chunkSize) {
+            await ctx.write(io.flush());
+            io.start();
+        }
+    }
+    io.writeBytes(COPY_BINARY_TRAILER);
+    await ctx.write(io.flush());
+    return { rowCount, skippedRows, nulledValues: stats.nulled };
+}

package/util/encode-copy-binary.d.ts

@@ -0,0 +1,48 @@
+import type { DataTypeMap } from '../data-type-map.js';
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import type { SmartBuffer } from '../protocol/smart-buffer.js';
+import type { OID } from '../types.js';
+/**
+ * `PGCOPY\n\377\r\n\0` followed by two int32 words: a flags field and the
+ * length of a header extension area. Bit 16 of the flags marks a stream
+ * that carries an OID per row - an obsolete variant PostgreSQL still reads
+ * but nothing should write - so both words are zero here.
+ */
+export declare const COPY_BINARY_HEADER: Buffer<ArrayBuffer>;
+/** A field count of -1 where a row would start, ending the stream. */
+export declare const COPY_BINARY_TRAILER: Buffer<ArrayBuffer>;
+/**
+ * Appends one row to `io` in PostgreSQL's binary COPY format: an int16
+ * field count, then per field an int32 byte length followed by that many
+ * bytes, with -1 standing in for NULL.
+ *
+ * Each value is written by its own type's `encodeBinary`, which is the same
+ * function a binary query parameter goes through (see Frontend's Bind) -
+ * both are the type's `send` representation, so there is one encoder per
+ * type rather than a COPY-specific set.
+ *
+ * Binary COPY performs no conversion on the server: the bytes have to be
+ * exactly what the destination column's type expects. `dataTypeIds` must
+ * therefore be the column's own OIDs, which is why the caller obtains them
+ * from the server rather than inferring them from the JavaScript values.
+ *
+ * @param rowIndex Only used to say which row failed, since a value that
+ *   cannot be encoded otherwise surfaces from the server as an opaque
+ *   "incorrect binary data format" naming neither row nor column.
+ * @returns Whether the row was written - false only under `'skip'`, where
+ *   the partial row has already been unwound.
+ */
+export declare function encodeCopyBinaryRow(io: SmartBuffer, values: any[], dataTypeIds: OID[], columnNames: string[], typeMap: DataTypeMap, options: DataMappingOptions, rowIndex: number, onInvalidValue?: 'throw' | 'null' | 'skip', 
+/** Incremented per value replaced under `'null'`; counted here rather
+ * than inferred by the caller, which cannot see inside a written row. */
+stats?: {
+    nulled: number;
+}): boolean;
+/**
+ * Fails before a single byte goes out when any column's type cannot be
+ * written in binary. Worth doing up front: once the server has answered
+ * CopyInResponse it is waiting for a complete stream, so discovering an
+ * unencodable column at row 900,000 means aborting a copy that was already
+ * most of the way done.
+ */
+export declare function assertCopyBinaryEncodable(dataTypeIds: OID[], columnNames: string[], typeMap: DataTypeMap): void;