Acquire a connection from the pool. Tries idle connections first (with health checks), creates a new one if under maxSize, or waits for a release. Raises PgPoolError on every failure mode: acquire timeout, pool closed, waiter queue full, or a failed connect attempt — for connect failures the underlying error (e.g. PgConnectionError) is preserved as the parent of the raised PgPoolError. Use the kind field (PoolErrorKind) to distinguish the failure mode programmatically. A connect that raises PgConfigError is reported as pekConfigFault, after which the pool never dials again (the config cannot change). A connect the server refuses (see isLastingRefusal) is reported as pekRefused, as are the waiters no borrower is left to serve; connectRefusal keeps the refusal until a connect succeeds, but a waiter queued after it gets a dial of its own. retryAdvice returns raStop for either kind.

Timeout types differ by phase: this proc reports its own deadline as PgPoolError(pekAcquireTimeout), while a pipelined pool.exec / pool.query wait and the pool withTransactionDeadline / withTransactionRetryDeadline deadline raise PgTimeoutError instead — even when the deadline variant expires during its internal acquire. An except PgPoolError clause alone therefore misses those operation timeouts; catch PgTimeoutError first:

try:
  discard await pool.query(sql"SELECT 1", timeout = seconds(5))
except PgTimeoutError:
  echo "operation timed out"
except PgPoolError as e:
  echo "acquire failed: ", e.kind

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, fail queued acquires and pipelined operations with pekClosed, and close the idle connections. An acquire already dialing or pinging fails once that dial or ping ends; a checked-out connection is closed when released.

When timeout > ZeroDuration, timeout is a single deadline shared by both the drain of activeCount() and the background-task drain. Pending background closes still running when the deadline elapses are cancelled so close() returns promptly. The idle connections, closed between the two drains, are not cut short: closing one sends Terminate and waits for no reply. Without a timeout (or ZeroDuration), close() does not wait for activeCount() and the background drain waits unbounded.

asyncdispatch cannot cancel a future: there the maintenance loop, and background tasks still running at the deadline, outlive close() until their current sleep, connect, ping or close ends. A connection they open or ping after close() is closed, not kept.

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. A finite timeout is measured from enqueue (queue dwell included); when maxWaiters >= 0, enqueue itself rejects with pekQueueFull once pendingOps reaches that depth.

A pipelined wait that exceeds timeout raises PgTimeoutError, not PgPoolError, so except PgPoolError alone misses it — catch PgTimeoutError first (see acquire).

Create a pool configuration with sensible defaults. Maintenance replenishes size() toward minSize, checked-out connections included; acquires dial up to maxSize. 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. A refusal (see connectRefusal) skips the ramp to connectBackoffMax and replenishes one connection at a time, but a waiter still gets a dial: one refused fails the waiters no borrower can serve with PgPoolError(pekRefused).

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. A finite timeout is measured from enqueue (queue dwell included); when maxWaiters >= 0, enqueue itself rejects with pekQueueFull once pendingOps reaches that depth.

A pipelined wait that exceeds timeout raises PgTimeoutError, not PgPoolError, so except PgPoolError alone misses it — catch PgTimeoutError first (see acquire).

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, in a transaction, or past maxLifetime, it is closed instead; if waiters are queued, it is handed directly to the next waiter.

No session reset: resetSession does not run, so resetQuery is skipped and session state (SET, SET ROLE, prepared statements, …) reaches the next borrower; a connection holding typed-API advisory locks or a changed TimeZone is closed instead. Use resetSessionAndRelease or the with* macros to clean up.

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.

Double-release: releasing an already-idle connection is a no-op (tracer onPoolDoubleRelease), but after a FIFO handoff a second raw release(conn) can still re-route the waiter's connection — this API carries no per-borrow token. Prefer PooledConnHandle / with*.

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 ROLE, prepared statements, etc.) on the connection is not cleared before it returns to the pool, so subsequent borrowers may observe it. A connection holding advisory locks acquired via the typed API, or whose TimeZone changed since connect, is closed instead, at the cost of a reconnect. 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, runs the configured resetQuery (if any), then sets back a TimeZone changed since connect (with TimeZone=DEFAULT, RESETs it to the server's current one). 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), has nothing to clean up (no resetQuery, no advisory locks held, TimeZone unchanged), or is bound for discard (TimeZone moved, but the server reported none at connect to set back). 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.

resetSession + release, wrapped so release() still runs when the reset propagates CancelledError (else a pool slot leaks).

Correct for both application-held and pool-internal borrows. A conn past maxLifetime skips the reset: release closes it, so the round trip would be spent on a conn the pool throws away.

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. Without a resetQuery, other session state (SET, SET ROLE, prepared statements, …) reaches the next borrower.

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. A COMMIT the server rolled back raises PgQueryError (25P02), as in the PgConnection overload. 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. Do not issue transaction-control SQL (COMMIT, ROLLBACK, ...) inside the body either: as in the PgConnection overload, ending the transaction yourself is not detected.

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. A COMMIT the server rolled back raises PgQueryError (25P02), as in withTransaction.

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. The grace ROLLBACK only runs in that second shape — the deadline expiring between statements; a cancellation inside a statement is caught there and invalidates the connection, so the cleanup skips it. Under asyncdispatch the still-running body keeps the connection, which is retired csClosed without a ROLLBACK and dropped on its eventual release. Whenever ROLLBACK is skipped, dropping the connection is what ends the server-side transaction. If the timeout fires while still waiting for acquire(), chronos cancels that acquire. Under asyncdispatch it stays queued, counting toward maxWaiters, until it gets a connection or its own acquireTimeout expires. A connection it still gets goes straight back to the pool: the body never runs, so a caller that retries does not run it twice. A deadline that expires after COMMIT, during the pool's session reset, raises nothing: the transaction committed. Under chronos the reset is cancelled and the connection dropped. Under asyncdispatch the reset runs on, bounded only by resetQueryTimeout, as on any release.

This holds for the acquire phase too: a deadline that expires while waiting for acquire() raises PgTimeoutError, not PgPoolError(pekAcquireTimeout) as a bare acquire() would. An except PgPoolError clause alone therefore misses it — catch PgTimeoutError first (see acquire). retryAdvice returns raRetry for both timeout types.

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. A COMMIT the server rolled back raises PgQueryError (25P02), retried as in the PgConnection overload. 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. This holds for the acquire phase too: a deadline that expires while waiting for acquire() raises PgTimeoutError, not PgPoolError(pekAcquireTimeout) as a bare acquire() would. An except PgPoolError clause alone therefore misses it — catch PgTimeoutError first (see acquire). retryAdvice returns raRetry for both timeout types. The in-flight connection, and a deadline that expires after COMMIT, are handled as in withTransactionDeadline. On a retryable error: ROLLBACK runs with rollbackGrace and the transaction is retried if budget remains. A COMMIT the server rolled back (25P02) is retried as in withTransactionRetry. 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.