{"id":2094,"library":"langgraph-checkpoint-postgres","title":"LangGraph Postgres Checkpoint","description":"langgraph-checkpoint-postgres provides a robust PostgreSQL implementation of LangGraph's checkpoint saver interface. This allows LangGraph agents to persist their conversational state and execution history in a Postgres database, enabling fault tolerance and the ability to resume graphs from previous states. Currently at version 3.0.5, it follows the rapid release cycle of the broader LangChain/LangGraph ecosystem, with frequent updates tied to `langgraph`'s release schedule.","status":"active","version":"3.0.5","language":"en","source_language":"en","source_url":"https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres","tags":["langgraph","checkpoint","postgres","database","state-management","ai","llm"],"install":[{"cmd":"pip install langgraph-checkpoint-postgres","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core LangGraph functionality and CheckpointSaver interface.","package":"langgraph>=1.0.0"},{"reason":"PostgreSQL adapter for Python; required for database connectivity.","package":"psycopg2-binary"}],"imports":[{"symbol":"PostgresSaver","correct":"from langgraph_checkpoint_postgres import PostgresSaver"}],"quickstart":{"code":"import os\nfrom langgraph.graph import StateGraph, START\nfrom langgraph.checkpoint.base import Checkpoint\nfrom langgraph_checkpoint_postgres import PostgresSaver\n\n# Define a simple graph state (must be mutable for in-place updates)\nclass AgentState:\n    def __init__(self, value: int = 0):\n        self.value = value\n\n    def __repr__(self):\n        return f\"AgentState(value={self.value})\"\n\n# Define simple node functions that modify the state\ndef increment_node(state: AgentState):\n    state.value += 1\n    print(f\"Node 'increment': value = {state.value}\")\n    return state\n\ndef decrement_node(state: AgentState):\n    state.value -= 1\n    print(f\"Node 'decrement': value = {state.value}\")\n    return state\n\n# Setup PostgresSaver\n# Ensure a PostgreSQL database is running and accessible with the connection string.\n# The necessary schema for langgraph checkpoints must be initialized in your DB beforehand.\n# Example connection string: \"postgresql://user:password@host:port/database_name\"\npg_connection_string = os.environ.get(\n    \"POSTGRES_CONNECTION_STRING\", \n    \"postgresql://user:password@localhost:5432/langgraph_db\"\n) # Replace with your actual connection string or set ENV var\n\nsaver = PostgresSaver(conn_string=pg_connection_string)\n\n# Build the graph\nbuilder = StateGraph(AgentState)\nbuilder.add_node(\"increment\", increment_node)\nbuilder.add_node(\"decrement\", decrement_node)\nbuilder.add_edge(START, \"increment\")\nbuilder.add_edge(\"increment\", \"decrement\")\n# Create a loop for multiple steps, with a conditional exit\nbuilder.add_conditional_edges(\n    \"decrement\",\n    # If value is less than 3, go back to 'increment', otherwise end\n    lambda state: \"increment\" if state.value < 3 else \"__end__\",\n    {\"increment\": \"increment\", \"__end__\": \"__end__\"}\n)\n\n# Compile the graph with the checkpointer\n# interrupt_after allows viewing state at specific nodes during stream\napp = builder.compile(checkpointer=saver, interrupt_after=[\"increment\", \"decrement\"])\n\n# Example usage:\n# A unique thread_id is crucial for checkpointing different conversations\nthread_id = \"my_unique_conversation_123\"\nconfig = {\"configurable\": {\"thread_id\": thread_id, \"thread_ts\": \"\"}}\n\nprint(f\"\\n--- Starting run for thread: {thread_id} ---\")\n# Start the graph from an initial state\nfor step in app.stream(AgentState(value=0), config, stream_mode=\"updates\"):\n    print(f\"Stream update: {step}\")\n\n# Simulate a pause or application restart\nprint(f\"\\n--- Resuming run for thread: {thread_id} ---\")\n# Pass None as input to resume from the last saved state for the given thread_id\nfor step in app.stream(None, config, stream_mode=\"updates\"):\n    print(f\"Stream update: {step}\")\n\n# Retrieve the final state directly from the saver\nlast_checkpoint: Checkpoint = saver.get(config)\nif last_checkpoint and '__root__' in last_checkpoint.channel_values:\n    final_state_value = last_checkpoint.channel_values['__root__'].value\n    print(f\"\\nFinal state value retrieved from checkpoint: {final_state_value}\")\nelse:\n    print(\"\\nNo final state found or __root__ channel missing.\")\n","lang":"python","description":"This quickstart demonstrates how to integrate `PostgresSaver` with a basic `StateGraph`. It defines a simple graph that increments and decrements a numerical state. The `PostgresSaver` persists the graph's state to a PostgreSQL database, enabling the graph to be stopped and resumed from its last checkpoint, illustrating fault tolerance and state persistence across runs. Ensure your PostgreSQL database is running and its schema for `langgraph` checkpoints is initialized."},"warnings":[{"fix":"Upgrade your `langgraph` installation to version 1.0.0 or higher. For new projects, always install the latest compatible versions of both `langgraph` and `langgraph-checkpoint-postgres`.","message":"This library (`langgraph-checkpoint-postgres` v3.x) is designed exclusively for `langgraph` v1.0.0 and newer. It relies on the significantly revised `CheckpointSaver` interface introduced in `langgraph` 1.x. Using this checkpoint saver with older versions of `langgraph` (pre-1.0.0) will lead to API mismatches and runtime errors.","severity":"breaking","affected_versions":"langgraph < 1.0.0 (when used with langgraph-checkpoint-postgres 3.x)"},{"fix":"Consult the official `langgraph` documentation or the `libs/checkpoint-postgres` directory in the `langgraph` GitHub repository for the required SQL schema or Alembic migration scripts. Typically, you'd run `alembic upgrade head` after configuring Alembic to initialize the schema.","message":"The `PostgresSaver` does not automatically create the necessary database tables. You must manually initialize the PostgreSQL schema that `langgraph` expects for checkpointing. Failure to do so will result in database errors when the saver attempts to write or read state.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For production, you might prefer to install `psycopg2` (which requires local build tools like `pg_config`) or use an asynchronous driver like `asyncpg` (if your application stack is asynchronous) and manage the database connection directly.","message":"For convenience, `langgraph-checkpoint-postgres` depends on `psycopg2-binary`. While suitable for development, `psycopg2-binary` is not always recommended for production due to its pre-compiled nature which can sometimes lead to platform-specific issues or larger container images. For robust production deployments, consider alternatives.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use environment variables (e.g., `POSTGRES_CONNECTION_STRING`) or a dedicated secrets management system to store and retrieve sensitive database connection information. Access these securely using `os.environ.get()` or a secrets client.","message":"Directly hardcoding database credentials or connection strings in your application code is a significant security risk. Exposure of credentials can compromise your entire database.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}