langchain-ai / langchain-ai/langgraph
Harden shallow Postgres migration guards against mixed-state schema
- 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
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