Environment:Langchain ai Langgraph Postgres Checkpoint Environment

Knowledge Sources	LangGraph Checkpoint Postgres LangGraph Persistence
Domains	Infrastructure, Database, Persistence
Last Updated	2026-02-11 14:00 GMT

Overview

PostgreSQL environment with `psycopg` async driver and connection pooling for production-grade LangGraph checkpoint and store persistence.

Description

This environment provides the PostgreSQL database backend for LangGraph checkpoint persistence and key-value store operations. It uses the `psycopg` v3 async driver with connection pooling via `psycopg-pool`. The package supports both synchronous and asynchronous checkpoint savers, with the async variant (`AsyncPostgresSaver`) recommended for production use. JSON serialization uses `orjson` for performance. The store implementation supports vector search via the `pgvector` extension when embeddings are configured.

Usage

Use this environment when deploying LangGraph applications in production settings that require durable, concurrent checkpoint persistence. It is the recommended backend for any multi-user or multi-thread deployment, replacing `InMemorySaver` (testing only) and `SqliteSaver` (single-writer limitation).

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	All platforms with PostgreSQL client support
PostgreSQL	>= 14	Server with vector extension support (optional for store search)
Network	TCP port 5432	Default PostgreSQL port; configurable via connection string
Disk	1GB+	Depends on checkpoint volume and retention

Dependencies

System Packages

`libpq-dev` or equivalent (PostgreSQL client library, needed to compile `psycopg`)

Python Packages

`langgraph-checkpoint-postgres` >= 3.0.4
`langgraph-checkpoint` >= 2.1.2, < 5.0.0
`psycopg` >= 3.2.0
`psycopg-pool` >= 3.2.0
`orjson` >= 3.10.1

Optional

`psycopg[binary]` (pre-compiled binary for easier installation)
`pgvector` PostgreSQL extension (for vector search in store)

Credentials

`DATABASE_URL` or connection string: PostgreSQL connection URI (e.g., `postgres://user:pass@host:5432/dbname`)
No LangGraph-specific environment variables; connection is passed programmatically

Quick Install

# Install with binary driver (recommended for quick setup)
pip install "langgraph-checkpoint-postgres" "psycopg[binary]"

# Or install with source driver (requires libpq-dev)
pip install langgraph-checkpoint-postgres

Code Evidence

Package dependencies from `libs/checkpoint-postgres/pyproject.toml:25-30`:

dependencies = [
    "langgraph-checkpoint>=2.1.2,<5.0.0",
    "orjson>=3.10.1",
    "psycopg>=3.2.0",
    "psycopg-pool>=3.2.0",
]

Default PostgreSQL URI used in Docker deployments from `libs/cli/langgraph_cli/docker.py:12`:

DEFAULT_POSTGRES_URI = (
    "postgres://postgres:postgres@langgraph-postgres:5432/postgres?sslmode=disable"
)

Common Errors

Error Message	Cause	Solution
`psycopg.OperationalError: connection refused`	PostgreSQL server not running or unreachable	Start PostgreSQL server and verify host/port
`Error: pg_config executable not found`	Missing `libpq-dev` when building from source	Install `libpq-dev` (Debian/Ubuntu) or use `psycopg[binary]`
`relation "checkpoints" does not exist`	Database tables not yet created	The saver auto-creates tables on first use via `setup()`

Compatibility Notes

Async recommended: Use `AsyncPostgresSaver` for production to avoid blocking the event loop
Connection pooling: `psycopg-pool` manages connection reuse; configure pool size based on concurrency
Vector search: Store search with embeddings requires the `pgvector` PostgreSQL extension
Docker Compose: The CLI auto-provisions a PostgreSQL container with default credentials in the generated compose file

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment