postgrejs 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 ## Changelog
 
-### [v3.3.0](https://github.com/panates/postgrejs/compare/v3.2.0...v3.3.0) - 
+### [v3.4.0](https://github.com/panates/postgrejs/compare/v3.3.0...v3.4.0) - 
+
+- feat: add PreparedStatement.executeBatch() for multi-set execution
+
+#### 🚀 New Features
+
+- feat: add copyFromRows() for binary COPY bulk loading @Eray Hanoğlu 
+- feat: add Connection.pipeline() for many statements in one round trip @Eray Hanoğlu 
+- feat: reuse prepared statements for repeated queries @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: refuse values that have no numeric reading instead of storing zero @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: regenerate both benchmark reports from an interleaved run @Eray Hanoğlu 
+- docs: refresh the Node report and correct a stale asymmetry note @Eray Hanoğlu 
+- docs: record statement-level rollback in the README @Eray Hanoğlu 
+- docs: record the prepared statement cache in the README @Eray Hanoğlu 
+- docs: list pipeline() in the feature list and comparison table @Eray Hanoğlu 
+- docs: list binary COPY in the feature list and comparison table @Eray Hanoğlu 
+- docs: list batch execution in the feature list and comparison table @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: carry the rollbackOnError savepoint in the statement's own round trip @Eray Hanoğlu 
+- perf: let the prepared statement cache serve queries inside a transaction @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- bench: add Bulk Load scenarios for text and binary COPY @Eray Hanoğlu 
+- bench: add Unit of Work scenario for pipeline() @Eray Hanoğlu 
+- bench: stop measuring postgres.js on an unprepared path @Eray Hanoğlu 
+- bench: interleave repeats instead of running them back to back @Eray Hanoğlu 
+- ci: pin GITHUB_TOKEN to read-only in the test and qc workflows @Eray Hanoğlu 
+
+### [v3.3.0](https://github.com/panates/postgrejs/compare/v3.2.0...v3.3.0) -  14 September 2026 
 
 #### 🚀 New Features
 

package/README.md

@@ -23,8 +23,8 @@ onto a client meant for text.
 The numbers back it up. In PostgreJS's own benchmark suite - run head-to-head against
 [`pg`](https://github.com/brianc/node-postgres) (node-postgres) and [`postgres`](https://github.com/porsager/postgres)
 (postgres.js) on identical workloads - PostgreJS opens a connection up to **3x faster** than postgres.js, pushes
-pooled queries through up to **6.6x faster** than postgres.js, and fetches large result sets nearly **5x faster**
-than pg. It's also the only one of the three Node drivers with a complete binary wire protocol across every data
+pooled queries through up to **6.5x faster** than pg, and fetches large result sets nearly **5x faster** than pg
+too. It's also the only one of the three Node drivers with a complete binary wire protocol across every data
 type, rather than falling back to text for most of them. See [`doc/BENCHMARKS.md`](doc/BENCHMARKS.md) for the full
 methodology and every scenario.
 
@@ -74,8 +74,17 @@ usage.
   resource management.
 - **Binary Wire Protocol:** Implements the full binary wire protocol for all PostgreSQL data types, ensuring robust and
   efficient data handling.
-- **Prepared Statements:** Named prepared statements for optimized query execution.
+- **Prepared Statements:** Named prepared statements for optimized query execution, and a per-connection cache that
+  reuses one automatically for SQL the connection has run before - a repeated query costs `Bind`/`Execute` instead of
+  parsing again, worth 3.2x on fifty concurrent calls and 2.9x again on a query inside an open transaction. On by
+  default, `prepare: false` to opt out.
+- **Statement-Level Rollback:** Inside a transaction each statement runs under a savepoint of its own, so a failed
+  statement leaves the transaction usable instead of aborting the whole block. The `SAVEPOINT`/`RELEASE` pair travels
+  in the statement's own round trip rather than costing one each - 36µs for the pair, against 507µs sent separately.
+  `rollbackOnError: false` to opt out.
 - **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
+- **Batch Execution:** `executeBatch()` runs one prepared statement over many parameter sets under a single `Sync`,
+  reporting each set's row count - 1000 updates in 20ms where the same calls pipelined individually take 188ms.
 - **Notifications:**  High-level implementation for PostgreSQL notifications (LISTEN/NOTIFY), enabling real-time data
   updates.
 - **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements.
@@ -84,8 +93,13 @@ usage.
 - **Performance Optimization:**  Low memory utilization and boosted performance through the use of shared buffers.
 - **Authorization:** Supports various password algorithms including Clear text, MD5, and SASL, ensuring secure
   authentication.
-- **Bulk Import/Export:** `COPY TO STDOUT` and `COPY FROM STDIN` as Node streams, with backpressure in both directions.
+- **Bulk Import/Export:** `COPY TO STDOUT` and `COPY FROM STDIN` as Node streams, with backpressure in both directions,
+  plus `copyFromRows()`, which encodes rows straight into binary `COPY` - around 4x faster than the CSV equivalent and
+  no text escaping to get wrong. Takes arrays or objects from anything iterable, so a file larger than memory streams in.
 - **Query Pipelining:** Pooled queries can share connections so a burst is not capped by pool size - opt-in per call.
+  `pipeline()` goes further for a known set of statements: several different ones travel under a single `Sync`, so they
+  cost one round trip instead of one each and commit or roll back together - around 2x faster than the same calls
+  through `Promise.all()`, which is already pipelined.
 - **Dynamic SQL:** A `sql` tag builds statements from composable fragments - values become parameters, names are quoted,
   and `sql.values()`/`sql.set()` write INSERT and UPDATE clauses from objects.
 - **Multiple Hosts:** A connection can list several servers and pick one by role
@@ -114,7 +128,7 @@ usage.
 
 How PostgreJS compares to [`pg`](https://github.com/brianc/node-postgres) (node-postgres) and
 [`postgres`](https://github.com/porsager/postgres) (postgres.js). Every row was checked against the libraries' own
-source rather than their documentation — versions compared: **PostgreJS 3.1.0, pg 8.23.0, postgres.js 3.4.9**. ✅ built
+source rather than their documentation — versions compared: **PostgreJS 3.4.0, pg 8.23.0, postgres.js 3.4.9**. ✅ built
 in · 🟡 partial or needs a separate package · ❌ not supported.
 
 | Feature                           |       PostgreJS        |          pg           |   postgres.js    |
@@ -146,10 +160,14 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | ***Querying***                    |                        |                       |                  |
 | Query parameters                  |           ✅           |          ✅           |        ✅        |
 | Parameter type casting            |           ✅           |   🟡 <sup>10</sup>    |        ✅        |
-| Prepared statements               |      ✅ explicit       |          ✅           |   ✅ automatic   |
+| Prepared statements <sup>24</sup> |     ✅ automatic      |      ✅ manual       |   ✅ automatic   |
+| Statement-level rollback <sup>25</sup> |     ✅ automatic      |          ❌           |    🟡 manual     |
+| Batch execution <sup>21</sup>     |           ✅           |          ❌           |        ❌        |
+| Multi-statement round trip <sup>23</sup> |     ✅     |          ❌           |        ❌        |
 | Multi-statement scripts           |           ✅           |          ✅           |        ✅        |
 | Server-side cursors               |           ✅           |   🟡 <sup>11</sup>    |        ✅        |
 | `COPY TO` / `COPY FROM`           |           ✅           |   🟡 <sup>12</sup>    |        ✅        |
+| Binary COPY encoding <sup>22</sup> |           ✅           |          ❌           |        ❌        |
 | Row count after a COPY            |           ✅           |          ✅           |        ❌        |
 | ***Transaction management***      |                        |                       |                  |
 | Transaction API                   |           ✅           |          ❌           |        ✅        |
@@ -215,6 +233,38 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
   documentation lists what stops working with it: `pg-cursor`, `pg-query-stream` and
   `pg-copy-streams` all "operate directly on the binary stream and therefore are
   incompatible" - so server-side cursors, row streaming and COPY are what it costs.
+- <sup>21</sup> One statement executed over many parameter sets behind a single `Sync`, each set's row count reported
+  separately. pg and postgres.js both emit a `Sync` per execution (`syncBuffer` in pg's `connection.js`, the
+  concatenated `ExecuteUnnamed` in postgres.js's), so a burst of executions costs a server round of implicit-transaction
+  bookkeeping each, pipelined or not. Writing one multi-row statement by hand is a separate approach that all three
+  support, and both PostgreJS and postgres.js ship value builders for it - it is faster still where it applies, but it
+  is one statement rather than many, and PostgreSQL's 65535-parameter ceiling bounds it.
+- <sup>22</sup> Turning JavaScript rows into the binary `COPY` format, rather than carrying a payload the caller
+  formatted first. All three can carry a `COPY` stream, but only as bytes: postgres.js hands back a `Writable` that
+  wraps raw chunks in `CopyData`, and pg reaches the same point through `pg-copy-streams`. Producing the format needs a
+  binary encoder per type, which neither driver has - see Binary encoders above, where the same gap shows up for query
+  parameters. The capability is still reachable with pg through a third package, `pg-copy-streams-binary`, which brings
+  its own encoders; postgres.js has no equivalent.
+- <sup>23</sup> Several different statements sent under one `Sync`, so they cost a single round of the server's
+  transaction bookkeeping rather than one each, arrive as one implicit transaction, and come back as per-statement
+  results. Distinct from the Pipelining row above, which is about not waiting between queries: all three do that, and
+  all three still close every statement with its own `Sync` - pg sends one immediately after each Execute
+  (`query.js`), and postgres.js concatenates Execute and Sync into a single constant (`ExecuteUnnamed`). Atomicity on
+  its own is reachable anywhere with an explicit `BEGIN`/`COMMIT`; what that cannot recover is the round trip, since
+  the per-statement Syncs and two extra statements remain.
+- <sup>24</sup> Whether a repeated query is parsed again every time. PostgreJS and postgres.js both keep a per-connection
+  cache keyed on the SQL and reuse a server-side statement, so a repeat costs `Bind`/`Execute` rather than
+  `Parse`/`Bind`/`Describe`/`Execute`; pg prepares only the statements you name yourself (`query.js`: "named queries
+  must always be prepared"), with nothing caching by SQL text. The two automatic ones differ in when they start:
+  postgres.js on first sight, PostgreJS on the second use, which leaves a genuinely one-shot query at its unprepared
+  cost. Both default to on and both take `prepare: false`, which matters for PgBouncer in transaction pooling mode
+  before 1.21, where a named statement does not survive to the next call.
+- <sup>25</sup> Whether one failed statement inside a transaction leaves the rest of the block runnable. PostgreJS puts
+  every statement under a savepoint of its own by default (`rollbackOnError`), rolling back to it when the statement
+  fails, and carries the `SAVEPOINT`/`RELEASE` pair inside the statement's own round trip rather than paying a round
+  trip for each. postgres.js has savepoints, but as a scope the caller opens around a callback (`savepoint(name, fn)`
+  in `src/index.js`), so a statement is protected only where someone wrapped it; pg has no savepoint handling in
+  `lib/` at all, so a failed statement leaves the block aborted until the caller rolls back themselves.
 
 
 ## Benchmarks

package/connection/connection.d.ts

@@ -1,7 +1,9 @@
 import { ConnectionState } from '../constants.js';
+import type { CopyFromRowsOptions, CopyFromRowsResult } from '../interfaces/copy-from-rows-options.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
 import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
 import type { FunctionCallResult } from '../interfaces/function-call-result.js';
+import type { PipelineRequest } from '../interfaces/pipeline-request.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
 import type { QueryResult } from '../interfaces/query-result.js';
 import type { ScriptExecuteOptions } from '../interfaces/script-execute-options.js';
@@ -11,6 +13,7 @@ import type { DatabaseError } from '../protocol/database-error.js';
 import type { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { Maybe, OID } from '../types.js';
+import type { CopyRowSource } from '../util/copy-from-rows.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import type { CopyFromStream, CopyToStream } from './copy-stream.js';
 import { IntlConnection } from './intl-connection.js';
@@ -136,6 +139,100 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      *
      * @param sql {string} - A COPY ... FROM STDIN statement
      */
+    /**
+     * Bulk-loads rows into a table with `COPY ... FROM STDIN (FORMAT binary)`,
+     * encoding every value with its own type's binary encoder instead of
+     * making the caller format a text payload.
+     *
+     * ```ts
+     * const { rowCount } = await connection.copyFromRows('users', [
+     *   [1, 'John', 10.5],
+     *   [2, 'Jane', 20.0],
+     * ], { columns: ['id', 'name', 'amount'] });
+     * ```
+     *
+     * Rows may be positional arrays or objects read by column name, and the
+     * source may be anything iterable - including an async iterable or a
+     * Readable, so a file far larger than memory streams straight in:
+     *
+     * ```ts
+     * await connection.copyFromRows('users', (async function* () {
+     *   for await (const { value } of jsonRows) yield [value.id, value.name];
+     * })(), { columns: ['id', 'name'] });
+     * ```
+     *
+     * Rows are pulled rather than pushed, so the source only produces the
+     * next row once the previous chunk has reached the socket - backpressure
+     * is the loop pausing, not a queue growing.
+     *
+     * Binary is both faster and cheaper to produce than text: 200,000 rows of
+     * int4/text/float8/timestamptz measured 232ms against 483ms for the
+     * equivalent CSV `copyFrom()`, client-side encoding included, because
+     * writing an int32 costs less than formatting a decimal string.
+     *
+     * Column types are read from the server (one Describe round trip) unless
+     * `columnTypes` supplies them. They have to be exact - binary COPY does
+     * no conversion - which is also why a column whose type has no binary
+     * encoder is rejected before any row is sent rather than mid-stream.
+     *
+     * `copyFrom()` remains the way to send an already-formatted text or CSV
+     * payload.
+     *
+     * A value the column's type cannot encode - `'abc'` for an integer
+     * column - aborts the copy by default, naming the row and column;
+     * `onInvalidValue` can instead null the value or drop the row, and the
+     * result says how many that happened to. NaN and Infinity in a float or
+     * numeric column are not invalid: PostgreSQL stores them as values
+     * distinct from NULL, so they go through untouched.
+     *
+     * @returns Rows sent, plus what a tolerant `onInvalidValue` swallowed.
+     */
+    /**
+     * Runs several different statements in one round trip: every
+     * Parse/Bind/Describe/Execute goes out before any response is waited
+     * for, and a single Sync closes the lot.
+     *
+     * ```ts
+     * const [renamed, , total] = await connection.pipeline([
+     *   sql`update users set name = ${name} where id = ${id}`,
+     *   sql`insert into audit(msg) values (${msg})`,
+     *   sql`select count(*)::int as n from users`,
+     * ]);
+     * renamed.rowsAffected;  // 1
+     * total.rows?.[0];       // [42]
+     * ```
+     *
+     * The counterpart to `PreparedStatement.executeBatch()`, which runs one
+     * statement over many parameter sets; this runs many statements once
+     * each. Twenty statements measured 2.3ms against 5.0ms for the same
+     * calls through `Promise.all()`, which PostgreJS already pipelines -
+     * what the single Sync removes is the server finishing an implicit
+     * transaction and answering ReadyForQuery twenty times over, which is
+     * why socket reads drop from twenty to one.
+     *
+     * Three things follow from that framing rather than from choices made
+     * above it:
+     *
+     * - **One transaction.** Unless an explicit transaction is already open,
+     *   the statements commit or roll back together.
+     * - **A failing statement stops the rest.** PostgreSQL discards
+     *   everything between an error and the Sync, so statements after a
+     *   rejected one never run. The error carries `failedIndex`.
+     * - **No statement can see another's results.** They are all sent before
+     *   any reply arrives, so anything conditional on an earlier result
+     *   belongs in a separate call rather than here.
+     *
+     * Results map to statements by position. Statements that return rows get
+     * them decoded as `query()` would, `rowDecoder` included; `fetchCount`
+     * does not apply, since a portal suspended mid-pipeline would break that
+     * mapping.
+     *
+     * @param requests Statements to run, as `sql` tag output, plain SQL
+     *   strings, or `{ sql, params }` objects.
+     * @param options Applied to every statement.
+     */
+    pipeline(requests: (string | QueryRequest | PipelineRequest)[], options?: QueryOptions): Promise<QueryResult[]>;
+    copyFromRows(table: string, source: CopyRowSource, options?: CopyFromRowsOptions): Promise<CopyFromRowsResult>;
     copyFrom(sql: string): Promise<CopyFromStream>;
     /**
      * Creates a PreparedStatement instance

package/connection/connection.js

@@ -251,6 +251,139 @@ export class Connection extends SafeEventEmitter {
      *
      * @param sql {string} - A COPY ... FROM STDIN statement
      */
+    /**
+     * Bulk-loads rows into a table with `COPY ... FROM STDIN (FORMAT binary)`,
+     * encoding every value with its own type's binary encoder instead of
+     * making the caller format a text payload.
+     *
+     * ```ts
+     * const { rowCount } = await connection.copyFromRows('users', [
+     *   [1, 'John', 10.5],
+     *   [2, 'Jane', 20.0],
+     * ], { columns: ['id', 'name', 'amount'] });
+     * ```
+     *
+     * Rows may be positional arrays or objects read by column name, and the
+     * source may be anything iterable - including an async iterable or a
+     * Readable, so a file far larger than memory streams straight in:
+     *
+     * ```ts
+     * await connection.copyFromRows('users', (async function* () {
+     *   for await (const { value } of jsonRows) yield [value.id, value.name];
+     * })(), { columns: ['id', 'name'] });
+     * ```
+     *
+     * Rows are pulled rather than pushed, so the source only produces the
+     * next row once the previous chunk has reached the socket - backpressure
+     * is the loop pausing, not a queue growing.
+     *
+     * Binary is both faster and cheaper to produce than text: 200,000 rows of
+     * int4/text/float8/timestamptz measured 232ms against 483ms for the
+     * equivalent CSV `copyFrom()`, client-side encoding included, because
+     * writing an int32 costs less than formatting a decimal string.
+     *
+     * Column types are read from the server (one Describe round trip) unless
+     * `columnTypes` supplies them. They have to be exact - binary COPY does
+     * no conversion - which is also why a column whose type has no binary
+     * encoder is rejected before any row is sent rather than mid-stream.
+     *
+     * `copyFrom()` remains the way to send an already-formatted text or CSV
+     * payload.
+     *
+     * A value the column's type cannot encode - `'abc'` for an integer
+     * column - aborts the copy by default, naming the row and column;
+     * `onInvalidValue` can instead null the value or drop the row, and the
+     * result says how many that happened to. NaN and Infinity in a float or
+     * numeric column are not invalid: PostgreSQL stores them as values
+     * distinct from NULL, so they go through untouched.
+     *
+     * @returns Rows sent, plus what a tolerant `onInvalidValue` swallowed.
+     */
+    /**
+     * Runs several different statements in one round trip: every
+     * Parse/Bind/Describe/Execute goes out before any response is waited
+     * for, and a single Sync closes the lot.
+     *
+     * ```ts
+     * const [renamed, , total] = await connection.pipeline([
+     *   sql`update users set name = ${name} where id = ${id}`,
+     *   sql`insert into audit(msg) values (${msg})`,
+     *   sql`select count(*)::int as n from users`,
+     * ]);
+     * renamed.rowsAffected;  // 1
+     * total.rows?.[0];       // [42]
+     * ```
+     *
+     * The counterpart to `PreparedStatement.executeBatch()`, which runs one
+     * statement over many parameter sets; this runs many statements once
+     * each. Twenty statements measured 2.3ms against 5.0ms for the same
+     * calls through `Promise.all()`, which PostgreJS already pipelines -
+     * what the single Sync removes is the server finishing an implicit
+     * transaction and answering ReadyForQuery twenty times over, which is
+     * why socket reads drop from twenty to one.
+     *
+     * Three things follow from that framing rather than from choices made
+     * above it:
+     *
+     * - **One transaction.** Unless an explicit transaction is already open,
+     *   the statements commit or roll back together.
+     * - **A failing statement stops the rest.** PostgreSQL discards
+     *   everything between an error and the Sync, so statements after a
+     *   rejected one never run. The error carries `failedIndex`.
+     * - **No statement can see another's results.** They are all sent before
+     *   any reply arrives, so anything conditional on an earlier result
+     *   belongs in a separate call rather than here.
+     *
+     * Results map to statements by position. Statements that return rows get
+     * them decoded as `query()` would, `rowDecoder` included; `fetchCount`
+     * does not apply, since a portal suspended mid-pipeline would break that
+     * mapping.
+     *
+     * @param requests Statements to run, as `sql` tag output, plain SQL
+     *   strings, or `{ sql, params }` objects.
+     * @param options Applied to every statement.
+     */
+    async pipeline(requests, options = {}) {
+        if (!Array.isArray(requests))
+            throw new TypeError('pipeline() requires an array of statements');
+        if (options.cursor)
+            throw new Error('pipeline() cannot return a cursor - every statement runs to ' +
+                'completion under one Sync, so there is no portal left to fetch from');
+        if (!requests.length)
+            return [];
+        const normalized = requests.map(r => typeof r === 'string' ? { sql: r } : { sql: r.sql, params: r.params });
+        /* c8 ignore start */
+        if (this.listenerCount('debug')) {
+            this.emit('debug', {
+                location: 'Connection.pipeline',
+                connection: this,
+                message: `[${this.processID}] pipeline | ${normalized.length} statements`,
+            });
+        }
+        /* c8 ignore stop */
+        return await this._captureErrorStack(this._intlCon.executePipeline(normalized, options)).catch((e) => {
+            // Name the statement the server actually rejected, not the first
+            // one - the error is otherwise attributed to whichever SQL happens
+            // to be handy, which in a pipeline is the wrong statement.
+            const i = e.failedIndex;
+            throw this._handleError(e, i != null && normalized[i] ? normalized[i].sql : normalized[0].sql);
+        });
+    }
+    async copyFromRows(table, source, options) {
+        /* c8 ignore start */
+        if (this.listenerCount('debug')) {
+            this.emit('debug', {
+                location: 'Connection.copyFromRows',
+                connection: this,
+                message: `[${this.processID}] copyFromRows | ${table}`,
+                table,
+            });
+        }
+        /* c8 ignore stop */
+        return await this._captureErrorStack(this._intlCon.copyFromRows(table, source, options)).catch((e) => {
+            throw this._handleError(e, `COPY ${table} FROM STDIN (FORMAT binary)`);
+        });
+    }
     async copyFrom(sql) {
         /* c8 ignore start */
         if (this.listenerCount('debug')) {
@@ -456,11 +589,17 @@ export class Connection extends SafeEventEmitter {
         const effectiveAutoCommit = options?.autoCommit != null
             ? options.autoCommit
             : this._intlCon.config.autoCommit;
+        // An open transaction takes this path too: queryCached() puts the
+        // rollbackOnError savepoint in the statement's own round trip rather
+        // than leaving it to the prepare()/execute()/close() route below. The
+        // one thing it cannot express is an explicit autoCommit:true while a
+        // transaction is open - "commit once this statement is done" - which
+        // stays with PreparedStatement's own wrapper.
         if (!options?.cursor &&
             effectiveAutoCommit !== false &&
-            !this._intlCon.inTransaction) {
+            !(options?.autoCommit === true && this._intlCon.inTransaction)) {
             const params = options?.params?.map(prm => prm instanceof BindParam ? prm.value : prm);
-            return await this._captureErrorStack(this._intlCon.queryOnce(sql, paramTypes, params, options || {}), this.query, options?.asyncErrorHandling).catch((e) => {
+            return await this._captureErrorStack(this._intlCon.queryCached(sql, paramTypes, params, options || {}), this.query, options?.asyncErrorHandling).catch((e) => {
                 throw this._handleError(e, sql);
             });
         }

package/connection/intl-connection.d.ts

@@ -1,5 +1,9 @@
 import { ConnectionState } from '../constants.js';
+import type { DataTypeMap } from '../data-type-map.js';
+import type { BatchResult } from '../interfaces/batch-result.js';
+import type { CopyFromRowsOptions, CopyFromRowsResult } from '../interfaces/copy-from-rows-options.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { FieldInfo } from '../interfaces/field-info.js';
 import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
 import type { FunctionCallResult } from '../interfaces/function-call-result.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
@@ -9,10 +13,25 @@ import type { ScriptResult } from '../interfaces/script-result.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import type { Maybe, OID } from '../types.js';
+import type { AnyParseFunction, Maybe, OID } from '../types.js';
+import { type CopyRowSource } from '../util/copy-from-rows.js';
 import type { Connection } from './connection.js';
 import { CopyFromStream, CopyToStream } from './copy-stream.js';
 export declare class IntlConnection extends SafeEventEmitter {
+    /**
+     * Server-side prepared statements this connection has built, keyed by
+     * the SQL text and its parameter OIDs - both, because the OIDs are part
+     * of what was parsed, not just how it is bound.
+     *
+     * A Map, relied on for its insertion order: re-inserting on every hit
+     * makes the first entry the least recently used, which is what gets
+     * closed when the cache is full. Statements belong to the session, so
+     * this is per connection and dies with it.
+     */
+    private _preparedCache;
+    /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
+    private _preparedCandidates;
+    private _preparedCounter;
     private _executeReusedParserCache;
     protected _refCount: number;
     protected _transactionDepth: number;
@@ -136,6 +155,21 @@ export declare class IntlConnection extends SafeEventEmitter {
      * Runs a COPY ... FROM STDIN and hands back a stream to feed it.
      * Resolves once the server is ready for data.
      */
+    /**
+     * Streams rows into a table with `COPY ... FROM STDIN (FORMAT binary)`,
+     * encoding each value with its own type's binary encoder.
+     *
+     * Binary COPY performs no conversion server-side, so the destination
+     * column types have to be known exactly. They are read from the server
+     * unless the caller supplies them: a Describe of `select <columns> from
+     * <table> where false` against the unnamed statement returns a
+     * RowDescription carrying each column's OID, which costs one round trip
+     * and leaves nothing to close (the next Parse replaces the unnamed
+     * statement). Letting PostgreSQL resolve the name is the reason to do it
+     * this way rather than reading the catalog here - schemas, quoting,
+     * search_path and views then behave exactly as they will for the COPY.
+     */
+    copyFromRows(table: string, source: CopyRowSource, options?: CopyFromRowsOptions): Promise<CopyFromRowsResult>;
     copyFrom(sql: string): Promise<CopyFromStream>;
     protected _execute(sql: string, options?: ScriptExecuteOptions, cb?: (event: string, ...args: any[]) => void): Promise<ScriptResult>;
     /**
@@ -145,7 +179,43 @@ export declare class IntlConnection extends SafeEventEmitter {
      * +close()'s 7 round trips whenever there's no cursor and no explicit/
      * active transaction to wrap (see Connection.query() for that gating).
      */
-    queryOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * Runs a one-shot extended query, reusing a server-side prepared
+     * statement when this connection has run the same SQL before.
+     *
+     * A repeated query then costs Bind/Execute instead of
+     * Parse/Bind/Describe/Execute, which the server can answer without
+     * planning again - fifty concurrent calls of one statement measured
+     * 0.97ms against 3.13ms, and socket reads dropped from 38 to 8.
+     *
+     * Nothing is prepared on first sight: SQL has to be seen
+     * PREPARE_AFTER_USES times before it earns a name, so a query that runs
+     * once costs exactly what it costs today.
+     *
+     * A cached statement can be invalidated under us - `alter table` between
+     * two calls makes PostgreSQL answer 0A000, "cached plan must not change
+     * result type". That is caught here: the entry is dropped and the query
+     * runs again unprepared, so a migration against a live connection
+     * recovers instead of failing every call from then on.
+     */
+    queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * The savepoint rollbackOnError calls for, or undefined when this call
+     * needs none: outside a transaction there is nothing to roll back to,
+     * and a statement that is itself a transaction command manages its own
+     * boundaries (wrapping COMMIT in a savepoint would be nonsense).
+     */
+    protected _inlineSavepointFor(sql: string, options: QueryOptions): Maybe<string>;
+    protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>): Promise<QueryResult>;
+    /** Closes the least recently used statement once the cache is full. */
+    protected _evictPreparedIfFull(): Promise<void>;
+    /**
+     * Closes an evicted statement server-side. Close answers CloseComplete
+     * but no ReadyForQuery, so the Sync goes separately and both are awaited
+     * together - the same shape PreparedStatement._close() uses.
+     */
+    protected _closePreparedStatement(name: string): Promise<void>;
+    queryOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint?: string): Promise<QueryResult>;
     /**
      * Parse+Describe(statement)+Sync as a single round trip - used by
      * PreparedStatement.prepare() instead of a separately-awaited Parse then
@@ -164,7 +234,47 @@ export declare class IntlConnection extends SafeEventEmitter {
      * the RowDescription fields prepareOnce() already fetched instead of
      * re-Describing a fresh portal on every call.
      */
-    executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * Parsers and wrapped field descriptions for a statement whose
+     * RowDescription prepare() already fetched, memoised per RowDescription
+     * so repeated executes of the same statement don't rebuild them.
+     * Shared by executeReused() and executeBatchReused().
+     */
+    protected _resolveReusedParsers(cachedFields: Protocol.RowDescription[], typeMap: DataTypeMap, options: QueryOptions): {
+        parsers: AnyParseFunction[];
+        resultFields: FieldInfo[];
+    };
+    /**
+     * Executes one prepared statement once per parameter set, as a single
+     * Bind/Execute stream closed by one Sync (see
+     * PgSocket.sendBatchBindExecuteMessages() for the wire shape and what
+     * the single Sync implies).
+     *
+     * Sets map to results positionally: the server answers each Execute with
+     * its own CommandComplete, and rows that arrive before one belong to the
+     * set it closes. When the server rejects a set, everything behind it is
+     * discarded unexecuted - the completed prefix is attached to the thrown
+     * error as `batchResults`, and the rejected set's index as `failedIndex`,
+     * so a caller can tell how far the batch actually got.
+     */
+    /**
+     * Runs several different statements as one Parse/Bind/Describe/Execute
+     * stream closed by a single Sync (see PgSocket.sendPipelineMessages() for
+     * the wire shape and what that framing implies).
+     *
+     * The counterpart to executeBatchReused(): that one runs a single
+     * prepared statement over many parameter sets, this one runs many
+     * statements once each. Results map to statements positionally - the
+     * server answers each Execute with its own CommandComplete, and any rows
+     * that arrive before one belong to the statement it closes.
+     */
+    executePipeline(requests: {
+        sql: string;
+        params?: any[];
+        paramTypes?: Maybe<OID>[];
+    }[], options: QueryOptions): Promise<QueryResult[]>;
+    executeBatchReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, paramSets: Maybe<any>[][], options: QueryOptions): Promise<BatchResult>;
+    executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint?: string): Promise<QueryResult>;
     emit(event: string | symbol, ...args: any[]): boolean;
     protected _onError(err: Error): void;
 }