npm package: @logicpanel/langgraph-checkpoint-postgres
Description: Drop-in replacement for @langchain/langgraph-checkpoint-postgres with Python parity fixes (branching, task_path, inline primitives)
Latest version: 1.0.1

# @logicpanel/langgraph-checkpoint-postgres

**Temporary** drop-in replacement for [`@langchain/langgraph-checkpoint-postgres`](https://www.npmjs.com/package/@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](https://github.com/langchain-ai/langgraphjs/issues/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](https://github.com/langchain-ai/langgraphjs/pull/1968) |
| `task_path` support | Migrations 5-9, `putWrites()` with `task_path` column | [#1967](https://github.com/langchain-ai/langgraphjs/pull/1967) |
| Thread indexes | `CREATE INDEX` on `thread_id` for checkpoints, checkpoint_blobs, checkpoint_writes | [#1967](https://github.com/langchain-ai/langgraphjs/pull/1967) |
| Inline primitives (write) | Primitive channel_values stored inline in checkpoint JSONB | [#1968](https://github.com/langchain-ai/langgraphjs/pull/1968) |
| Inline primitives (read) | Merges inline primitives from JSONB with blob values (Python compat) | [#1967](https://github.com/langchain-ai/langgraphjs/pull/1967) |

## Installation

```bash
npm install @logicpanel/langgraph-checkpoint-postgres
```

Peer dependencies (you likely already have these):
```bash
npm install @langchain/langgraph-checkpoint-postgres @langchain/langgraph-checkpoint @langchain/core pg
```

## Usage

```typescript
// 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

```typescript
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](https://github.com/langchain-ai/langgraphjs/pull/1967) - Non-breaking: `task_path` support, migrations 5-9, read-side inline primitives
- [#1968](https://github.com/langchain-ai/langgraphjs/pull/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](https://github.com/langchain-ai/langgraphjs/issues/1812) - Branching bug report
- [langgraph-checkpoint-postgres (Python)](https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres) - Reference implementation