LangGraph Checkpointer Postgres: PgBouncer and SSL Errors

The sync factory lives in langgraph/checkpoint/postgres/__init__.py.

There is no pool, no pool_config, no keepalive argument (libpq keepalive parameters can still ride in the connection string), no prepare_threshold and no way to change pipeline behaviour. Issue #7304 asked for pool_config on AsyncPostgresSaver.from_conn_string(); it is open, and the PR that implemented it, #7311, was closed without merge on 2026-03-27.

The constructors are more flexible than the factory. PostgresSaver(conn, pipe=None, serde=None) and AsyncPostgresSaver(conn, pipe=None, serde=None) accept either a single connection or a pool. Internally, _internal.get_connection does two different things depending on which you passed. Given a ConnectionPool, it checks a connection out for each operation and returns it afterwards. Given a Connection, it yields the same connection forever. So a saver built by the factory, or on a connection you checked out of a pool and handed over, holds one socket across every LLM call, tool call and human wait for as long as the process lives. A saver built on a pool holds a socket only while it reads or writes.

Two constraints come with the constructor route. The README requires autocommit=True and row_factory=dict_row on any connection you pass in. Autocommit is needed because setup() applies 10 migrations, three of which are CREATE INDEX CONCURRENTLY statements that Postgres refuses inside a transaction block. dict_row is needed because the saver reads columns by name. And passing a pool together with a pipe raises ValueError("Pipeline should be used only with a single Connection, not ConnectionPool.").

One more property sets expectations for pool sizing. _cursor holds self.lock (a threading.Lock in the sync saver, an asyncio.Lock in the async one) for the whole time it holds a connection, and every checkpoint read and write goes through _cursor. It follows from the source that one saver instance uses at most one pooled connection at a time. Raising max_size adds no checkpoint throughput for a single saver. The pool is there for validation, recycling and reconnect, and for sharing with an AsyncPostgresStore if you run one.

These are the six symptoms that trace back to the 3.1.2 code path, with the mechanism, the fix you control, and where upstream stands as of 2026-10-05.

The first, fifth and sixth rows have deterministic fixes. The second has a reliable mitigation. The third and fourth are open bugs, covered further down. Every fix is client configuration, which matters where you cannot change the pooler or the firewall.

psycopg's semantics are precise, and the factory picks the most aggressive value. From the prepare_threshold docstring in psycopg 3.3.6: it is the number of times a query is executed before it is prepared; at 0, every query is prepared the first time it is executed; at None, prepared statements are disabled on the connection; the default is 5. So from_conn_string asks Postgres to prepare every checkpoint statement on first use.

That is fine against a direct connection. Behind a transaction-mode pooler it is the wrong setting. The psycopg documentation on prepared statements says that unless a connection pooling middleware explicitly declares otherwise, it is not compatible with prepared statements, "because the same client connection may change the server session it refers to", and that with such middleware you should set prepare_threshold to None. The warning is generic, so it covers RDS Proxy and Supavisor as much as PgBouncer unless their own documentation says otherwise.

There is a path that keeps prepared statements. Starting from psycopg 3.2, they work through PgBouncer when all three conditions hold:

With PgBouncer 1.22+ but an older libpq, psycopg documents a fallback: disable deallocation by setting Connection.prepared_max to None (its default is 100 statements per connection). Start from prepare_threshold=None, and move to the 1.22 path only after the platform team confirms the pooler config and you have pinned libpq in your image.

If you cannot replace the factory this week, two attributes can be changed after construction. saver.conn is the psycopg connection and prepare_threshold has a setter; the reporter of #5675 uses exactly this line. supports_pipeline is covered in the next section.

async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.conn.prepare_threshold = None  # factory hardcodes 0
    checkpointer.supports_pipeline = False       # pipeline=False alone does not do this
    graph = builder.compile(checkpointer=checkpointer)

This patch fixes the prepared-statement row and the pipeline row of the table. It does nothing for dead idle connections, because the saver still holds one connection for the process lifetime. Treat it as a stopgap until the pool construction below replaces it.

Both constructors run self.supports_pipeline = Capabilities().has_pipeline(). The same line appears in the sync saver, the async saver and both Shallow savers. has_pipeline() is a psycopg capability check on the client: to use pipeline mode, "the client must use a libpq from PostgreSQL 14 or higher". It knows nothing about the server, PgBouncer, RDS Proxy or the network in between. Issue #8420's description says it checks the server; it does not.

Then look at _cursor(pipeline=...), identical in sync and async:

put, put_writes and delete_thread (and their async versions) call _cursor(pipeline=True). Reads (get_tuple, list, setup) use a plain cursor. So on any libpq 14 or newer, every checkpoint write runs in pipeline mode: when you passed pipeline=False, when you passed nothing, and when conn is a pool. The factory's pipeline flag only decides whether the whole saver lives inside one long-lived pipeline.

psycopg's own documentation calls pipeline mode experimental: "Its behaviour, especially around error conditions and concurrency, hasn't been explored as much as the normal request-response messages pattern." #8420 reports connection is closed behind PgBouncer in transaction mode and gives supports_pipeline = False as the workaround. Pipelining is an extra moving part on a path that already has a pooler and a firewall in it, and you can remove it.

The workaround is one line after construction. supports_pipeline is a plain public instance attribute read on every _cursor call, so setting it to False switches writes to conn.transaction(). #8420 proposed a constructor parameter; its PR, #8421, was closed without merge on the day it was opened, 2026-07-23. The sync PostgresSaver is affected in exactly the same way. #8420 claims the sync saver uses psycopg2 and is immune; at 3.1.2 it uses psycopg 3 and carries the identical line.

A run waits on a slow model, a long tool call or a human approval, and a single connection held across that wait is exposed to every idle timer on the path: the pooler, a load balancer, a firewall. Ask your network team for the idle timeout on each hop before you pick numbers; provider defaults pasted in issue comments are not a substitute.

This construction replaces from_conn_string for the async saver. Each line maps to a requirement covered above.

from psycopg.rows import dict_row
from psycopg_pool import AsyncConnectionPool
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

# sslmode=verify-full and the CA path are your PKI's, not defaults
DB_URI = "postgresql://agent_rw@pgbouncer.internal:6432/agents?sslmode=verify-full"

pool = AsyncConnectionPool(
    conninfo=DB_URI,
    min_size=1,
    max_size=4,
    max_lifetime=1800,  # bounds connection age; illustrative, below psycopg's 3600s default
    check=AsyncConnectionPool.check_connection,  # validate on every checkout
    kwargs={
        "autocommit": True,
        "row_factory": dict_row,
        "prepare_threshold": None,  # transaction-mode pooler: no prepared statements
    },
    open=False,
)

async def build_checkpointer() -> AsyncPostgresSaver:
    await pool.open()
    checkpointer = AsyncPostgresSaver(pool)
    # Behind PgBouncer/RDS Proxy/Supavisor: route writes through conn.transaction()
    checkpointer.supports_pipeline = False
    return checkpointer

Construct the saver inside a running event loop: AsyncPostgresSaver.__init__ calls asyncio.get_running_loop(). Pass the pool, never a connection you checked out of it for the whole run, or you are back to one long-lived socket.

max_idle=300 appears in the #3716 and #7304 threads as the cure for a reaper timeout. Read the definition: it only shrinks connections that the pool grew beyond min_size. Since one saver uses one connection at a time, the pool usually sits at min_size, which is exactly where max_idle has no effect. check and max_lifetime act on every connection. A check validates at checkout, so a connection can still die between checkout and the write; it narrows the window rather than closing it.

Two of the six rows have no root cause on record, so what the evidence rules out is the useful part.

Here the on-prem context changes the answer most. In a bank, insurer or hospital, the agent's state lands in the institution's own Postgres, and the checkpoint tables are a step-level record of what the agent saw and did: model inputs, tool arguments, tool outputs, every intermediate state. That is a records object with an owner, an access policy and a retention schedule, and at 3.1.2 the package gives you none of them by default.

The safe unit is the whole thread. Select threads whose newest root checkpoint is older than your retention window, then delete each through the saver so all three tables stay consistent:

STALE_THREADS_SQL = """
    SELECT thread_id
    FROM checkpoints
    WHERE checkpoint_ns = ''
    GROUP BY thread_id
    HAVING max((checkpoint->>'ts')::timestamptz) < now() - %s::interval
"""

async def sweep(pool, checkpointer, retention: str = "90 days") -> int:
    async with pool.connection() as conn:
        rows = await (await conn.execute(STALE_THREADS_SQL, (retention,))).fetchall()
    for row in rows:
        await checkpointer.adelete_thread(row["thread_id"])
    return len(rows)

The "90 days" is a placeholder; the value comes from your records schedule, not from us. The ts expression is unindexed, so run the sweep off-peak or add an expression index. If audit requires the history to outlive the operational window, export threads to the records system before the sweep deletes them. It is the same shape of problem as an LLM gateway's spend logs table: an append-only Postgres table with no default retention, where the obligation should set the window and disk pressure should not.

The same review should settle three more decisions.

For how checkpointing fits into the rest of an agent architecture, see the AI agents pillar.

Grep your services for from_conn_string. For each hit, replace it with the pool construction: autocommit=True, row_factory=dict_row and prepare_threshold=None in the kwargs, check=AsyncConnectionPool.check_connection, a max_lifetime you chose deliberately, and supports_pipeline = False on the saver if any pooler sits between the agent and Postgres. Ask the network team for the idle timeout on every hop and set the libpq keepalive idle value below the shortest one. Then run the pg_terminate_backend drill on staging and confirm the next write recovers. Last, take the stale-thread query to whoever owns the records schedule, agree the window, and schedule the sweep.