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, timeout is a single deadline shared by both the active-connection drain and the background-task drain. Pending background spawns still in flight when the deadline elapses are cancelled so close() returns promptly. Without a timeout (or ZeroDuration), active connections are closed on release and the background drain waits unbounded.

Execute a statement with typed parameters using a pooled connection. When pipelined is enabled, the operation is batched with other concurrent calls and sent in a single TCP write.

In pipelined mode a batch runs under a single timeout, so a finite timeout may be widened to the largest finite timeout among the ops it is batched with. An op with no timeout (ZeroDuration) is batched separately and stays unlimited.

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. When pipelined is enabled, the operation is batched with other concurrent calls and sent in a single TCP write.

In pipelined mode a batch runs under a single timeout, so a finite timeout may be widened to the largest finite timeout among the ops it is batched with. An op with no timeout (ZeroDuration) is batched separately and stays unlimited.

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.

Swallows CatchableError (invoked from finally, so a raised reset error would mask the body's original exception) but re-raises CancelledError — chronos requires cancellation to propagate. A Defect is re-raised as PgPoolError (the Defect as parent) after marking csClosed (the reset did not complete). Callers must chain release() under try/finally (or use resetSessionAndRelease) to keep pool accounting balanced on cancel.

Acquire a connection, execute body, then release it back to the pool. The connection is available as conn inside the body. resetSession runs before release, so a configured resetQuery is applied and any session-level advisory locks acquired through the typed API are released via pg_advisory_unlock_all.

Release runs outside finally (a failing await in an asyncdispatch finally masks the body error), so return / break / continue escaping the body are rejected at compile time.

Acquire a connection, create a Pipeline, execute body, then release. pipeline and the acquired conn are available in the body.

Body return / break / continue escaping to an enclosing loop are rejected at compile time (see withConnection).

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: PgTimeoutError is raised. Under chronos the body future is cancelled: a connection with a request in flight is invalidated (server-side CancelRequest, dropped on release), while one that unwinds cleanly (grace ROLLBACK succeeded) returns to the pool healthy. Under asyncdispatch the still-running body keeps the connection; it is invalidated via invalidateOnTimeout and dropped on its eventual release. 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 runs with rollbackGrace. A body Defect is re-raised wrapped in PgPoolError (Defect as parent).

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: PgTimeoutError is raised — never retried; the in-flight connection is handled as in withTransactionDeadline. 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.

On a `Defect` raised by the body: re-raised wrapped in PgPoolError (parent = Defect), never retried; see withTransactionDeadline.