Skip to content
⚠️ Before You Start
Risk: Medium
Duration: Half a day
Last Validated: Not yet validated (draft)
Kind: How-to
Risk Note: Medium (misconfigured connection or missing setup breaks every run)

Set up LangGraph checkpointer and store on Azure Database for PostgreSQL

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-12-24). Author: Sanjay Sarvesh · dry-run: Yasar · sign-off: James. Work items: AGT-04-T05, AGT-04-T06, AGT-04-T07, AGT-04-T08.

1. Summary

When an agent moves from in-memory state to durable memory, or a new environment is created.

Risk: Medium (misconfigured connection or missing setup breaks every run). Typical duration: Half a day.

2. When to use and when not to

Use it when: When an agent moves from in-memory state to durable memory, or a new environment is created.

Do not use it when: to be written by the author.

3. What you must know first

  • PostgresSaver comes from langgraph-checkpoint-postgres and needs setup() once
  • thread_id should stay short; the docs note a length limit for Postgres
  • PostgresStore holds cross-thread memory with namespaces
  • EncryptedSerializer can encrypt checkpoints with an AES key
  • Flexible server supports zone-redundant HA and point-in-time restore

4. Prerequisites and access

  • Azure Database for PostgreSQL flexible server with pgvector if semantic search is used
  • Entra or password auth configured and stored in Key Vault
  • langgraph-checkpoint-postgres installed
  • Network access from the agent host

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Create a database and a least-privilege role for the agent
  2. Store the connection string in Key Vault and load it at start
  3. Run checkpointer.setup() and store.setup() from a migration job, not the app
  4. Compile the graph with checkpointer and store
  5. Write and read one memory item and one thread in sandbox
  6. Restart the app and confirm the thread resumes
  7. Enable backups and confirm the restore window

Draft snippet: PostgresSaver and PostgresStore wired into a graph

from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.store.postgres import PostgresStore

DB_URI = "${PG_CONN_STRING}"  # Azure Database for PostgreSQL, sslmode=require


def respond(state: MessagesState) -> dict:
    return {"messages": [("ai", "Noted.")]}


with PostgresSaver.from_conn_string(DB_URI) as checkpointer, \
        PostgresStore.from_conn_string(DB_URI) as store:
    checkpointer.setup()  # creates checkpoint tables; run once per release
    store.setup()

    ns = ("tenant-a", "user-123", "preferences")
    store.put(ns, "seat", {"text": "Prefers window seats"})
    print([item.value for item in store.search(ns, limit=5)])

    builder = StateGraph(MessagesState)
    builder.add_node("respond", respond)
    builder.add_edge(START, "respond")
    builder.add_edge("respond", END)
    graph = builder.compile(checkpointer=checkpointer, store=store)

    cfg = {"configurable": {"thread_id": "tenant-a:user-123:s1"}}
    graph.invoke({"messages": [("user", "Book my usual seat")]}, cfg)
    print(graph.get_state(cfg).values["messages"][-1])

Snippets to add:

  • snippets/templates/memory/setup_pg.py: Checkpointer and store wiring (python)
  • snippets/ops/run_memory_migrations.sh: Migration job that runs setup() (bash)

6. Verify it works

A second engineer sets up a fresh sandbox database using the playbook, writes a thread and a memory item, restarts the app and passes when both are read back.

7. Known issues and fixes

Symptom Likely cause Fix
Tables missing at first run setup() not executed Run the migration job before deploying
Connection errors under load Too many connections per pod Use a connection pool and size it to the server tier
Threads lost after restart In-memory saver still used in one code path Search for InMemorySaver and replace it

8. Monitoring and alerts

Signal Alert when Action
PostgreSQL connection failures from agent hosts More than 5 in 5 minutes Check network, credentials and pool size
Database storage used Above 80 percent Run the retention job and review growth

9. AWS and open-source equivalents

On AWS use Amazon RDS or Aurora PostgreSQL with the same packages, or AgentCore Memory. Redis and MongoDB stores exist for LangGraph too.

10. Validation record

Pending. Planned dry-run scenario: A second engineer sets up a fresh sandbox database using the playbook, writes a thread and a memory item, restarts the app and passes when both are read back.

11. Sources