@logicpanel/langgraph-checkpoint-postgres

Temporary drop-in replacement for @langchain/langgraph-checkpoint-postgres with critical bug fixes ported from the Python implementation.

This package will be deprecated once the upstream PRs are merged.

Why does this package exist?

The official @langchain/langgraph-checkpoint-postgres has several gaps compared to the Python equivalent that cause real bugs in production:

Branching is broken (#1812)

getNextVersion() produces deterministic integer versions (1, 2, 3...). When branching from the same checkpoint, two branches produce the same next version, causing checkpoint_blobs rows to collide via ON CONFLICT ... DO NOTHING. The second branch's blob data is silently discarded, corrupting state.

MemorySaver works fine because it doesn't have version-keyed blob storage. PostgresSaver is broken.

Missing task_path column

The Python implementation added task_path to checkpoint_writes for deterministic ordering of pending sends from nested subgraphs and parallel branches. The JS implementation never ported this.

No inline primitive support

Python stores primitive channel_values (string, number, boolean, null) inline in the checkpoint JSONB column for efficiency. The JS implementation can't read these correctly, breaking cross-language compatibility.

What this package fixes

| Fix | Description | Upstream PR | |-----|-------------|-------------| | Branching collisions | getNextVersion() produces globally unique string versions (zero-padded counter + random hash) | #1968 | | task_path support | Migrations 5-9, putWrites() with task_path column | #1967 | | Thread indexes | CREATE INDEX on thread_id for checkpoints, checkpoint_blobs, checkpoint_writes | #1967 | | Inline primitives (write) | Primitive channel_values stored inline in checkpoint JSONB | #1968 | | Inline primitives (read) | Merges inline primitives from JSONB with blob values (Python compat) | #1967 |

Installation

npm install @logicpanel/langgraph-checkpoint-postgres

Peer dependencies (you likely already have these):

npm install @langchain/langgraph-checkpoint-postgres @langchain/langgraph-checkpoint @langchain/core pg

Usage

// Before:
import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";

// After (just change the import):
import { PostgresSaver } from "@logicpanel/langgraph-checkpoint-postgres";

// Everything else stays the same
const checkpointer = PostgresSaver.fromConnString(process.env.DATABASE_URL);
await checkpointer.setup();

Schema support

const checkpointer = new PostgresSaver(pool, undefined, { schema: "my_schema" });

How it works

This package extends the official PostgresSaver class and overrides:

• setup() - Runs the original migrations (0-4) then applies migrations 5-9 (thread_id indexes + task_path column)
• putWrites() - Includes the task_path column in INSERT statements (9 columns instead of 8)
• getNextVersion() - Produces "00000000000000000000000000000003.7482910384729105" instead of 3, making versions globally unique across branches
• _dumpCheckpoint() - Stores primitive values inline in checkpoint JSONB
• _dumpBlobs() - Skips primitive values (already stored inline)
• _loadCheckpoint() - Merges inline primitives from JSONB with blob values

Upstream PRs

We've submitted these fixes to the official repository:

• #1967 - Non-breaking: task_path support, migrations 5-9, read-side inline primitives
• #1968 - Breaking: getNextVersion() string format, write-side inline primitives

Once these PRs are merged and released, this package will be deprecated in favor of the official @langchain/langgraph-checkpoint-postgres.

Related

• langchain-ai/langgraphjs#1812 - Branching bug report
• langgraph-checkpoint-postgres (Python) - Reference implementation