LangGraph Checkpoint Postgres

To help you ship LangGraph apps to production faster, check out LangSmith. LangSmith is a unified developer platform for building, testing, and monitoring LLM applications.

Quick Install

uv add langgraph-checkpoint-postgres

🤔 What is this?

This library provides a Postgres implementation of LangGraph's checkpoint saver. Use it when you want LangGraph state persistence backed by Postgres for durable, long-running workflows and agents.

By default, langgraph-checkpoint-postgres installs psycopg (Psycopg 3) without any extras. You can choose a specific installation that best suits your needs in the Psycopg installation docs, for example psycopg[binary].

📖 Documentation

For full documentation, see the API reference. For conceptual guides on persistence and memory, see the LangGraph Docs.

Security

[!IMPORTANT] Set LANGGRAPH_STRICT_MSGPACK=true or pass an explicit allowed_msgpack_modules list when creating your checkpointer. This restricts checkpoint deserialization to known-safe types, preventing code execution if the database is compromised. See the langgraph-checkpoint README for details.

Usage

[!IMPORTANT] When using Postgres checkpointers for the first time, make sure to call .setup() method on them to create required tables. See example below.

[!IMPORTANT] When manually creating Postgres connections and passing them to PostgresSaver or AsyncPostgresSaver, make sure to include autocommit=True and row_factory=dict_row (from psycopg.rows import dict_row). See a full example in this how-to guide.

Why these parameters are required:

autocommit=True: Required for the .setup() method to properly commit the checkpoint tables to the database. Without this, table creation may not be persisted.

row_factory=dict_row: Required because the PostgresSaver implementation accesses database rows using dictionary-style syntax (e.g., row["column_name"]). The default tuple_row factory returns tuples that only support index-based access (e.g., row[0]), which will cause TypeError exceptions when the checkpointer tries to access columns by name.

Example of incorrect usage:
# ❌ This will fail with TypeError during checkpointer operations
with psycopg.connect(DB_URI) as conn:  # Missing autocommit=True and row_factory=dict_row
    checkpointer = PostgresSaver(conn)
    checkpointer.setup()  # May not persist tables properly
    # Any operation that reads from database will fail with:
    # TypeError: tuple indices must be integers or slices, not str

from langgraph.checkpoint.postgres import PostgresSaver

write_config = {"configurable": {"thread_id": "1", "checkpoint_ns": ""}}
read_config = {"configurable": {"thread_id": "1"}}

DB_URI = "postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    # call .setup() the first time you're using the checkpointer
    checkpointer.setup()
    checkpoint = {
        "v": 4,
        "ts": "2024-07-31T20:14:19.804150+00:00",
        "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
        "channel_values": {"my_key": "meow", "node": "node"},
        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
        "versions_seen": {
            "__input__": {},
            "__start__": {"__start__": 1},
            "node": {"start:node": 2},
        },
    }

    # store checkpoint
    checkpointer.put(write_config, checkpoint, {}, {})

    # load checkpoint
    checkpointer.get(read_config)

    # list checkpoints
    list(checkpointer.list(read_config))

Async

from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpoint = {
        "v": 4,
        "ts": "2024-07-31T20:14:19.804150+00:00",
        "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
        "channel_values": {"my_key": "meow", "node": "node"},
        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
        "versions_seen": {
            "__input__": {},
            "__start__": {"__start__": 1},
            "node": {"start:node": 2},
        },
    }

    # store checkpoint
    await checkpointer.aput(write_config, checkpoint, {}, {})

    # load checkpoint
    await checkpointer.aget(read_config)

    # list checkpoints
    [c async for c in checkpointer.alist(read_config)]

📕 Releases & Versioning

See our Releases and Versioning policies.

💁 Contributing

As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.

For detailed information on how to contribute, see the Contributing Guide.

Metadata

Release files for langgraph-checkpoint-postgres 3.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langgraph-checkpoint-postgres 3.1.2
File	Size	Uploaded
langgraph_checkpoint_postgres-3.1.2.tar.gz	155.1 kB	Aug 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for langgraph-checkpoint-postgres 3.1.2
File	Interpreter	ABI	Platform	Reset
langgraph_checkpoint_postgres-3.1.2-py3-none-any.whl 52.1 kB Aug 7, 2026	Python 3	none	any	Details

Total release size: 207.2 kB

Release files / langgraph_checkpoint_postgres-3.1.2.tar.gz

Download URL	langgraph_checkpoint_postgres-3.1.2.tar.gz
Size	155.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`1cd404803ff895a2b79f3ac04ce92b775e6b999715f8333fce674c6d927bba95`
BLAKE2b-256 checksum How to use checksums	`9d526e732f7bf702ef4918b64ea4107e7da21d4276b808f9a651fe34be9b0abe`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / langgraph_checkpoint_postgres-3.1.2-py3-none-any.whl

Download URL	langgraph_checkpoint_postgres-3.1.2-py3-none-any.whl
Size	52.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6a7e38ef16985b54e356cba7bdaf447943aae33d5aaf290026c593bb6b4a6264`
BLAKE2b-256 checksum How to use checksums	`0f628899c9f4d9b97d5b3eb0c07c13cdf5f63342f15f5ef93eaf3477958df602`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`