Implementation:Langchain ai Langgraph PostgresCheckpointBase

Knowledge Sources	Langchain_ai_Langgraph
Domains	Checkpointing, Postgres
Last Updated	2026-02-11 16:00 GMT

Overview

`BasePostgresSaver` is the abstract base class for all Postgres checkpoint savers, providing shared SQL query constants, serialization utilities, and version management logic.

Description

`BasePostgresSaver` extends `BaseCheckpointSaver[str]` and serves as the foundation for both synchronous and asynchronous Postgres checkpoint implementations. It centralizes all SQL query definitions as class attributes, including `SELECT_SQL` for checkpoint retrieval with joined blob and write data, `UPSERT_CHECKPOINTS_SQL` and `UPSERT_CHECKPOINT_BLOBS_SQL` for saving checkpoints and their binary data, and `UPSERT_CHECKPOINT_WRITES_SQL` / `INSERT_CHECKPOINT_WRITES_SQL` for persisting intermediate writes.

The class also defines a comprehensive migration system through the `MIGRATIONS` list, which contains SQL statements for creating the `checkpoint_migrations`, `checkpoints`, `checkpoint_blobs`, and `checkpoint_writes` tables along with their indexes. Each migration is versioned and tracked in the `checkpoint_migrations` table to ensure idempotent schema updates.

In addition to SQL constants, `BasePostgresSaver` provides helper methods for data transformation: `_load_blobs` and `_dump_blobs` handle binary channel value serialization, `_load_writes` and `_dump_writes` manage intermediate write serialization, `_search_where` builds parameterized WHERE clauses for listing checkpoints, and `get_next_version` generates monotonically increasing version identifiers with random suffixes for conflict avoidance.

Usage

`BasePostgresSaver` is not intended to be used directly. It is subclassed by `AsyncPostgresSaver` (and its shallow variant) to provide the actual checkpoint persistence implementation. Use this base class when you need to understand the database schema, SQL queries, or serialization logic shared across all Postgres checkpoint savers.

Code Reference

Source Location

• Repository: Langchain_ai_Langgraph
• File: libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py
• Lines: 1-315

Signature

class BasePostgresSaver(BaseCheckpointSaver[str]):
    SELECT_SQL = SELECT_SQL
    SELECT_PENDING_SENDS_SQL = SELECT_PENDING_SENDS_SQL
    MIGRATIONS = MIGRATIONS
    UPSERT_CHECKPOINT_BLOBS_SQL = UPSERT_CHECKPOINT_BLOBS_SQL
    UPSERT_CHECKPOINTS_SQL = UPSERT_CHECKPOINTS_SQL
    UPSERT_CHECKPOINT_WRITES_SQL = UPSERT_CHECKPOINT_WRITES_SQL
    INSERT_CHECKPOINT_WRITES_SQL = INSERT_CHECKPOINT_WRITES_SQL

Import

from langgraph.checkpoint.postgres.base import BasePostgresSaver

I/O Contract

Inputs

Name	Type	Required	Description
serde	None	No	Custom serializer protocol for encoding/decoding checkpoint data. Inherited from `BaseCheckpointSaver`.

Outputs

Name	Type	Description
BasePostgresSaver	BasePostgresSaver	An abstract base instance providing SQL constants and helper methods for Postgres checkpoint persistence.

Database Schema

The class defines migrations for the following tables:

Table	Description
checkpoint_migrations	Tracks applied migration versions.
checkpoints	Stores checkpoint data with thread_id, checkpoint_ns, and checkpoint_id as composite primary key.
checkpoint_blobs	Stores serialized binary channel values keyed by thread, namespace, channel, and version.
checkpoint_writes	Stores intermediate task writes linked to specific checkpoints.

Key Helper Methods

Method	Description
_load_blobs(blob_values)	Deserializes binary blob data back into channel values.
_dump_blobs(thread_id, checkpoint_ns, values, versions)	Serializes channel values into blob tuples for database storage.
_load_writes(writes)	Deserializes raw write data into structured tuples.
_dump_writes(thread_id, ...)	Serializes write data for database insertion.
get_next_version(current, channel)	Generates the next monotonically increasing version identifier.
_search_where(config, filter, before)	Builds parameterized WHERE clause for checkpoint listing.

Usage Examples

# BasePostgresSaver is not used directly. It is subclassed by AsyncPostgresSaver.
# Here is how the SQL constants are accessed:

from langgraph.checkpoint.postgres.base import BasePostgresSaver

# Access migration definitions
migrations = BasePostgresSaver.MIGRATIONS
print(f"Number of migrations: {len(migrations)}")

# Access the SELECT query used for checkpoint retrieval
print(BasePostgresSaver.SELECT_SQL)

Related Pages

• Principle:Langchain_ai_Langgraph_Checkpoint_Backend_Selection