postgrejs 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -1,6 +1,60 @@
 ## Changelog
 
-### [v3.3.0](https://github.com/panates/postgrejs/compare/v3.2.0...v3.3.0) - 
+### [v3.5.0](https://github.com/panates/postgrejs/compare/v3.4.0...v3.5.0) - 
+
+#### 🚀 New Features
+
+- feat: add transaction(fn) and let a Cursor be iterated with for await @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: refresh Unit of Work after pipeline() started reusing statements @Eray Hanoğlu 
+- docs: record scoped transactions and cursor iteration in the README @Eray Hanoğlu 
+- docs: stop signing commits on the assistant's behalf @Eray Hanoğlu 
+- docs: note that pipeline() reuses cached prepared statements @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: let pipeline() bind to the connection's cached statements @Eray Hanoğlu 
+
+### [v3.4.0](https://github.com/panates/postgrejs/compare/v3.3.0...v3.4.0) -  16 September 2026 
+
+- 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,21 @@ 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.
-- **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
+- **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, iterable with `for await` a row
+  at a time and closed when the loop ends - by exhaustion, a `break`, or a throw.
+- **Scoped Transactions:** `transaction(fn)` commits when the callback returns and rolls back when it throws, on a
+  connection or straight from the pool. A call made while a transaction is already open takes a savepoint rather than
+  a second `BEGIN`, so a nested scope that fails rolls back its own work and leaves the outer transaction standing.
+- **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 +97,14 @@ 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. Statements the connection has run before bind to their cached
+  prepared names, so a repeated set sends no `Parse` at all - worth 2.5x on twenty statements.
 - **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 +133,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 +165,15 @@ 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     |
+| Scoped transaction helper <sup>26</sup> |     ✅ nests      |          ❌           |        ✅        |
+| 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 +239,43 @@ 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.
+- <sup>26</sup> Whether the library runs a callback inside a transaction for you, committing or rolling back on the way
+  out. PostgreJS has `transaction(fn)` on both a connection and the pool, and a call made inside one already open takes
+  a savepoint, so nesting needs nothing from the caller. postgres.js has `sql.begin(fn)` (`src/index.js`), where a
+  nested scope is opened explicitly with `sql.savepoint(fn)` instead. pg has no such helper in `lib/` - `BEGIN` and
+  `COMMIT` are statements the caller sends, and getting a transaction onto one connection is the caller's problem too.
 
 
 ## 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
@@ -185,6 +282,34 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * Starts a transaction
      */
     startTransaction(): Promise<void>;
+    /**
+     * Runs `fn` inside a transaction and commits when it returns, or rolls
+     * back and rethrows when it throws - the try/catch every caller of
+     * startTransaction()/commit()/rollback() ends up writing by hand.
+     *
+     * ```ts
+     * const id = await connection.transaction(async tx => {
+     *   const r = await tx.query(
+     *     'insert into orders (total) values ($1) returning id',
+     *     { params: [total] },
+     *   );
+     *   await tx.query('update stock set n = n - 1 where sku = $1', {
+     *     params: [sku],
+     *   });
+     *   return r.rows![0][0];
+     * });
+     * ```
+     *
+     * A call made while a transaction is already open becomes a savepoint
+     * rather than a second BEGIN, so an inner scope that fails rolls back
+     * its own work and leaves the outer transaction to decide what to do -
+     * instead of taking everything down with it, which is what a shared
+     * BEGIN/ROLLBACK pair would do.
+     *
+     * `fn` is handed this same connection: every statement it runs on it is
+     * inside the transaction, and one it runs on another connection is not.
+     */
+    transaction<T>(fn: (connection: this) => Promise<T>): Promise<T>;
     /**
      * Commits current transaction.
      * @param immediate - Commits right away, ignoring how many nested
@@ -286,6 +411,15 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * microtask tick on top of the one `promise`/`.catch()` already goes
      * through - paid on every single query this wraps, disabled or not.
      */
+    /**
+     * The nested half of transaction(): a savepoint of its own, released on
+     * success and rolled back to on failure.
+     *
+     * The `inTransaction` checks are re-read rather than assumed - `fn` is
+     * free to commit or roll back the outer transaction itself, and there is
+     * no savepoint left to release once it has.
+     */
+    private _savepointScope;
     protected _captureErrorStack<T>(promise: Promise<T>, entry?: (...args: any[]) => any, asyncErrorHandling?: boolean): Promise<T>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/connection/connection.js

@@ -8,6 +8,8 @@ import { IntlConnection } from './intl-connection.js';
 import { LargeObject, LargeObjectMode } from './large-object.js';
 import { PreparedStatement } from './prepared-statement.js';
 const CAPTURE_STACK_TRACE_LIMIT = 5;
+/** Names the savepoint a nested transaction() scope takes. */
+let transactionScopeCounter = 0;
 export class Connection extends SafeEventEmitter {
     _pool;
     _intlCon;
@@ -251,6 +253,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')) {
@@ -344,6 +479,50 @@ export class Connection extends SafeEventEmitter {
     startTransaction() {
         return this._captureErrorStack(this._intlCon.startTransaction());
     }
+    /**
+     * Runs `fn` inside a transaction and commits when it returns, or rolls
+     * back and rethrows when it throws - the try/catch every caller of
+     * startTransaction()/commit()/rollback() ends up writing by hand.
+     *
+     * ```ts
+     * const id = await connection.transaction(async tx => {
+     *   const r = await tx.query(
+     *     'insert into orders (total) values ($1) returning id',
+     *     { params: [total] },
+     *   );
+     *   await tx.query('update stock set n = n - 1 where sku = $1', {
+     *     params: [sku],
+     *   });
+     *   return r.rows![0][0];
+     * });
+     * ```
+     *
+     * A call made while a transaction is already open becomes a savepoint
+     * rather than a second BEGIN, so an inner scope that fails rolls back
+     * its own work and leaves the outer transaction to decide what to do -
+     * instead of taking everything down with it, which is what a shared
+     * BEGIN/ROLLBACK pair would do.
+     *
+     * `fn` is handed this same connection: every statement it runs on it is
+     * inside the transaction, and one it runs on another connection is not.
+     */
+    async transaction(fn) {
+        if (this._intlCon.inTransaction)
+            return await this._savepointScope(fn);
+        await this.startTransaction();
+        try {
+            const result = await fn(this);
+            await this.commit();
+            return result;
+        }
+        catch (e) {
+            // A rollback that fails in turn must not replace the error that
+            // caused it: the connection is already in trouble, and the original
+            // is what the caller needs to see.
+            await this.rollback().catch(() => undefined);
+            throw e;
+        }
+    }
     /**
      * Commits current transaction.
      * @param immediate - Commits right away, ignoring how many nested
@@ -456,11 +635,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);
             });
         }
@@ -556,6 +741,32 @@ export class Connection extends SafeEventEmitter {
      * microtask tick on top of the one `promise`/`.catch()` already goes
      * through - paid on every single query this wraps, disabled or not.
      */
+    /**
+     * The nested half of transaction(): a savepoint of its own, released on
+     * success and rolled back to on failure.
+     *
+     * The `inTransaction` checks are re-read rather than assumed - `fn` is
+     * free to commit or roll back the outer transaction itself, and there is
+     * no savepoint left to release once it has.
+     */
+    async _savepointScope(fn) {
+        const name = 'txscope' + ++transactionScopeCounter;
+        await this._captureErrorStack(this._intlCon.execute('SAVEPOINT ' + name));
+        try {
+            const result = await fn(this);
+            if (this._intlCon.inTransaction)
+                await this._intlCon.execute('RELEASE SAVEPOINT ' + name);
+            return result;
+        }
+        catch (e) {
+            if (this._intlCon.inTransaction) {
+                await this._intlCon
+                    .execute('ROLLBACK TO SAVEPOINT ' + name + '; RELEASE SAVEPOINT ' + name)
+                    .catch(() => undefined);
+            }
+            throw e;
+        }
+    }
     _captureErrorStack(promise, entry, asyncErrorHandling) {
         const enabled = asyncErrorHandling ?? this._intlCon.config.asyncErrorHandling ?? true;
         if (!enabled)

package/connection/cursor.d.ts

@@ -21,5 +21,13 @@ export declare class Cursor extends SafeEventEmitter implements AsyncDisposable
     fetch(nRows: number): Promise<Row[]>;
     close(): Promise<void>;
     private _fetchRows;
+    /**
+     * Iterates the remaining rows, fetching a batch at a time, and closes
+     * the cursor when the loop ends - whether it ran out of rows, broke
+     * early, or the body threw. Nothing is decoded ahead of what is asked
+     * for, so this streams a result larger than memory the same way next()
+     * does one row at a time.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<Row>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/connection/cursor.js

@@ -92,6 +92,23 @@ export class Cursor extends SafeEventEmitter {
         })
             .toPromise();
     }
+    /**
+     * Iterates the remaining rows, fetching a batch at a time, and closes
+     * the cursor when the loop ends - whether it ran out of rows, broke
+     * early, or the body threw. Nothing is decoded ahead of what is asked
+     * for, so this streams a result larger than memory the same way next()
+     * does one row at a time.
+     */
+    async *[Symbol.asyncIterator]() {
+        try {
+            let row;
+            while ((row = await this.next()) !== undefined)
+                yield row;
+        }
+        finally {
+            await this.close();
+        }
+    }
     [Symbol.asyncDispose]() {
         return this.close();
     }