Connections · XB Field Notes

A pool shares a few Postgres connections among many requests

Sat, 13 Feb 2027 00:00:00 +0000

A connection pool lets many application requests borrow a smaller number of PostgreSQL sessions over time. Reuse amortizes connection setup and limits simultaneous leases, but does not make an overloaded database faster by itself. The pool creates another queue whose capacity, waiting time, and cancellation behavior belong to the request budget. Treat that queue as part of the service, not as an invisible implementation detail.

When it breaks

A PostgreSQL backend waiting on ClientRead is waiting for its client to send data. It is not reporting that an application request is queued for a pool lease. Pool waiters may have no backend connection at all. Measure acquisition waiting in the pool and database execution or lock waiting at the server; combining those into one supposed PostgreSQL pool event hides the actual bottleneck.

Returning a connection also does not universally erase session state. Psycopg’s connection context commits on normal exit and rolls back when an exception leaves the context. Additional reset behavior depends on configuration. A committed session-level setting can remain for the next borrower, even though no transaction was leaked. Temporary objects and other session resources likewise require a deliberate policy rather than an assumption that every pool resets everything.

Check it quickly

Use Python 3.10 or later, a disposable PostgreSQL 18 database, and a role allowed to create the fixture schema. Install the tested dependencies with python3 -m pip install "psycopg[binary]==3.3.5" "psycopg-pool==3.3.1". Set PG_DSN to that database’s connection string using your existing authentication configuration. Save the program as pool-demo.py and run it with the same Python environment.

import os
import time
from concurrent.futures import ThreadPoolExecutor

import psycopg
from psycopg_pool import ConnectionPool, PoolTimeout, TooManyRequests

dsn = os.environ['PG_DSN']
with psycopg.connect(dsn, autocommit=True) as admin:
 admin.execute('CREATE SCHEMA pool_demo')
 try:
 admin.execute('CREATE TABLE pool_demo.counter (n integer)')
 admin.execute('INSERT INTO pool_demo.counter VALUES (0)')
 with ConnectionPool(
 dsn, min_size=1, max_size=1, max_waiting=1,
 timeout=3, open=True,
 kwargs={'application_name': 'pool_example'},
 ) as pool:
 pool.wait(timeout=3)

 def queued_request():
 try:
 with pool.connection(timeout=1):
 raise AssertionError('holder should still own the only connection')
 except PoolTimeout:
 return 'PoolTimeout'

 with ThreadPoolExecutor(max_workers=1) as workers:
 with pool.connection() as held:
 original_pid = held.info.backend_pid
 waiting = workers.submit(queued_request)
 deadline = time.monotonic() + 0.5
 while pool.get_stats()['requests_waiting'] != 1:
 if time.monotonic() >= deadline:
 raise TimeoutError('request did not enter the pool queue')
 time.sleep(0.005)
 state = admin.execute(
 'SELECT state,wait_event_type,wait_event '
 'FROM pg_stat_activity WHERE pid=%s', (original_pid,)
 ).fetchone()
 assert state == ('idle', 'Client', 'ClientRead'), state
 print('waiting_in_pool', 1, 'server', state)
 try:
 with pool.connection(timeout=0.1):
 raise AssertionError('queue limit was not applied')
 except TooManyRequests:
 print('queue_limit', 'TooManyRequests')
 assert waiting.result(timeout=2) == 'PoolTimeout'
 print('queued_request', 'PoolTimeout')

 with pool.connection() as conn:
 assert conn.info.backend_pid == original_pid
 conn.execute("SET application_name='previous_borrower'")
 try:
 with pool.connection() as conn:
 conn.execute('UPDATE pool_demo.counter SET n=99')
 raise ValueError('simulated request failure')
 except ValueError as error:
 assert str(error) == 'simulated request failure'

 with pool.connection() as conn:
 value = conn.execute('SELECT n FROM pool_demo.counter').fetchone()[0]
 setting = conn.execute('SHOW application_name').fetchone()[0]
 assert value == 0 and setting == 'previous_borrower'
 assert conn.info.backend_pid == original_pid
 print('same_backend', True, 'rollback_value', value, 'retained_setting', setting)
 conn.execute('RESET application_name')
 finally:
 admin.execute('DROP SCHEMA pool_demo CASCADE')

The pool contains exactly one connection and allows one waiting request. The main thread holds the connection without running a query, while a worker tries to borrow it. Once the pool reports one waiter, the independent observer sees the held backend idle on ClientRead. Those states coexist: the queue is in the application even though the database session has no query to execute.

A third acquisition is rejected with TooManyRequests because the queue is already full. The queued worker then reaches its one-second acquisition budget and reports PoolTimeout. The holder does not release early, so the test distinguishes queue overflow from expiration while waiting. Neither error is a PostgreSQL row-lock timeout, and neither indicates that an application SQL operation was executed.

After release, another borrower receives the same backend identifier. It sets application_name at session scope and exits normally. A later borrower updates the counter to 99, then raises an exception outside the successful path. The connection context rolls back that update. The final borrower sees counter zero and the earlier session setting still present, while the backend identifier remains unchanged.

The final output therefore reports same_backend True, rollback_value 0, and retained_setting previous_borrower. Transaction cleanup worked, while session state was retained. The program explicitly resets its setting and drops its own schema. An existing schema of that name causes setup to fail before cleanup ownership is assumed.

Size the complete deployment

Pool size applies to one pool instance, not the whole service fleet. Four processes with eight connections each can consume thirty-two server slots before counting other applications, migrations, monitoring, and administrative headroom. Compare that aggregate with the server’s connection budget and useful execution concurrency. Increasing every pool can move waiting into the database while increasing memory pressure.

Borrow connections for the shortest complete database operation that preserves its transaction boundary, and return them on every exit path. Avoid holding a lease during unrelated network calls or user interaction. Use transaction-local settings where appropriate, or an explicit reset callback for state that must be cleared. Observe acquisition latency, queue rejection, lease duration, and database execution together before changing capacity.

Sources

Psycopg pooling documentation source, connection lifecycle, transaction contexts, and optional reset callbacks, checked 2026-09-10.
Psycopg pool API documentation source, size, queue limits, timeout exceptions, and statistics, checked 2026-09-10.
PostgreSQL 18 connection settings, server connection limits and reserved capacity, checked 2026-09-10.
PostgreSQL 18 activity statistics, backend state and ClientRead semantics, checked 2026-09-10.

Connection caps guard a shared database

Sat, 05 Sep 2026 00:00:00 +0000

A connection cap limits one owner’s demand; it does not automatically cap every application sharing a database. The useful budget is the sum of physical connections that can reach each backend, including idle pooled connections. Begin with the backend’s usable slots, then allocate them across all callers and deployment states.

Count pools before choosing their size

For a finite SQLAlchemy QueuePool, simultaneous connections are bounded by pool_size + max_overflow. That is a per-pool limit. Engines with separately created QueuePools have independent limits; worker processes and replicas can multiply them again. Count actual pools, since derived Engine views can share one. For identical owners, multiply replicas, processes per replica, pools per process, and the per-pool cap. For different owners, sum their individual caps instead.

Count the maximum overlapping deployment, not merely the number of ready replicas after rollout. New replicas can open connections while old replicas still drain work or retain idle connections. Include background jobs, migration tools, monitoring, and other services in the inventory. Connections to different database servers require separate budgets rather than one number that hides the constrained target.

PostgreSQL’s max_connections is the server ceiling, not the application’s allocation. Ordinary roles without reserved-slot privileges must leave both superuser_reserved_connections and reserved_connections untouched. The latter is for roles with pg_use_reserved_connections privileges. Explicitly subtract other ordinary clients and operating margin as well; do not borrow emergency capacity for routine traffic.

When it breaks

A service can respect every local pool cap and still exhaust the database because there are more pools than the worksheet counted. Unlimited overflow defeats that worksheet altogether. Conversely, an excessively small cap can cause acquisition waits even when the backend has capacity. Neither observation establishes that changing the database ceiling is the right fix.

More connections do not create more CPU, faster storage, or fewer conflicting transactions. PostgreSQL allocates some resources according to its configured ceiling, so raising it also has resource consequences. Examine acquisition waits, physical connections, active work, and transaction duration together. A cap constrains connection count; it does not guarantee throughput, fairness between services, or short lock waits.

An external pooler adds another accounting boundary. PgBouncer session pooling retains a server connection for the client session, whereas transaction pooling returns it after each transaction. Client connections therefore are not interchangeable with backend-session counts. Inventory the pooler’s server-side allocation and pooling mode; transaction mode changes assumptions about session features, so adopting it is not just a capacity-number edit.

Check it quickly

Use an empty directory on macOS or Linux. Run python3 -m venv .venv, then .venv/bin/python -m pip install SQLAlchemy==2.0.52. Save this as pool_probe.py and run .venv/bin/python pool_probe.py. It was checked with Python 3.14.4 and SQLite 3.53.0. Its three real pools live in one process and share a temporary local database file.

from pathlib import Path
from tempfile import TemporaryDirectory

import sqlalchemy
from sqlalchemy import create_engine, event
from sqlalchemy.exc import TimeoutError as PoolTimeout
from sqlalchemy.pool import QueuePool


assert sqlalchemy.__version__ == "2.0.52"
with TemporaryDirectory(prefix="pool-caps-") as directory:
 engines, held, opened, closed = [], [], [0, 0, 0], [0, 0, 0]
 try:
 for owner in range(3):
 engine = create_engine(
 "sqlite:///" + str(Path(directory) / "probe.db"),
 poolclass=QueuePool, pool_size=2, max_overflow=1, pool_timeout=0.05,
 )
 engines.append(engine)

 def on_connect(dbapi_connection, entry, index=owner):
 opened[index] += 1

 def on_close(dbapi_connection, entry, index=owner):
 closed[index] += 1

 event.listen(engine, "connect", on_connect)
 event.listen(engine, "close", on_close)
 for _ in range(3):
 held.append(engine.connect())
 try:
 unexpected = engine.connect()
 except PoolTimeout:
 pass
 else:
 unexpected.close()
 raise AssertionError("each pool must reject a fourth simultaneous lease")
 assert len({id(engine.pool) for engine in engines}) == 3
 view = engines[0].execution_options(logging_token="same-pool")
 assert view.pool is engines[0].pool
 print("an Engine execution-options view shares its parent pool; it adds no connection slots")
 assert opened == [3, 3, 3]
 assert [engine.pool.checkedout() for engine in engines] == [3, 3, 3]
 print("three independent pools each cap at 3, yet together hold 9 physical SQLite connections")

 for connection in held:
 connection.close()
 assert [engine.pool.checkedin() for engine in engines] == [2, 2, 2]
 assert closed == [1, 1, 1]
 print("after return, 6 connections remain idle; the 3 overflow connections are closed")
 finally:
 for connection in held:
 connection.close()
 for engine in engines:
 engine.dispose()
 assert opened == closed == [3, 3, 3]


def demand(replicas, processes, pools_per_process, size, overflow):
 return replicas * processes * pools_per_process * (size + overflow)


# Illustrative PostgreSQL worksheet, not a live server configuration or benchmark.
maximum, superuser_reserve, role_reserve = 100, 3, 5
other_clients, operating_margin = 24, 8
budget = maximum - superuser_reserve - role_reserve - other_clients - operating_margin
assert budget == 60
assert demand(6, 1, 1, 8, 2) == 60
assert demand(8, 1, 1, 8, 2) == 80 > budget # Two extra replicas during rollout.
assert demand(8, 1, 1, 6, 1) == 56 <= budget
assert demand(8, 2, 1, 6, 1) == 112 > budget # A second process creates another pool.
assert demand(8, 1, 2, 6, 1) == 112 > budget # A second independent pool per process.
print("ordinary-client allocation: 60; steady demand 60; rollout demand 80; revised rollout demand 56")
print("doubling either processes or pools raises that revised demand to 112; no PostgreSQL server was run")

Each pool holds three physical SQLite connections and rejects a fourth checkout with PoolTimeout. Together they hold nine, proving that a local cap of three is not a database-wide cap of three. An execution-options Engine view shares the first pool and adds no capacity. Returning the leases retains six idle connections and closes three excess connections. Disposing all Engines after return makes the observed connect and close event counts agree.

The second half is explicitly an arithmetic model, not a running PostgreSQL configuration. Its illustrative ceiling of 100 loses three superuser slots, five reserved-role slots, 24 other ordinary-client slots, and eight margin slots, leaving 60. Five reserved-role slots are a chosen example; PostgreSQL’s documented default for that setting is zero.

Six replicas with caps of ten fit exactly, but eight overlapping replicas require 80. Revising each cap to six retained plus one overflow gives 56 during overlap. Adding a second worker process or a second pool per process doubles that to 112, exceeding the same allocation.

These checks establish local pool behavior and budget arithmetic, not production performance or a safe universal pool size. No PostgreSQL server, PgBouncer instance, or real rollout was exercised. Before changing production limits, verify the actual pool inventory and maximum overlap, then measure waiting and backend saturation under the intended workload.

Sources

SQLAlchemy connection pooling, finite QueuePool capacity and idle retention, checked 2026-09-09.
SQLAlchemy Engine and Connection, derived Engine views can share a connection pool, checked 2026-09-09.
SQLAlchemy pool events, observed connection creation and close events, checked 2026-09-09.
PostgreSQL connection settings, server ceiling and reserved-slot privileges, checked 2026-09-09.
PgBouncer features, session and transaction pooling boundaries, checked 2026-09-09.