postgrejs 3.1.3 → 3.4.0

package/CHANGELOG.md

@@ -1,6 +1,84 @@
 ## Changelog
 
-### [v3.1.3](https://github.com/panates/postgrejs/compare/v3.1.2...v3.1.3) - 
+### [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
+
+- feat: add first-class Bun support with dedicated benchmark suite @Eray Hanoğlu 
+- feat: add pluggable RowDecoder for custom row decoding @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: return the actual instant when decoding timestamptz from binary @Eray Hanoğlu 
+- fix: point coverage badge at dev instead of the abandoned master branch @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: refresh both benchmark reports on 3.3.0 @Eray Hanoğlu 
+- docs: document Bun support and the Bun benchmark report in the README @Eray Hanoğlu 
+- docs: cover the Bun benchmarks in the README's speed section too @Eray Hanoğlu 
+- docs: document RowDecoder's data-immutability contract @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: decode timestamps from the wire bytes instead of a string @Eray Hanoğlu 
+- perf: build object rows from a compiled literal instead of per-column assignment @Eray Hanoğlu 
+- perf: decode float and numeric text without materialising a string @Eray Hanoğlu 
+- perf: decode PostgreSQL's own timestamp text shape without the engine parser @Eray Hanoğlu 
+- perf: write protocol messages immediately instead of deferring a tick @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- bench: report near-ties as ties instead of ranking them @Eray Hanoğlu 
+- feat!: give decodeBinary the value's length, not a slice of it @Eray Hanoğlu 
+- bench: stop measuring type-declaration policy in the Extended Query scenarios @Eray Hanoğlu 
+- bench: stop one stalled repeat from making every result a tie @Eray Hanoğlu 
+- bench: document why concurrent Simple Query varies its literal @Eray Hanoğlu 
+
+### [v3.2.0](https://github.com/panates/postgrejs/compare/v3.1.3...v3.2.0) -  12 September 2026 
+
+#### 🛠 Refactoring and Updates
+
+- refactor: build SmartBuffer/BufferReader on top of flexy-buffer @Eray Hanoğlu 
+
+### [v3.1.3](https://github.com/panates/postgrejs/compare/v3.1.2...v3.1.3) -  11 September 2026 
 
 #### 🪲 Fixes
 

package/README.md

@@ -12,7 +12,7 @@
 
 ## Why PostgreJS?
 
-**PostgreJS** is a PostgreSQL driver for Node.js built from the wire protocol up - no `libpq`, no native bindings,
+**PostgreJS** is a PostgreSQL driver for Node.js and Bun built from the wire protocol up - no `libpq`, no native bindings,
 just TypeScript talking directly to PostgreSQL. That from-scratch design is also what makes it fast and light: every
 byte on the wire is handled by code written for exactly that purpose, with a binary-first protocol, shared buffers,
 and row/column decoding pipelines built to avoid unnecessary allocation, instead of generic string plumbing bolted
@@ -22,11 +22,14 @@ 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 and
-**2x faster** than pg, 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 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.
+(postgres.js) on identical workloads - PostgreJS opens a connection up to **3x faster** than postgres.js, pushes
+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.
+
+The same suite runs under Bun, where Bun's own built-in `Bun.sql` joins the comparison as a fourth client - see
+[`doc/BENCHMARKS-bun.md`](doc/BENCHMARKS-bun.md).
 
 ### 🪶 Small Footprint
 
@@ -71,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.
@@ -81,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
@@ -111,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    |
@@ -143,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                   |           ✅           |          ❌           |        ✅        |
@@ -212,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
@@ -223,14 +276,27 @@ concurrency, each library run through its own idiomatic fast path. The numbers t
 machine via `npm run bench` against the repo's own
 `docker/docker-compose.yml` Postgres instance; see [`benchmark/README.md`](./benchmark/README.md) for details.
 
+The same suite runs under Bun via `npm run bench:bun`, where it also measures Bun's own built-in `Bun.sql` client as
+a fourth library. Those results live in [`doc/BENCHMARKS-bun.md`](doc/BENCHMARKS-bun.md) and are deliberately kept
+in a separate report rather than merged into the Node one: GC instrumentation, cursor streaming and binary-format
+control all differ enough between the two runtimes that a single table would conflate a library difference with a
+runtime difference.
+
+Both reports list libraries in a fixed order rather than fastest-first, and mark every result statistically tied
+with the leader rather than bolding a lone winner - several scenarios separate the leading drivers by about a
+percent, which is less than the run-to-run spread of the measurement itself.
+
 ## Support
 
 You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/postgrejs/issues) page When
 you open an issue please provide version of NodeJS and PostgreSQL server.
 
-## Node Compatibility
+## Runtime Compatibility
 
-- node >= 20.x
+- Node.js >= 20.x
+- Bun - the same test suite runs under Bun in CI against PostgreSQL 18 on every push, so Bun is a supported target
+  rather than an untested coincidence. (Coverage is collected on the Node matrix only: `c8` instruments V8's
+  coverage APIs, which JavaScriptCore doesn't have.)
 
 ## License
 
@@ -242,5 +308,5 @@ PostgreJS is available under the [BSD 3-Clause](LICENSE) license.
 [downloads-url]: https://npmjs.org/package/postgrejs
 [ci-test-image]: https://github.com/panates/postgrejs/actions/workflows/test.yml/badge.svg
 [ci-test-url]: https://github.com/panates/postgrejs/actions/workflows/test.yml
-[coveralls-image]: https://img.shields.io/coveralls/panates/postgrejs/master.svg
+[coveralls-image]: https://img.shields.io/coveralls/panates/postgrejs/dev.svg
 [coveralls-url]: https://coveralls.io/r/panates/postgrejs

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/cursor.d.ts

@@ -9,12 +9,13 @@ export declare class Cursor extends SafeEventEmitter implements AsyncDisposable
     private readonly _portal;
     private readonly _parsers;
     private readonly _queryOptions;
+    private readonly _rowDecoder;
     private _taskQueue;
     private _rows;
     private _closed;
     readonly fields: FieldInfo[];
     constructor(statement: PreparedStatement, portal: Portal, fields: FieldInfo[], parsers: AnyParseFunction[], queryOptions: QueryOptions);
-    get rowType(): 'array' | 'object';
+    get rowType(): 'array' | 'object' | 'custom';
     get isClosed(): boolean;
     next(): Promise<Maybe<Row>>;
     fetch(nRows: number): Promise<Row[]>;

package/connection/cursor.js

@@ -1,12 +1,13 @@
 import DoublyLinked from 'doublylinked';
 import { TaskQueue } from 'power-tasks';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import { parseObjectRow, parseRow } from '../util/parse-row.js';
+import { resolveRowDecoder, resolveRowType } from '../util/row-decoder.js';
 export class Cursor extends SafeEventEmitter {
     _statement;
     _portal;
     _parsers;
     _queryOptions;
+    _rowDecoder;
     _taskQueue = new TaskQueue({ concurrency: 1 });
     _rows = new DoublyLinked();
     _closed = false;
@@ -18,9 +19,10 @@ export class Cursor extends SafeEventEmitter {
         this._parsers = parsers;
         this._queryOptions = queryOptions;
         this.fields = fields;
+        this._rowDecoder = resolveRowDecoder(queryOptions);
     }
     get rowType() {
-        return this._queryOptions.objectRows ? 'object' : 'array';
+        return resolveRowType(this._queryOptions);
     }
     get isClosed() {
         return this._closed;
@@ -71,16 +73,14 @@ export class Cursor extends SafeEventEmitter {
             if (r && r.rows && r.rows.length) {
                 const rows = r.rows;
                 if (this._parsers) {
-                    const objectRows = queryOptions.objectRows;
                     const fields = this.fields;
                     const parsers = this._parsers;
+                    const rowDecoder = this._rowDecoder;
                     const rowLen = rows.length;
                     let i;
                     for (i = 0; i < rowLen; i++) {
                         const { data, columnCount } = rows[i];
-                        rows[i] = objectRows
-                            ? parseObjectRow(parsers, data, columnCount, this._queryOptions, fields)
-                            : parseRow(parsers, data, columnCount, this._queryOptions);
+                        rows[i] = rowDecoder.decode(parsers, data, columnCount, this._queryOptions, fields);
                     }
                 }
                 this._rows.push(...rows);