Feature request: Configurable PostgreSQL schema for langgraph-checkpoint-postgres (parity with LangGraphJS)

Privileged issue

• I am a LangGraph maintainer.

Issue Content

Summary

Add optional PostgreSQL schema selection to the langgraph-checkpoint-postgres package (PostgresSaver / AsyncPostgresSaver), so checkpoint tables and queries can target a non-public schema without relying on connection search_path.

This would align the Python implementation with LangGraphJS, which already merged explicit schema support (e.g. PostgresSaver.fromConnString(..., { schema: "..." }) in langgraphjs PR #838).

Motivation / problem

Today, Python checkpoint DDL/DML uses unqualified table names (checkpoints, checkpoint_blobs, checkpoint_writes, checkpoint_migrations). Resolution depends on the session search_path, which:

• Is easy to misconfigure with connection pools, PgBouncer (especially transaction pooling), and multi-tenant setups.

Enterprise and multi-tenant deployments often need one schema per tenant while sharing a single database and connection pool.

Proposed behavior

1. Optional schema name (default "public") applied consistently to:

   • All migration strings (CREATE TABLE, ALTER, indexes, etc.)
   • All runtime SQL (SELECT, INSERT, UPSERT, DELETE)

2. Safe identifier handling — validate or use a documented quoting strategy

3. Public API sketch for example:

   • PostgresSaver(conn, ..., schema: str | None = None)
   • AsyncPostgresSaver(conn, ..., schema: str | None = None)
   • If from_conn_string exists, mirror JS: optional schema in a small options/kwargs object.

4. setup() creates and migrates tables in the configured schema; runtime reads/writes use the same schema (no split “setup vs runtime” path).

5. Backward compatibility: omitting the parameter preserves current behavior (tables in whatever search_path resolves to today, typically public).

Acceptance criteria (suggested)

• Documented public API for schema selection.
• Integration tests: default schema + at least one non-public schema (create schema in fixture, run setup(), put/get/list checkpoints).
• Changelog / release note.
• Short doc note cross-linking JS behavior for teams on both stacks.

Alternatives considered

• Rely on search_path only — works in simple setups but is fragile with pools, PgBouncer transaction mode, and mixed-tenant reuse of physical connections
• Application-level pool subclassing — possible but duplicates logic, breaks on upstream SQL changes, and is hard to maintain across versions.

Environment (optional)

• langgraph-checkpoint-postgres version: 3.0.4
• langgraph version: 1.1.3
• Python: 3.12

Related

• langgraphjs PR #838 – custom schema for checkpoint-postgres