feat(checkpoint-postgres)!: align version format and inline primitive storage with Python by WilliamPeralta · Pull Request #1968 · langchain-ai/langgraphjs

WilliamPeralta · 2026-02-17T13:54:23Z

Summary

BREAKING: Align checkpoint version format and channel_values storage with the Python implementation.

Breaking changes:

Version format: getNextVersion now produces zero-padded string versions (e.g. "00000000000000000000000000000001.0482910384729105") instead of integer versions (1, 2, 3).

Migration impact: Existing checkpoints with integer versions will still be readable. New checkpoints will use string versions. Active threads may need to be completed before upgrading, as getNextVersion needs to parse the current version format.
Inline primitives: Primitive channel values (string, number, boolean, null) are now stored inline in the checkpoint JSONB column instead of in checkpoint_blobs. Requires feat(checkpoint-postgres): add task_path support and inline primitive merging #1967 (read-side merge) to be deployed first, so existing readers can handle both formats.

Why:

These changes enable cross-compatibility between Python and JS checkpoint implementations sharing the same database, which is required for hybrid Python/JS LangGraph deployments.

Upgrade path:

Deploy feat(checkpoint-postgres): add task_path support and inline primitive merging #1967 (non-breaking, adds read-side support) to all readers
Then deploy this PR to writers
Old integer-versioned checkpoints remain readable

Test plan

Verify getNextVersion produces correct zero-padded string format
Verify primitive values are stored inline in checkpoint JSONB
Verify complex values are still stored in checkpoint_blobs
Verify read-side correctly merges inline + blob values
Verify existing integer-versioned checkpoints still readable

changeset-bot · 2026-02-17T13:54:28Z

🦋 Changeset detected

Latest commit: 7a85bb7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@langchain/langgraph-checkpoint-postgres	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…s with Python parity fixes Fixes branching bug (#1812), adds task_path support, inline primitives, and globally unique version IDs. Upstream PRs: langchain-ai/langgraphjs#1967, langchain-ai/langgraphjs#1968

WilliamPeralta · 2026-02-17T14:31:06Z

This PR directly addresses #1812 — the branching bug caused by deterministic integer versions in getNextVersion().

Root cause: When branching from the same checkpoint, getNextVersion() produces the same next integer version for both branches (e.g., both get version 3). Since checkpoint_blobs uses ON CONFLICT ... DO NOTHING, the second branch's blob data is silently discarded, corrupting state. MemorySaver is unaffected because it doesn't use version-keyed blob storage.

Fix: getNextVersion() now produces globally unique string versions ("00000000000000000000000000000003.7482910384729105") — zero-padded counter + random hash — ensuring no collisions across branches.

In the meantime, we've published a temporary drop-in replacement package with all fixes from both #1967 and this PR:

npm: @logicpanel/langgraph-checkpoint-postgres
Source: https://github.com/WilliamPeralta/langgraph-checkpoint-postgres

Usage is a one-line import change:

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

We'll deprecate the temporary package once these PRs are merged.

Christian Bromann (christian-bromann)

Can we have some unit tests here to ensure we don't regress in the future?

WilliamPeralta · 2026-02-24T09:16:26Z

Christian Bromann (@christian-bromann) Christian BromannAdded unit tests in src/tests/postgres-saver.test.ts (21 tests) covering:

getNextVersion (8 tests)

Produces correct format: 32-char zero-padded counter + dot + 16-char random hash
Starts at counter 1 when current is undefined
Increments counter correctly from string versions
Backward compat: handles legacy integer versions (e.g. 3 → "0...04.xxx")
Produces unique versions across calls (random hash uniqueness)
Monotonically increasing counters
String sorting works correctly (critical for Postgres ORDER BY)
Format matches Python's f"{next_v:032}.{next_h:016}"

_dumpCheckpoint (4 tests)

Inlines primitive channel_values (string, number, boolean, null) in checkpoint JSONB
Excludes complex values (arrays, objects) from inline storage
Handles empty channel_values
Preserves all other checkpoint fields

_dumpBlobs (5 tests)

Skips primitive values (they go inline in checkpoint)
Includes complex values in blob output
Correctly separates primitives vs complex in mixed scenarios
Returns empty array when no versions
Handles channels with version but missing from values (empty type)

_loadCheckpoint (4 tests)

Merges inline primitives from checkpoint JSONB with blob values
Blob values override inline primitives on key collision
Works with empty blob values (inline-only)
Works with no inline channel_values (backward compat with pre-inline checkpoints)

All passing: pnpm test ✓, pnpm lint ✓, pnpm format:check ✓

WilliamPeralta · 2026-03-02T16:03:37Z

so?

… storage with Python BREAKING: Align checkpoint version format and channel_values storage with the Python implementation. Breaking changes: 1. Version format: getNextVersion now produces zero-padded string versions (e.g. "00000000000000000000000000000001.0482910384729105") instead of integer versions (1, 2, 3). Migration impact: Existing checkpoints with integer versions will still be readable. New checkpoints will use string versions. 2. Inline primitives: Primitive channel values (string, number, boolean, null) are now stored inline in the checkpoint JSONB column instead of in checkpoint_blobs. Requires PR langchain-ai#1967 (read-side merge) to be deployed first, so existing readers can handle both formats. These changes enable cross-compatibility between Python and JS checkpoint implementations sharing the same database, required for hybrid Python/JS LangGraph deployments.

…ne primitive storage Add unit tests covering the changes introduced in this PR: - getNextVersion: format validation, counter increment, backward compat with integer versions, uniqueness, string sorting, Python format parity - _dumpCheckpoint: inline primitive extraction (string, number, boolean, null) vs complex value exclusion - _dumpBlobs: primitive skipping, complex value serialization, mixed value handling - _loadCheckpoint: inline + blob merge, blob-wins-on-collision, backward compat with missing inline values

pkg-pr-new · 2026-03-18T03:30:50Z

Open in StackBlitz

@langchain/langgraph-checkpoint

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint@1968

@langchain/langgraph-checkpoint-mongodb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-mongodb@1968

@langchain/langgraph-checkpoint-postgres

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-postgres@1968

@langchain/langgraph-checkpoint-redis

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-redis@1968

@langchain/langgraph-checkpoint-sqlite

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-sqlite@1968

@langchain/langgraph-checkpoint-validation

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-validation@1968

create-langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/create-langgraph@1968

@langchain/langgraph-api

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-api@1968

@langchain/langgraph-cli

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cli@1968

@langchain/langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph@1968

@langchain/langgraph-cua

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cua@1968

@langchain/langgraph-supervisor

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-supervisor@1968

@langchain/langgraph-swarm

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-swarm@1968

@langchain/langgraph-ui

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-ui@1968

@langchain/langgraph-sdk

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-sdk@1968

commit: 7a85bb7

Christian Bromann (christian-bromann)

I don't think the PR is mergable at current state due to its breaking nature.

Christian Bromann (christian-bromann) · 2026-03-18T03:32:02Z

+      string,
+      Uint8Array | undefined
+    ][] = [];
+    for (const [k, ver] of Object.entries(versions)) {


We should keep Promise.all. For checkpoints with many non-primitive channel values, this serializes all dumpsTyped calls that were previously concurrent.

Christian Bromann (christian-bromann) · 2026-03-18T03:36:46Z

+
+Align checkpoint version format and channel_values storage with the Python implementation:
+
+1. **Version format:** `getNextVersion` now produces zero-padded string versions (e.g. `"00000000000000000000000000000001.0482910384729105"`) instead of integer versions (`1`, `2`, `3`).


I don't think this can be released as minor change. The getNextVersion signature changes the version format stored in Postgres, and the inline primitive storage changes the shape of the checkpoint JSONB column. Both are breaking changes for users who upgrade without first deploying #1967. The PR description itself uses the ! breaking-change marker.

We currently don't plan major releases , so I can't merge this PR in the current form.

Christian Bromann (christian-bromann) · 2026-03-18T03:37:43Z

 * ```
 */
-export class PostgresSaver extends BaseCheckpointSaver {
+export class PostgresSaver extends BaseCheckpointSaver<string | number> {


Since getNextVersion always returns a string, the type parameter should be BaseCheckpointSaver<string>, not BaseCheckpointSaver<string | number>. The union is needed to accept legacy integer values as input, but the output is always a string. The union type leaks into callers and weakens type safety. We should handle the integer input case internally and keep the declared version type as string.

Christian Bromann (christian-bromann) · 2026-03-18T03:38:32Z

+        .padEnd(16, "0")}`;
+    }
+    const currentStr = String(current);
+    const currentV = parseInt(currentStr.split(".")[0], 10) || 0;


The || 0 fallback silently swallows a NaN and a legitimate 0. If parseInt returns NaN (e.g. a malformed version), this produces nextV = 1, which looks like a fresh start and could silently cause a version regression. Use Number.isNaN(parsed) ? 0 : parsed instead:

const parsed = parseInt(currentStr.split(".")[0], 10); const currentV = Number.isNaN(parsed) ? 0 : parsed;

Christian Bromann (christian-bromann) · 2026-03-18T03:39:19Z

+        encoder.encode("json"),
+        encoder.encode(JSON.stringify({ complex: true })),


This test bypasses the real serde (the default JsonPlusSerializer) and manually encodes values as json type. The _loadBlobs method calls this.serde.loadsTyped("json", bytes), if the default serde doesn't handle plain "json" type strings (it uses "msgpack" or "json+" under the hood), this test could pass while the real runtime path fails. Consider using the actual serde round-trip (await saver.serde.dumpsTyped(...)) to produce the blob values in the test, to ensure you're exercising the real deserialization path.

WilliamPeralta mentioned this pull request Feb 17, 2026

checkpoint_blob versions not calculated globally #1812

Open

5 tasks

Christian Bromann (christian-bromann) reviewed Feb 19, 2026

View reviewed changes

WilliamPeralta force-pushed the feat/checkpoint-postgres-version-format branch from 863dddd to d71f9ae Compare February 24, 2026 09:16

WilliamPeralta added 3 commits March 2, 2026 17:19

chore: add changeset for version format alignment

7a85bb7

WilliamPeralta force-pushed the feat/checkpoint-postgres-version-format branch from d71f9ae to 7a85bb7 Compare March 2, 2026 16:20

Youngho Kim (JadenKim-dev) mentioned this pull request Mar 8, 2026

fix(langgraph-checkpoint-redis): use blob storage for channel values to match Python implementation #2039

Open

4 tasks

Christian Bromann (christian-bromann) requested changes Mar 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(checkpoint-postgres)!: align version format and inline primitive storage with Python - #1968

feat(checkpoint-postgres)!: align version format and inline primitive storage with Python#1968
WilliamPeralta wants to merge 3 commits into
langchain-ai:mainfrom
WilliamPeralta:feat/checkpoint-postgres-version-format

WilliamPeralta commented Feb 17, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Feb 17, 2026 •

edited

Loading

Uh oh!

WilliamPeralta commented Feb 17, 2026

Uh oh!

Christian Bromann (christian-bromann) left a comment

Uh oh!

WilliamPeralta commented Feb 24, 2026 •

edited

Loading

Uh oh!

WilliamPeralta commented Mar 2, 2026

Uh oh!

pkg-pr-new Bot commented Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) left a comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Align checkpoint version format and channel_values storage with the Python implementation:

		1. Version format: `getNextVersion` now produces zero-padded string versions (e.g. `"00000000000000000000000000000001.0482910384729105"`) instead of integer versions (`1`, `2`, `3`).

		encoder.encode("json"),
		encoder.encode(JSON.stringify({ complex: true })),

Uh oh!

Conversation

WilliamPeralta commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes:

Why:

Upgrade path:

Test plan

Uh oh!

changeset-bot Bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

WilliamPeralta commented Feb 17, 2026

Uh oh!

Christian Bromann (christian-bromann) left a comment

Choose a reason for hiding this comment

Uh oh!

WilliamPeralta commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WilliamPeralta commented Mar 2, 2026

Uh oh!

pkg-pr-new Bot commented Mar 18, 2026

Uh oh!

Christian Bromann (christian-bromann) left a comment

Choose a reason for hiding this comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Christian Bromann (christian-bromann) Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

WilliamPeralta commented Feb 17, 2026 •

edited

Loading

changeset-bot Bot commented Feb 17, 2026 •

edited

Loading

WilliamPeralta commented Feb 24, 2026 •

edited

Loading