Acquire a connection wrapped in a PooledConnHandle. Equivalent to acquire, but the returned handle pairs the connection with its owning pool and provides an idempotent release(h).

The caller is responsible for releasing — typically via defer: h.release(). Forgetting to release leaks the connection. release(h) does not run resetSession; prefer withConnection when automatic session cleanup is desired.

Close the pool: stop the maintenance loop, cancel all waiters, and close all idle and active connections.

When timeout > ZeroDuration, waits up to timeout for active connections to be released. Unreleased connections are closed when they are eventually returned to the pool. Without a timeout (or ZeroDuration), active connections are closed on release.

Create a pool configuration with sensible defaults. minSize idle connections are maintained; up to maxSize total. Set resetQuery to clean session state on release (e.g. "DISCARD ALL" for PgBouncer). Set pipelined to true to enable implicit query batching for pool.exec/pool.query. When the maintenance loop fails to open a connection, subsequent retries use exponential backoff starting at connectBackoffInitial, doubling up to connectBackoffMax. Set connectBackoffInitial = ZeroDuration to disable backoff and fall back to fixed-interval retries.

Raises ValueError if parameters are invalid.

Execute a query with typed parameters using a pooled connection, invoking callback once per row.

Row lifetime: the Row passed to callback is only valid for the duration of that single invocation. To retain a row beyond the callback, call row.clone() to get a detached copy.

Return a connection to its owning pool. If the connection is broken or in a transaction, it is closed instead; if waiters are queued, it is handed directly to the next waiter.

The owning pool is tracked on conn.ownerPool, set automatically when the connection is acquired from a PgPool (including pools inside a PgPoolCluster). For standalone connections created with connect this field is nil and calling release raises PgError — use conn.close() instead.

withConnection, withReadConnection, withWriteConnection, withPipeline, and withTransaction call this automatically; direct callers only need it when they manage acquire/release manually.

Return the borrowed connection to its pool. Idempotent — safe to call twice (e.g. once explicitly and once via defer).

Does not run `resetSession`. Session state (SET/SET LOCAL outside a transaction, prepared statements, advisory locks acquired via the typed API, etc.) on the connection is not cleared before it returns to the pool, so subsequent borrowers may observe it. If that matters, use withConnection / withReadConnection / withWriteConnection instead, or call await h.pool.resetSession(h.conn) yourself before release(h).

Reset session-affecting state on a connection before returning it to the pool. Releases any session-level advisory locks acquired through the typed API, then runs the configured resetQuery (if any). On failure, closes the connection so that release() will discard it.

Always safe to call: returns immediately when the connection is unusable (broken / mid-transaction) or has nothing to clean up (no resetQuery and no advisory locks held). Callers don't need to gate on the pool config.

Never propagates CatchableError: this is invoked from finally blocks in the with* helpers (and the per-call cleanup path of exec / query etc.), where a raised reset error would mask the body's original exception. Cleanup errors — including any raised from the close path's tracer hook — are swallowed.

Execute body inside a BEGIN/COMMIT transaction using a pooled connection. On exception, ROLLBACK is issued automatically. Using return inside the body is a compile-time error.

Usage: pool.withTransaction(conn): conn.exec(...) pool.withTransaction(conn, seconds(5)): conn.exec(...) pool.withTransaction(conn, TransactionOptions(isolation: ilSerializable)): conn.exec(...) pool.withTransaction(conn, opts, seconds(5)): conn.exec(...)

Warning: Inside the body, use conn.exec(...) / conn.query(...) directly — not pool.exec(...) / pool.query(...). Pool methods acquire a separate connection, so those statements would run outside this transaction.

Timeout semantics: The timeout argument applies per-call to BEGIN, COMMIT, and ROLLBACK only — it does not bound body operations or pool.acquire(). Worst-case wall-clock = acquire(unbounded) + BEGIN(≤timeout) + body(unbounded) + COMMIT(≤timeout) [+ ROLLBACK(≤timeout) on failure]. Use withTransactionDeadline for a single wall-clock deadline covering acquire, BEGIN, body, and COMMIT.

Execute body inside a BEGIN/COMMIT transaction bounded by a single wall-clock deadline that covers pool.acquire(), BEGIN, the body, and COMMIT together.

Usage: pool.withTransactionDeadline(conn, seconds(5)): await conn.exec(...) pool.withTransactionDeadline(conn, TransactionOptions(...), seconds(5)): await conn.exec(...)

On deadline exceeded: if a connection was already acquired, it is invalidated via invalidateOnTimeout (marked csClosed) and the pool drops it on release. ROLLBACK is not attempted. PgTimeoutError is raised. If the timeout fires while still waiting for acquire(), the waiter remains queued (cancelled best-effort) until the underlying acquire future settles; this is unavoidable under asyncdispatch.

Edge case — acquire-completion race: under asyncdispatch the only preemption point is await, but the outer wait may still fire its timeout on the same tick the body finishes. To avoid a false-positive PgTimeoutError in that window, the timeout handler checks bodyFut.completed() (success only) and, when true, returns normally instead of reporting a timeout. A still-running or failed body falls through to the standard invalidate-and-raise path. This narrows but does not eliminate the race — a PgTimeoutError from this macro still does not guarantee the transaction was rolled back if the body was mid-flight when the timer won; it only guarantees the caller gave up waiting.

On other body exceptions: ROLLBACK is issued with rollbackGrace per-call timeout.

Warning: Inside the body, use conn.exec(...) / conn.query(...) directly — not pool.exec(...) / pool.query(...). Pool methods acquire a separate connection, so those statements would run outside this transaction.

Execute body inside a BEGIN/COMMIT transaction on a pooled connection, re-running the whole transaction when it fails with a retryable error (by default the serialization_failure / deadlock_detected SQLSTATEs — see RetryOptions). The pooled connection is acquired once and reused across attempts; a ROLLBACK between attempts returns it to a clean tsIdle state. On a non-retryable error, or once maxAttempts is exhausted, the last exception propagates. Using return inside the body is a compile-time error.

Usage: pool.withTransactionRetry(RetryOptions(maxAttempts: 3), conn): await conn.exec(...) pool.withTransactionRetry(RetryOptions(...), conn, seconds(5)): await conn.exec(...) pool.withTransactionRetry(RetryOptions(...), conn, TransactionOptions(isolation: ilSerializable)): await conn.exec(...) pool.withTransactionRetry(RetryOptions(...), conn, opts, seconds(5)): await conn.exec(...)

Idempotency: body runs once per attempt, so it must be safe to re-run; non-database side effects are repeated on every retry. See withTransaction for the timeout semantics and the in-body conn.exec(...) warning.

Execute body inside a BEGIN/COMMIT transaction on a pooled connection, bounded by a single wall-clock deadline that is shared across all retry attempts (covering acquire(), BEGIN, body, and COMMIT of every attempt), re-running the whole transaction on a retryable error while budget remains.

Usage: pool.withTransactionRetryDeadline(RetryOptions(maxAttempts: 3), conn, seconds(5)): await conn.exec(...) pool.withTransactionRetryDeadline(RetryOptions(...), conn, TransactionOptions(...), seconds(5)): await conn.exec(...)

Each attempt acquires a fresh connection (the previous one is released by the per-attempt finally), so a failed/poisoned connection is dropped by the pool's health check rather than reused. Worst-case wall-clock is deadline, not maxAttempts * deadline.

On deadline exceeded: the in-flight connection (if any) is invalidated and PgTimeoutError is raised — never retried. On a retryable error: ROLLBACK runs with rollbackGrace and the transaction is retried if budget remains. See withTransactionDeadline for the acquire-race / completed() rationale and the in-body conn.exec(...) warning. Idempotency: body runs once per attempt; non-database side effects repeat. Using return inside the body is a compile-time error.