withPipelinedTransaction function

  1. @experimental
Future<void> withPipelinedTransaction(
  1. PostgresConnectionPool pool,
  2. List<String> queries, {
  3. Duration? timeout,
})

Runs queries inside a single Postgres pipeline: BEGIN; <queries[0]>; ...; <queries[N-1]>; COMMIT; in one network round-trip total (vs N+1 for the sequential withTransaction pattern — the BEGIN is fused into the first statement, so it no longer costs a dedicated round-trip; the COMMIT still does).

v1 limitation: result rows are NOT returned (libpq pipeline mode + our watcher's counting strategy discard them). Best suited for bulk writes (INSERT/UPDATE/DELETE) where command tags suffice. For mixed read/write patterns where you need rows, use the sequential withTransaction.

This self-contained helper is the recommended path for a standalone write batch. When you already hold an external transaction, calling executePipeline(writes) inside withTransaction also persists correctly (since 2026-07-29) — the pipeline no longer discards the surrounding open transaction.

On any failure (libpq dispatch error, mid-pipeline error, timeout), the entire pipeline aborts and propagates the exception.

Added in ABI MAJOR 1 MINOR 1.

Implementation

@experimental
Future<void> withPipelinedTransaction(
  PostgresConnectionPool pool,
  List<String> queries, {
  Duration? timeout,
}) async {
  if (queries.isEmpty) return;
  final leased = await pool.acquire();
  try {
    final exec = PostgresQueryExecutor(pool.binding, leased.raw,
        timeout: timeout, statementCache: pool.statementCacheEnabled);
    await exec.executePipeline([
      'BEGIN',
      ...queries,
      'COMMIT',
    ]);
  } finally {
    await leased.release();
  }
}