Proposal: additional docs for implementing custom DB checkpointers or a guide on generic base checkpointer

OSS Product Help LangGraph
, , ,
1

Currently I’m guessing a lot of agent PoC made with LangGraph is preparing to get to production level, and so is my project, and some projects that needs to be deployed on-prem, database licensing of the client’s side is a problem and therefore I’m assuming that lots of potential langgraph users will be having to create their own implementation of checkpointers, with considerations to the orms like sqlalchemy

As the base checkpointers of multiple DB kinds are subject to updates such as the recent DeltaChannel releases(great work btw!), I’m not expecting for the LangGraph team to be widening integration supports for multiple kinds of Databases, I think documenting and sharing a good guide on the custom checkpointers for DB is going to be enough for lots of LangGraph users in institutions. Even in the r/LangChain, there is weekly post on the best agentic framework for production level project and nobody seems to be having a clear answer for that. I think, so far I haven’t seen no other agentic frameworks keeping a production-friendly guide yet. I think similar kinds of production-level guidances will be help you build a good reputations and userbase.

Thanks

2

Hello @Wonder-donbury, welcome to Langchain community

Great suggestion, and this is a real need for on-prem deployments. Here’s what already exists and how to proceed today:

1. The BaseCheckpointSaver interface is your entry point

All checkpointers conform to BaseCheckpointSaver from langgraph-checkpoint. You need to implement four core async methods:

Method Purpose
aput Store a checkpoint
aput_writes Store pending node writes
aget_tuple Fetch a checkpoint by config
alist List checkpoints by config/filter

For deploying behind LangSmith Agent Server, you also need adelete_thread, and optionally adelete_for_runs, acopy_thread, and aprune for extended capabilities.

Reference: Persistence — Checkpointer interface

2. There is an official “how to use a custom checkpointer” guide

The guide covers defining an async context manager that yields your BaseCheckpointSaver, wiring it into langgraph.json, and validating it against the conformance suite:

Reference: How to use a custom checkpointer (LangSmith deployment)

3. Validate against the conformance suite before deploying

pip install langgraph-checkpoint-conformance

from langgraph.checkpoint.conformance import checkpointer_test, validate

@checkpointer_test(name="MyCheckpointer")
async def my_checkpointer():
    async with MyCheckpointer(...) as saver:
        yield saver

report = await validate(my_checkpointer)
report.print_report()
assert report.passed_all_base()

This suite auto-detects which extended capabilities your implementation provides and confirms it is compatible with Agent Server.

4. Reference the Postgres source as a model implementation

The Postgres checkpointer (langgraph-checkpoint-postgres) is the production reference. Studying PostgresSaver / AsyncPostgresSaver is the fastest way to understand the full contract, the put, put_writes, get_tuple, and list implementations map 1:1 to any SQL-backed store (including SQLAlchemy-wrapped DBs).

  • Installed packages: libs/checkpoint-postgres/ in the LangGraph repo
  • Reference: Checkpoint packages

5. For SQLite as a local/dev pattern, use SqliteSaver as a simpler reference

langgraph-checkpoint-sqlite is a lighter reference for writing a SQL-based checkpointer with minimal complexity, good starting point before scaling to your target DB.

Summary for on-prem / custom DB scenarios:

  1. Subclass BaseCheckpointSaver and implement the four required async methods using your ORM/DB driver of choice.
  2. Wrap it in an asynccontextmanager that handles connection lifecycle.
  3. Validate with langgraph-checkpoint-conformance.
  4. Point langgraph.json → checkpointer.path to your context manager.

The conformance suite and the custom checkpointer guide address most of the gaps you’ve described. The ask for a more narrative how-to guide specifically walking through an ORM/SQLAlchemy-based implementation is a valid gap worth filing as a docs issue on the GitHub - langchain-ai/docs: Unified LangChain documentation. · GitHub