langchain-ai / langchain-ai/langgraph

Harden shallow Postgres migration guards against mixed-state schema

Open
#6,902 3 comments 0 reactions 0 assignees View on GitHub
external
Dominant language
Python
Stars
41.8k
Forks
7.1k
Avg merge
23h 7m
Merged PRs (30d)
30

Description

## Problem
`ShallowPostgresSaver` setup currently trusts migration version rows and can proceed even when shallow schema objects are missing, allowing mixed-state reads/writes after partial/manual migration drift.

## Why Now
Shallow migration paths are still in use, and mixed-state semantics create durable data debt and hard-to-debug runtime failures.

## Impact
Runtimes can appear initialized while required shallow tables/columns are absent.

## Evidence Packet
- Version/commit: `eaad5b83`
- Environment: `Darwin 25.3.0 arm64`, `Python 3.14.0`
- Minimal repro:
1. Create `checkpoint_migrations` table manually.
2. Insert a latest-version row without creating shallow checkpoint tables.
3. Call `ShallowPostgresSaver.setup()` and then use saver reads.
- Expected: setup fails closed on incomplete shallow schema.
- Actual: setup can proceed using migration version alone, deferring failures to reads/writes.

## Why Code (not docs)
Safety guarantees must be enforced at runtime setup; docs cannot prevent mixed-state boot.

## Codepaths
- `libs/checkpoint-postgres/langgraph/checkpoint/postgres/shallow.py`
- `libs/checkpoint-postgres/tests/test_sync.py`
- `libs/langgraph/tests/test_checkpoint_migration.py`

## Acceptance
- Setup verifies shallow schema invariants, not just migration version.
- Incomplete schema fails immediately with actionable error.
- Regression tests cover malformed migration-state startup.

Contributor guide

Open the contributing guide

Research direction

Start in libs/checkpoint-postgres/langgraph/checkpoint/postgres/shallow.py and trace ShallowPostgresSaver.setup() alongside the migration-state handling. Review libs/checkpoint-postgres/tests/test_sync.py and libs/langgraph/tests/test_checkpoint_migration.py, then add regression coverage for a latest-version row with missing shallow schema objects. Done means setup fails immediately with an actionable error and verifies the shallow schema beyond the migration version.

Written by the indexing model from the issue text.

Assessment

Tech stack
postgresql, python
Domain
databases
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.