postgrejs 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 ## Changelog
 
-### [v3.4.0](https://github.com/panates/postgrejs/compare/v3.3.0...v3.4.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
 

package/README.md

@@ -82,7 +82,11 @@ usage.
   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.
+- **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
@@ -99,7 +103,8 @@ usage.
 - **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.
+  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
@@ -162,6 +167,7 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Parameter type casting            |           ✅           |   🟡 <sup>10</sup>    |        ✅        |
 | 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           |           ✅           |          ✅           |        ✅        |
@@ -265,6 +271,11 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
   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

@@ -282,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
@@ -383,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;
@@ -477,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
@@ -695,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();
     }

package/connection/intl-connection.d.ts

@@ -207,6 +207,11 @@ export declare class IntlConnection extends SafeEventEmitter {
      */
     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>;
+    /**
+     * Counts one more use of this SQL and says whether it has now been seen
+     * often enough to be worth preparing under a name.
+     */
+    protected _earnsAName(key: string): boolean;
     /** Closes the least recently used statement once the cache is full. */
     protected _evictPreparedIfFull(): Promise<void>;
     /**

package/connection/intl-connection.js

@@ -41,6 +41,14 @@ const PREPARE_AFTER_USES = 2;
  * SQL that manages transaction boundaries itself, and so must never be
  * wrapped in a savepoint or an implicit BEGIN/COMMIT of ours.
  */
+/**
+ * What the prepared statement cache is keyed on. The parameter OIDs are
+ * part of it because the server fixes them at Parse: the same SQL bound
+ * with different types is a different plan.
+ */
+function preparedCacheKey(sql, paramTypes) {
+    return paramTypes?.length ? sql + '\u0000' + paramTypes.join(',') : sql;
+}
 const TRANSACTION_COMMAND_PATTERN = /^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i;
 export class IntlConnection extends SafeEventEmitter {
     /**
@@ -627,9 +635,7 @@ export class IntlConnection extends SafeEventEmitter {
         const enabled = options.prepare ?? this.config.prepare ?? true;
         if (!enabled)
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
-        const key = paramTypes?.length
-            ? sql + '\u0000' + paramTypes.join(',')
-            : sql;
+        const key = preparedCacheKey(sql, paramTypes);
         const cached = this._preparedCache.get(key);
         if (cached) {
             // Re-insert to mark it most recently used.
@@ -653,12 +659,8 @@ export class IntlConnection extends SafeEventEmitter {
                 return result;
             }
         }
-        const uses = (this._preparedCandidates.get(key) || 0) + 1;
-        if (uses < PREPARE_AFTER_USES) {
-            this._preparedCandidates.set(key, uses);
+        if (!this._earnsAName(key))
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
-        }
-        this._preparedCandidates.delete(key);
         const name = 'C_' + ++this._preparedCounter;
         // A Parse that fails caches nothing and reports itself; the statement
         // is simply never reused. It runs outside the savepoint, as the
@@ -669,6 +671,19 @@ export class IntlConnection extends SafeEventEmitter {
         this._preparedCache.set(key, entry);
         return this.executeReused(name, entry.fields, paramTypes, params, options, savepoint);
     }
+    /**
+     * Counts one more use of this SQL and says whether it has now been seen
+     * often enough to be worth preparing under a name.
+     */
+    _earnsAName(key) {
+        const uses = (this._preparedCandidates.get(key) || 0) + 1;
+        if (uses < PREPARE_AFTER_USES) {
+            this._preparedCandidates.set(key, uses);
+            return false;
+        }
+        this._preparedCandidates.delete(key);
+        return true;
+    }
     /** Closes the least recently used statement once the cache is full. */
     async _evictPreparedIfFull() {
         const max = this.config.preparedStatementCacheSize ?? 64;
@@ -914,94 +929,174 @@ export class IntlConnection extends SafeEventEmitter {
             const timingEnabled = options.timing ?? this.config.timing ?? false;
             const startTime = timingEnabled ? performance.now() : 0;
             const rowDecoder = resolveRowDecoder(options);
-            const columnFormat = options.columnFormat != null
-                ? options.columnFormat
-                : DEFAULT_COLUMN_FORMAT;
             const results = [];
             let pendingFields;
             let pendingRows;
             let error;
-            const statements = requests.map(r => ({
-                // Per statement, not per pipeline: the statements differ, so a
-                // single shared list of parameter OIDs could only ever be right
-                // for one of them.
-                parse: { sql: r.sql, paramTypes: r.paramTypes },
-                bind: {
-                    typeMap,
-                    paramTypes: r.paramTypes,
-                    params: r.params,
-                    queryOptions: options,
-                },
-                describe: { type: 'P' },
-                // Unlimited, never options.fetchCount: a suspended portal would
-                // break the positional statement-to-result mapping.
-                execute: { fetchCount: 0 },
-            }));
+            // Plan every statement against the prepared statement cache before
+            // writing anything: one that is already prepared binds to its name
+            // and skips both Parse and Describe, one seen often enough earns a
+            // name here, and the rest go out unnamed exactly as before.
+            const prepareEnabled = options.prepare ?? this.config.prepare ?? true;
+            const plans = [];
+            const promotions = [];
+            const cachedKeys = [];
+            const named = new Map();
+            const statements = [];
+            for (const r of requests) {
+                const key = prepareEnabled
+                    ? preparedCacheKey(r.sql, r.paramTypes)
+                    : undefined;
+                // A repeat can only skip its own Parse if the statement it binds
+                // to has a name. An unnamed one would be gone by now: any later
+                // statement's Parse replaces it.
+                let plan = key != null ? named.get(key) : undefined;
+                let sendParse = !plan;
+                let sendDescribe = !plan;
+                if (!plan) {
+                    const cached = key != null ? this._preparedCache.get(key) : undefined;
+                    if (cached && key != null) {
+                        // Re-insert to mark it most recently used.
+                        this._preparedCache.delete(key);
+                        this._preparedCache.set(key, cached);
+                        cachedKeys.push(key);
+                        plan = { name: cached.name, fields: cached.fields };
+                        sendParse = false;
+                        sendDescribe = false;
+                    }
+                    else if (key != null && this._earnsAName(key)) {
+                        plan = { name: 'C_' + ++this._preparedCounter };
+                        promotions.push({ key, plan });
+                    }
+                    else {
+                        plan = {};
+                    }
+                    if (key != null && plan.name)
+                        named.set(key, plan);
+                }
+                plans.push(plan);
+                statements.push({
+                    // Per statement, not per pipeline: the statements differ, so a
+                    // single shared list of parameter OIDs could only ever be right
+                    // for one of them.
+                    parse: sendParse
+                        ? { sql: r.sql, paramTypes: r.paramTypes, statement: plan.name }
+                        : undefined,
+                    bind: {
+                        typeMap,
+                        statement: plan.name,
+                        paramTypes: r.paramTypes,
+                        params: r.params,
+                        queryOptions: options,
+                    },
+                    describe: sendDescribe ? { type: 'P' } : undefined,
+                    // Unlimited, never options.fetchCount: a suspended portal would
+                    // break the positional statement-to-result mapping.
+                    execute: { fetchCount: 0 },
+                });
+            }
             this.runningQueryCount++;
-            await this.socket
-                .sendPipelineMessages({ statements }, (code, msg, done) => {
-                switch (code) {
-                    case Protocol.BackendMessageCode.ParseComplete:
-                    case Protocol.BackendMessageCode.BindComplete:
-                    case Protocol.BackendMessageCode.NoticeResponse:
-                        break;
-                    case Protocol.BackendMessageCode.NoData:
-                        pendingFields = undefined;
-                        break;
-                    case Protocol.BackendMessageCode.RowDescription:
-                        pendingFields = msg.fields;
-                        break;
-                    case Protocol.BackendMessageCode.DataRow:
-                        (pendingRows || (pendingRows = [])).push(msg);
-                        break;
-                    case Protocol.BackendMessageCode.EmptyQueryResponse:
-                    case Protocol.BackendMessageCode.CommandComplete: {
-                        const result = { command: msg?.command };
-                        if (pendingFields) {
-                            const parsers = getParsers(typeMap, pendingFields);
-                            const resultFields = wrapRowDescription(typeMap, pendingFields, columnFormat);
-                            result.fields = resultFields;
-                            result.rowType = resolveRowType(options);
-                            if (!result.command)
-                                result.command = 'SELECT';
-                            const rows = pendingRows || [];
-                            const l = rows.length;
-                            let i;
-                            for (i = 0; i < l; i++) {
-                                rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+            try {
+                await this.socket
+                    .sendPipelineMessages({ statements }, (code, msg, done) => {
+                    switch (code) {
+                        case Protocol.BackendMessageCode.ParseComplete:
+                        case Protocol.BackendMessageCode.BindComplete:
+                        case Protocol.BackendMessageCode.NoticeResponse:
+                            break;
+                        case Protocol.BackendMessageCode.NoData:
+                            pendingFields = undefined;
+                            break;
+                        case Protocol.BackendMessageCode.RowDescription:
+                            pendingFields = msg.fields;
+                            break;
+                        case Protocol.BackendMessageCode.DataRow:
+                            (pendingRows || (pendingRows = [])).push(msg);
+                            break;
+                        case Protocol.BackendMessageCode.EmptyQueryResponse:
+                        case Protocol.BackendMessageCode.CommandComplete: {
+                            const plan = plans[results.length];
+                            // A statement bound to a cached name sent no Describe, so
+                            // its columns come from the cache entry instead; one being
+                            // prepared here records its RowDescription for the entry it
+                            // is about to become, and for any repeat behind it.
+                            if (pendingFields)
+                                plan.fields = pendingFields;
+                            const fields = pendingFields || plan.fields;
+                            const result = { command: msg?.command };
+                            if (fields) {
+                                const { parsers, resultFields } = this._resolveReusedParsers(fields, typeMap, options);
+                                result.fields = resultFields;
+                                result.rowType = resolveRowType(options);
+                                if (!result.command)
+                                    result.command = 'SELECT';
+                                const rows = pendingRows || [];
+                                const l = rows.length;
+                                let i;
+                                for (i = 0; i < l; i++) {
+                                    rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+                                }
+                                result.rows = rows;
                             }
-                            result.rows = rows;
+                            if (result.command === 'DELETE' ||
+                                result.command === 'INSERT' ||
+                                result.command === 'UPDATE')
+                                result.rowsAffected = msg.rowCount;
+                            pendingFields = undefined;
+                            pendingRows = undefined;
+                            results.push(result);
+                            break;
                         }
-                        if (result.command === 'DELETE' ||
-                            result.command === 'INSERT' ||
-                            result.command === 'UPDATE')
-                            result.rowsAffected = msg.rowCount;
-                        pendingFields = undefined;
-                        pendingRows = undefined;
-                        results.push(result);
-                        break;
+                        case Protocol.BackendMessageCode.ErrorResponse:
+                            error = msg;
+                            break;
+                        case Protocol.BackendMessageCode.ReadyForQuery:
+                            this.transactionStatus = msg.status;
+                            done(error);
+                            break;
+                        default:
+                            done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
                     }
-                    case Protocol.BackendMessageCode.ErrorResponse:
-                        error = msg;
-                        break;
-                    case Protocol.BackendMessageCode.ReadyForQuery:
-                        this.transactionStatus = msg.status;
-                        done(error);
-                        break;
-                    default:
-                        done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
-                }
-            })
-                .catch((e) => {
-                // The rejected statement is the one right after everything that
-                // completed, since results only grow on CommandComplete.
-                if (e instanceof DatabaseError && error === e)
-                    e.failedIndex = results.length;
-                throw e;
-            })
-                .finally(() => {
-                this.runningQueryCount--;
-            });
+                })
+                    .catch((e) => {
+                    // The rejected statement is the one right after everything
+                    // that completed, since results only grow on CommandComplete.
+                    if (e instanceof DatabaseError && error === e)
+                        e.failedIndex = results.length;
+                    throw e;
+                })
+                    .finally(() => {
+                    this.runningQueryCount--;
+                });
+            }
+            catch (e) {
+                // A cached statement can be invalidated between two pipelines the
+                // same way a cached single query can (0A000, "cached plan must not
+                // change result type"). Drop what this pipeline reused and run it
+                // again unprepared - once, since the second attempt has nothing
+                // cached left to reuse.
+                if (e?.code !== '0A000' || !cachedKeys.length)
+                    throw e;
+                for (const k of cachedKeys)
+                    this._preparedCache.delete(k);
+                // Inside an explicit transaction there is nothing to retry into:
+                // the failed statement has already aborted the block.
+                if (this.inTransaction)
+                    throw e;
+                return await this.executePipeline(requests, options);
+            }
+            // Only now, with every Parse answered, are the new names real.
+            let promo;
+            let p;
+            const promotionCount = promotions.length;
+            for (p = 0; p < promotionCount; p++) {
+                promo = promotions[p];
+                await this._evictPreparedIfFull();
+                this._preparedCache.set(promo.key, {
+                    name: promo.plan.name,
+                    fields: promo.plan.fields,
+                });
+            }
             if (timingEnabled) {
                 const elapsed = performance.now() - startTime;
                 const l = results.length;

package/connection/pool.d.ts

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

package/connection/pool.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {

package/protocol/pg-socket.d.ts

@@ -119,9 +119,9 @@ export declare class PgSocket extends SafeEventEmitter {
      */
     sendPipelineMessages(args: {
         statements: {
-            parse: Frontend.ParseMessageArgs;
+            parse?: Frontend.ParseMessageArgs;
             bind: Frontend.BindMessageArgs;
-            describe: Frontend.DescribeMessageArgs;
+            describe?: Frontend.DescribeMessageArgs;
             execute: Frontend.ExecuteMessageArgs;
         }[];
     }, cb: CaptureCallback): Promise<any>;

package/protocol/pg-socket.js

@@ -280,17 +280,23 @@ export class PgSocket extends SafeEventEmitter {
      */
     sendPipelineMessages(args, cb) {
         const l = args.statements.length;
-        const data = new Array(l * 4 + 1);
+        const data = [];
         let i;
         let st;
         for (i = 0; i < l; i++) {
             st = args.statements[i];
-            data[i * 4] = this._frontend.getParseMessage(st.parse);
-            data[i * 4 + 1] = this._frontend.getBindMessage(st.bind);
-            data[i * 4 + 2] = this._frontend.getDescribeMessage(st.describe);
-            data[i * 4 + 3] = this._frontend.getExecuteMessage(st.execute);
+            // Parse and Describe are both optional: a statement bound to one the
+            // connection has already prepared needs neither, since the server
+            // still holds the plan and IntlConnection still holds the
+            // RowDescription that came with it.
+            if (st.parse)
+                data.push(this._frontend.getParseMessage(st.parse));
+            data.push(this._frontend.getBindMessage(st.bind));
+            if (st.describe)
+                data.push(this._frontend.getDescribeMessage(st.describe));
+            data.push(this._frontend.getExecuteMessage(st.execute));
         }
-        data[l * 4] = this._frontend.getSyncMessage();
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendPipelineMessages', args);
     }
     /**