withPipelinedTransaction function
- @experimental
- PostgresConnectionPool pool,
- List<
String> queries, { - 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();
}
}