langgraph-checkpoint-postgres 3.1.0a4__tar.gz → 3.1.2__tar.gz

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/Makefile

@@ -47,22 +47,19 @@ test_watch:
 
 # Define a variable for Python and notebook files.
 PYTHON_FILES=.
-MYPY_CACHE=.mypy_cache
 lint format: PYTHON_FILES=.
 lint_diff format_diff: PYTHON_FILES=$(shell git diff --name-only --relative --diff-filter=d main . | grep -E '\.py$$|\.ipynb$$')
 lint_package: PYTHON_FILES=langgraph
 lint_tests: PYTHON_FILES=tests
-lint_tests: MYPY_CACHE=.mypy_cache_test
 
 lint lint_diff lint_package lint_tests:
 	uv run ruff check .
 	[ "$(PYTHON_FILES)" = "" ] || uv run ruff format $(PYTHON_FILES) --diff
 	[ "$(PYTHON_FILES)" = "" ] || uv run ruff check --select I $(PYTHON_FILES)
-	[ "$(PYTHON_FILES)" = "" ] || mkdir -p $(MYPY_CACHE)
-	[ "$(PYTHON_FILES)" = "" ] || uv run mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+	[ "$(PYTHON_FILES)" = "" ] || uv run ty check $(PYTHON_FILES)
 
 type:
-	mkdir -p $(MYPY_CACHE) && uv run mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+	uv run ty check $(PYTHON_FILES)
 
 format format_diff:
 	uv run ruff format $(PYTHON_FILES)

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-checkpoint-postgres
-Version: 3.1.0a4
+Version: 3.1.2
 Summary: Library with a Postgres implementation of LangGraph checkpoint saver.
 Project-URL: Source, https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres
 Project-URL: Twitter, https://x.com/langchain_oss
@@ -9,7 +9,7 @@ Project-URL: Reddit, https://www.reddit.com/r/LangChain/
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: langgraph-checkpoint<5.0.0,>=4.1.0a4
+Requires-Dist: langgraph-checkpoint<5.0.0,>=4.1.0
 Requires-Dist: orjson>=3.11.5
 Requires-Dist: psycopg-pool>=3.2.0
 Requires-Dist: psycopg>=3.2.0
@@ -17,11 +17,29 @@ Description-Content-Type: text/markdown
 
 # LangGraph Checkpoint Postgres
 
-Implementation of LangGraph CheckpointSaver that uses Postgres.
+[![PyPI - Version](https://img.shields.io/pypi/v/langgraph-checkpoint-postgres?label=%20)](https://pypi.org/project/langgraph-checkpoint-postgres/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langgraph-checkpoint-postgres)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langgraph-checkpoint-postgres)](https://pypistats.org/packages/langgraph-checkpoint-postgres)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchain_oss.svg?style=social&label=Follow%20%40LangChain)](https://x.com/langchain_oss)
 
-## Dependencies
+To help you ship LangGraph apps to production faster, check out [LangSmith](https://www.langchain.com/langsmith).
+[LangSmith](https://www.langchain.com/langsmith) is a unified developer platform for building, testing, and monitoring LLM applications.
 
-By default `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) without any extras. However, you can choose a specific installation that best suits your needs [here](https://www.psycopg.org/psycopg3/docs/basic/install.html) (for example, `psycopg[binary]`).
+## Quick Install
+
+```bash
+uv add langgraph-checkpoint-postgres
+```
+
+## 🤔 What is this?
+
+This library provides a Postgres implementation of LangGraph's checkpoint saver. Use it when you want LangGraph state persistence backed by Postgres for durable, long-running workflows and agents.
+
+By default, `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) without any extras. You can choose a specific installation that best suits your needs in the [Psycopg installation docs](https://www.psycopg.org/psycopg3/docs/basic/install.html), for example `psycopg[binary]`.
+
+## 📖 Documentation
+
+For full documentation, see the [API reference](https://reference.langchain.com/python/langgraph.checkpoint.postgres). For conceptual guides on persistence and memory, see the [LangGraph Docs](https://docs.langchain.com/oss/python/langgraph/overview).
 
 ## Security
 
@@ -37,10 +55,12 @@ By default `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) withou
 > When manually creating Postgres connections and passing them to `PostgresSaver` or `AsyncPostgresSaver`, make sure to include `autocommit=True` and `row_factory=dict_row` (`from psycopg.rows import dict_row`). See a full example in this [how-to guide](https://langchain-ai.github.io/langgraph/how-tos/persistence_postgres/).
 >
 > **Why these parameters are required:**
+>
 > - `autocommit=True`: Required for the `.setup()` method to properly commit the checkpoint tables to the database. Without this, table creation may not be persisted.
 > - `row_factory=dict_row`: Required because the PostgresSaver implementation accesses database rows using dictionary-style syntax (e.g., `row["column_name"]`). The default `tuple_row` factory returns tuples that only support index-based access (e.g., `row[0]`), which will cause `TypeError` exceptions when the checkpointer tries to access columns by name.
 >
 > **Example of incorrect usage:**
+>
 > ```python
 > # ❌ This will fail with TypeError during checkpointer operations
 > with psycopg.connect(DB_URI) as conn:  # Missing autocommit=True and row_factory=dict_row
@@ -64,24 +84,12 @@ with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
         "v": 4,
         "ts": "2024-07-31T20:14:19.804150+00:00",
         "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
-        "channel_values": {
-            "my_key": "meow",
-            "node": "node"
-        },
-        "channel_versions": {
-            "__start__": 2,
-            "my_key": 3,
-            "start:node": 3,
-            "node": 3
-        },
+        "channel_values": {"my_key": "meow", "node": "node"},
+        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
         "versions_seen": {
             "__input__": {},
-            "__start__": {
-            "__start__": 1
-            },
-            "node": {
-            "start:node": 2
-            }
+            "__start__": {"__start__": 1},
+            "node": {"start:node": 2},
         },
     }
 
@@ -105,24 +113,12 @@ async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
         "v": 4,
         "ts": "2024-07-31T20:14:19.804150+00:00",
         "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
-        "channel_values": {
-            "my_key": "meow",
-            "node": "node"
-        },
-        "channel_versions": {
-            "__start__": 2,
-            "my_key": 3,
-            "start:node": 3,
-            "node": 3
-        },
+        "channel_values": {"my_key": "meow", "node": "node"},
+        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
         "versions_seen": {
             "__input__": {},
-            "__start__": {
-            "__start__": 1
-            },
-            "node": {
-            "start:node": 2
-            }
+            "__start__": {"__start__": 1},
+            "node": {"start:node": 2},
         },
     }
 
@@ -135,3 +131,13 @@ async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
     # list checkpoints
     [c async for c in checkpointer.alist(read_config)]
 ```
+
+## 📕 Releases & Versioning
+
+See our [Releases](https://docs.langchain.com/oss/python/release-policy) and [Versioning](https://docs.langchain.com/oss/python/versioning) policies.
+
+## 💁 Contributing
+
+As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
+
+For detailed information on how to contribute, see the [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview).

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/README.md

@@ -1,10 +1,28 @@
 # LangGraph Checkpoint Postgres
 
-Implementation of LangGraph CheckpointSaver that uses Postgres.
+[![PyPI - Version](https://img.shields.io/pypi/v/langgraph-checkpoint-postgres?label=%20)](https://pypi.org/project/langgraph-checkpoint-postgres/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langgraph-checkpoint-postgres)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langgraph-checkpoint-postgres)](https://pypistats.org/packages/langgraph-checkpoint-postgres)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchain_oss.svg?style=social&label=Follow%20%40LangChain)](https://x.com/langchain_oss)
 
-## Dependencies
+To help you ship LangGraph apps to production faster, check out [LangSmith](https://www.langchain.com/langsmith).
+[LangSmith](https://www.langchain.com/langsmith) is a unified developer platform for building, testing, and monitoring LLM applications.
 
-By default `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) without any extras. However, you can choose a specific installation that best suits your needs [here](https://www.psycopg.org/psycopg3/docs/basic/install.html) (for example, `psycopg[binary]`).
+## Quick Install
+
+```bash
+uv add langgraph-checkpoint-postgres
+```
+
+## 🤔 What is this?
+
+This library provides a Postgres implementation of LangGraph's checkpoint saver. Use it when you want LangGraph state persistence backed by Postgres for durable, long-running workflows and agents.
+
+By default, `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) without any extras. You can choose a specific installation that best suits your needs in the [Psycopg installation docs](https://www.psycopg.org/psycopg3/docs/basic/install.html), for example `psycopg[binary]`.
+
+## 📖 Documentation
+
+For full documentation, see the [API reference](https://reference.langchain.com/python/langgraph.checkpoint.postgres). For conceptual guides on persistence and memory, see the [LangGraph Docs](https://docs.langchain.com/oss/python/langgraph/overview).
 
 ## Security
 
@@ -20,10 +38,12 @@ By default `langgraph-checkpoint-postgres` installs `psycopg` (Psycopg 3) withou
 > When manually creating Postgres connections and passing them to `PostgresSaver` or `AsyncPostgresSaver`, make sure to include `autocommit=True` and `row_factory=dict_row` (`from psycopg.rows import dict_row`). See a full example in this [how-to guide](https://langchain-ai.github.io/langgraph/how-tos/persistence_postgres/).
 >
 > **Why these parameters are required:**
+>
 > - `autocommit=True`: Required for the `.setup()` method to properly commit the checkpoint tables to the database. Without this, table creation may not be persisted.
 > - `row_factory=dict_row`: Required because the PostgresSaver implementation accesses database rows using dictionary-style syntax (e.g., `row["column_name"]`). The default `tuple_row` factory returns tuples that only support index-based access (e.g., `row[0]`), which will cause `TypeError` exceptions when the checkpointer tries to access columns by name.
 >
 > **Example of incorrect usage:**
+>
 > ```python
 > # ❌ This will fail with TypeError during checkpointer operations
 > with psycopg.connect(DB_URI) as conn:  # Missing autocommit=True and row_factory=dict_row
@@ -47,24 +67,12 @@ with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
         "v": 4,
         "ts": "2024-07-31T20:14:19.804150+00:00",
         "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
-        "channel_values": {
-            "my_key": "meow",
-            "node": "node"
-        },
-        "channel_versions": {
-            "__start__": 2,
-            "my_key": 3,
-            "start:node": 3,
-            "node": 3
-        },
+        "channel_values": {"my_key": "meow", "node": "node"},
+        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
         "versions_seen": {
             "__input__": {},
-            "__start__": {
-            "__start__": 1
-            },
-            "node": {
-            "start:node": 2
-            }
+            "__start__": {"__start__": 1},
+            "node": {"start:node": 2},
         },
     }
 
@@ -88,24 +96,12 @@ async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
         "v": 4,
         "ts": "2024-07-31T20:14:19.804150+00:00",
         "id": "1ef4f797-8335-6428-8001-8a1503f9b875",
-        "channel_values": {
-            "my_key": "meow",
-            "node": "node"
-        },
-        "channel_versions": {
-            "__start__": 2,
-            "my_key": 3,
-            "start:node": 3,
-            "node": 3
-        },
+        "channel_values": {"my_key": "meow", "node": "node"},
+        "channel_versions": {"__start__": 2, "my_key": 3, "start:node": 3, "node": 3},
         "versions_seen": {
             "__input__": {},
-            "__start__": {
-            "__start__": 1
-            },
-            "node": {
-            "start:node": 2
-            }
+            "__start__": {"__start__": 1},
+            "node": {"start:node": 2},
         },
     }
 
@@ -118,3 +114,13 @@ async with AsyncPostgresSaver.from_conn_string(DB_URI) as checkpointer:
     # list checkpoints
     [c async for c in checkpointer.alist(read_config)]
 ```
+
+## 📕 Releases & Versioning
+
+See our [Releases](https://docs.langchain.com/oss/python/release-policy) and [Versioning](https://docs.langchain.com/oss/python/versioning) policies.
+
+## 💁 Contributing
+
+As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
+
+For detailed information on how to contribute, see the [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview).

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/langgraph/checkpoint/postgres/__init__.py

@@ -223,7 +223,7 @@ class PostgresSaver(BasePostgresSaver):
             >>> checkpoint_tuple = memory.get_tuple(config)
             >>> print(checkpoint_tuple)
             CheckpointTuple(...)
-        """  # noqa
+        """
         thread_id = config["configurable"]["thread_id"]
         checkpoint_id = get_checkpoint_id(config)
         checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
@@ -478,9 +478,11 @@ class PostgresSaver(BasePostgresSaver):
         stage1_sql = _build_delta_stage1_sql(channels, paged=True)
         parent_of: dict[str, str | None] = {}
         ver_by_i_by_cid: list[dict[str, str | None]] = [{} for _ in channels]
-        hs_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        hb_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        inline_by_i_by_cid: list[dict[str, Any]] = [{} for _ in channels]
         chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
         seed_ver_by_ch: dict[str, str | None] = {ch: None for ch in channels}
+        seed_inline_by_ch: dict[str, Any] = {}
         walk_cursor_by_ch: dict[str, str | None] = {}
         seeded: set[str] = set()
         cursor: str | None = None
@@ -489,7 +491,8 @@ class PostgresSaver(BasePostgresSaver):
             while True:
                 stage1_params: list[Any] = []
                 for ch in channels:
-                    stage1_params.extend([ch, ch])
+                    # ver_i, blob channel, blob version, inline_i
+                    stage1_params.extend([ch, ch, ch, ch])
                 stage1_params.extend(
                     [thread_id, checkpoint_ns, cursor, cursor, _DELTA_PAGE_SIZE]
                 )
@@ -502,16 +505,19 @@ class PostgresSaver(BasePostgresSaver):
                     channels,
                     parent_of,
                     ver_by_i_by_cid,
-                    hs_by_i_by_cid,
+                    hb_by_i_by_cid,
+                    inline_by_i_by_cid,
                 )
                 self._try_advance_walks(
                     checkpoint_id,
                     channels,
                     parent_of,
                     ver_by_i_by_cid,
-                    hs_by_i_by_cid,
+                    hb_by_i_by_cid,
+                    inline_by_i_by_cid,
                     chain_by_ch,
                     seed_ver_by_ch,
+                    seed_inline_by_ch,
                     walk_cursor_by_ch,
                     seeded,
                 )
@@ -546,6 +552,7 @@ class PostgresSaver(BasePostgresSaver):
             channels=channels,
             chain_by_ch=chain_by_ch,
             seed_ver_by_ch=seed_ver_by_ch,
+            seed_inline_by_ch=seed_inline_by_ch,
             stage2_rows=cast("list[_DeltaStage2Row]", stage2_rows),
         )
 

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/langgraph/checkpoint/postgres/aio.py

@@ -426,9 +426,11 @@ class AsyncPostgresSaver(BasePostgresSaver):
         stage1_sql = _build_delta_stage1_sql(channels, paged=True)
         parent_of: dict[str, str | None] = {}
         ver_by_i_by_cid: list[dict[str, str | None]] = [{} for _ in channels]
-        hs_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        hb_by_i_by_cid: list[dict[str, bool]] = [{} for _ in channels]
+        inline_by_i_by_cid: list[dict[str, Any]] = [{} for _ in channels]
         chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
         seed_ver_by_ch: dict[str, str | None] = {ch: None for ch in channels}
+        seed_inline_by_ch: dict[str, Any] = {}
         walk_cursor_by_ch: dict[str, str | None] = {}
         seeded: set[str] = set()
         cursor: str | None = None
@@ -437,7 +439,8 @@ class AsyncPostgresSaver(BasePostgresSaver):
             while True:
                 stage1_params: list[Any] = []
                 for ch in channels:
-                    stage1_params.extend([ch, ch])
+                    # ver_i, blob channel, blob version, inline_i
+                    stage1_params.extend([ch, ch, ch, ch])
                 stage1_params.extend(
                     [thread_id, checkpoint_ns, cursor, cursor, _DELTA_PAGE_SIZE]
                 )
@@ -450,16 +453,19 @@ class AsyncPostgresSaver(BasePostgresSaver):
                     channels,
                     parent_of,
                     ver_by_i_by_cid,
-                    hs_by_i_by_cid,
+                    hb_by_i_by_cid,
+                    inline_by_i_by_cid,
                 )
                 self._try_advance_walks(
                     checkpoint_id,
                     channels,
                     parent_of,
                     ver_by_i_by_cid,
-                    hs_by_i_by_cid,
+                    hb_by_i_by_cid,
+                    inline_by_i_by_cid,
                     chain_by_ch,
                     seed_ver_by_ch,
+                    seed_inline_by_ch,
                     walk_cursor_by_ch,
                     seeded,
                 )
@@ -490,6 +496,7 @@ class AsyncPostgresSaver(BasePostgresSaver):
             channels=channels,
             chain_by_ch=chain_by_ch,
             seed_ver_by_ch=seed_ver_by_ch,
+            seed_inline_by_ch=seed_inline_by_ch,
             stage2_rows=cast("list[_DeltaStage2Row]", stage2_rows),
         )
 
@@ -573,7 +580,7 @@ class AsyncPostgresSaver(BasePostgresSaver):
         while True:
             try:
                 yield asyncio.run_coroutine_threadsafe(
-                    anext(aiter_),  # type: ignore[arg-type]  # noqa: F821
+                    anext(aiter_),  # type: ignore[arg-type]
                     self.loop,
                 ).result()
             except StopAsyncIteration:

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/langgraph/checkpoint/postgres/base.py

@@ -199,27 +199,68 @@ class _DeltaStage2Row(TypedDict, total=False):
 
 
 def _build_delta_stage1_sql(channels: Sequence[str], *, paged: bool) -> str:
-    """Build stage 1 SQL with 2K parallel JSONB key lookups.
+    """Build stage 1 SQL with K parallel version lookups + seed probes.
 
     For channels=["messages", "files"] (with `paged=True`) the result is::
 
         SELECT checkpoint_id, parent_checkpoint_id,
                checkpoint -> 'channel_versions' ->> %s AS ver_0,
-               (checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_0,
+               EXISTS (SELECT 1 FROM checkpoint_blobs b0
+                       WHERE b0.thread_id = checkpoints.thread_id
+                         AND b0.checkpoint_ns = checkpoints.checkpoint_ns
+                         AND b0.channel = %s
+                         AND b0.version = checkpoint -> 'channel_versions' ->> %s
+                         AND b0.type <> 'empty') AS hb_0,
+               checkpoint -> 'channel_values' -> %s AS inline_0,
                checkpoint -> 'channel_versions' ->> %s AS ver_1,
-               (checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_1
+               EXISTS (...) AS hb_1,
+               checkpoint -> 'channel_values' -> %s AS inline_1
         FROM checkpoints
         WHERE thread_id = %s AND checkpoint_ns = %s
           AND (%s::text IS NULL OR checkpoint_id < %s)
         ORDER BY checkpoint_id DESC
         LIMIT %s
 
+    A stored value for a channel lives in one of two places, because `put`
+    splits them:
+
+    * **blob** — non-primitive values (and `_DeltaSnapshot`) are moved to
+      `checkpoint_blobs`. `hb_i` ("has blob") probes for one. The probe hits
+      that table's primary key `(thread_id, checkpoint_ns, channel, version)`
+      exactly, so it is an index lookup per row per channel.
+    * **inline** — `None`, `str`, `int`, `float` and `bool` stay in the
+      checkpoint's own `channel_values` and get no blob row at all. `inline_i`
+      returns that value.
+
+    Testing only for a key in `channel_values` (the previous approach) missed
+    blob-stored plain values, since `put` leaves an inline marker there for
+    `_DeltaSnapshot` but not for a plain value — which is what a thread
+    migrated from a pre-delta channel type leaves behind. Probing only the
+    blobs table would conversely miss inline primitives. Both are needed, and
+    the caller treats "either present" as the seed.
+
+    `hb_i` also disambiguates the two: for a `_DeltaSnapshot`, `inline_i` is the
+    literal `true` marker rather than the value, so a blob must win over an
+    inline reading whenever one exists. That ordering is what makes a genuine
+    inline `true` (a bool channel) distinguishable from the marker.
+
+    The `type <> 'empty'` predicate mirrors the check stage 2 already applies
+    when resolving the seed blob. `put` does not currently produce `empty` rows
+    on this path — `blob_versions` is filtered to keys present in
+    `channel_values`, so `_dump_blobs`' empty branch is unreachable from it —
+    but without the predicate the two stages could disagree: stage 1 would
+    terminate the walk on a row stage 2 then discards, yielding no seed *and* a
+    truncated write chain, which is the failure this function exists to avoid.
+
     Channel names are passed as `%s` parameters (safe from SQL injection).
-    Only the column aliases `ver_i` / `hs_i` are interpolated into the
-    SQL string (i is bounded by len(channels) and uses safe identifiers).
+    Only the column aliases `ver_i` / `hb_i` / `inline_i` and the subquery alias
+    `b{i}` are interpolated into the SQL string (i is bounded by len(channels)
+    and uses safe identifiers).
 
-    Caller must extend params with `[ch_0, ch_0, ch_1, ch_1, ...,
-    thread_id, ns, cursor, cursor, page_size]` when `paged=True`.
+    Caller must extend params with `[ch_0 x4, ch_1 x4, ..., thread_id, ns,
+    cursor, cursor, page_size]` when `paged=True` — four per channel: the
+    version lookup, the blob's channel, the version the blob must match, and the
+    inline lookup.
 
     When `paged=False`, the WHERE has no cursor predicate and there's no
     LIMIT/ORDER BY — kept as a non-public helper for tests/diagnostics.
@@ -228,7 +269,13 @@ def _build_delta_stage1_sql(channels: Sequence[str], *, paged: bool) -> str:
     for i in range(len(channels)):
         cols.append(
             f"checkpoint -> 'channel_versions' ->> %s AS ver_{i}, "
-            f"(checkpoint -> 'channel_values' -> %s) IS NOT NULL AS hs_{i}"
+            f"EXISTS (SELECT 1 FROM checkpoint_blobs b{i} "
+            f"WHERE b{i}.thread_id = checkpoints.thread_id "
+            f"AND b{i}.checkpoint_ns = checkpoints.checkpoint_ns "
+            f"AND b{i}.channel = %s "
+            f"AND b{i}.version = checkpoint -> 'channel_versions' ->> %s "
+            f"AND b{i}.type <> 'empty') AS hb_{i}, "
+            f"checkpoint -> 'channel_values' -> %s AS inline_{i}"
         )
     sql = (
         "SELECT checkpoint_id, parent_checkpoint_id, "
@@ -279,8 +326,8 @@ def _build_delta_stage2_sql(
         )
     for _ in channels_with_seed:
         branches.append(
-            "SELECT 'b'::text, NULL, channel, "
-            "type, blob, NULL, NULL, version "
+            "SELECT 'b'::text AS _kind, NULL::text AS checkpoint_id, channel, "
+            "type, blob, NULL::text AS task_id, NULL::int AS idx, version "
             "FROM checkpoint_blobs "
             "WHERE thread_id = %s AND checkpoint_ns = %s AND channel = %s "
             "AND version = %s"
@@ -342,7 +389,8 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
         channels: Sequence[str],
         parent_of: dict[str, str | None],
         ver_by_i_by_cid: list[dict[str, str | None]],
-        hs_by_i_by_cid: list[dict[str, bool]],
+        hb_by_i_by_cid: list[dict[str, bool]],
+        inline_by_i_by_cid: list[dict[str, Any]],
     ) -> str | None:
         """Fold one stage-1 page into the running walk-state mappings.
 
@@ -356,7 +404,8 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
             parent_of[cid] = cast("str | None", r["parent_checkpoint_id"])
             for i in range(len(channels)):
                 ver_by_i_by_cid[i][cid] = cast("str | None", r.get(f"ver_{i}"))
-                hs_by_i_by_cid[i][cid] = bool(r.get(f"hs_{i}"))
+                hb_by_i_by_cid[i][cid] = bool(r.get(f"hb_{i}"))
+                inline_by_i_by_cid[i][cid] = r.get(f"inline_{i}")
             # Rows are DESC; the last one is the smallest cid in the page.
             oldest = cid
         return oldest
@@ -367,9 +416,11 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
         channels: Sequence[str],
         parent_of: Mapping[str, str | None],
         ver_by_i_by_cid: Sequence[Mapping[str, str | None]],
-        hs_by_i_by_cid: Sequence[Mapping[str, bool]],
+        hb_by_i_by_cid: Sequence[Mapping[str, bool]],
+        inline_by_i_by_cid: Sequence[Mapping[str, Any]],
         chain_by_ch: dict[str, list[str]],
         seed_ver_by_ch: dict[str, str | None],
+        seed_inline_by_ch: dict[str, Any],
         walk_cursor_by_ch: dict[str, str | None],
         seeded: set[str],
     ) -> None:
@@ -377,14 +428,15 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
 
         Uses the partial `parent_of` map accumulated so far. A walk stops
         either because:
-          (a) it found a snapshot for its channel (channel becomes seeded),
+          (a) it found a stored value for its channel — a blob or an inline
+              primitive (channel becomes seeded),
           (b) it reached a real root (parent_of[cid] is None — fully
               materialized at this point), or
           (c) the next ancestor cid isn't in `parent_of` yet (waiting for
               a later page; the cursor stays put).
 
-        Mutates `chain_by_ch`, `seed_ver_by_ch`, `walk_cursor_by_ch`, and
-        `seeded` in place.
+        Mutates `chain_by_ch`, `seed_ver_by_ch`, `seed_inline_by_ch`,
+        `walk_cursor_by_ch`, and `seeded` in place.
         """
         for i, ch in enumerate(channels):
             if ch in seeded:
@@ -394,15 +446,22 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
                 walk_cursor_by_ch[ch] = parent_of.get(target_id)
             cur_cid = walk_cursor_by_ch[ch]
             ch_chain = chain_by_ch[ch]
-            hs_i = hs_by_i_by_cid[i]
+            hb_i = hb_by_i_by_cid[i]
+            inline_i = inline_by_i_by_cid[i]
             ver_i = ver_by_i_by_cid[i]
             while cur_cid is not None:
                 if cur_cid not in parent_of:
                     # Need more pages to continue this walk.
                     break
                 ch_chain.append(cur_cid)
-                if hs_i.get(cur_cid, False):
+                has_blob = hb_i.get(cur_cid, False)
+                inline = inline_i.get(cur_cid)
+                if has_blob or inline is not None:
+                    # A blob wins: for a `_DeltaSnapshot` the inline reading is
+                    # the `true` marker, not the value.
                     seed_ver_by_ch[ch] = ver_i.get(cur_cid)
+                    if not has_blob:
+                        seed_inline_by_ch[ch] = inline
                     seeded.add(ch)
                     cur_cid = None
                     break
@@ -415,16 +474,23 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
         channels: Sequence[str],
         chain_by_ch: Mapping[str, list[str]],
         seed_ver_by_ch: Mapping[str, str | None],
+        seed_inline_by_ch: Mapping[str, Any],
         stage2_rows: Sequence[_DeltaStage2Row],
     ) -> dict[str, DeltaChannelHistory]:
         """Demux stage 2 rows per channel; produce per-channel histories.
 
         stage2_rows carry `channel` on every row. We build per-channel
         `writes_by_cid` and per-channel `seed_blob` dicts, then assemble
-        a `DeltaChannelHistory` per requested channel. The `seed` key is omitted
-        when the walk reached root with no snapshot found, or when the
-        seed blob is sentinel "empty" — in both cases the consumer treats
-        absence as "start empty".
+        a `DeltaChannelHistory` per requested channel.
+
+        A seed comes from the blobs table when the walk found one there, and
+        otherwise from `seed_inline_by_ch` — `put` keeps `None`, `str`, `int`,
+        `float` and `bool` values in the checkpoint's own `channel_values` with
+        no blob row, so those never appear in `stage2_rows`.
+
+        The `seed` key is omitted when the walk reached root without finding a
+        stored value, or when the seed blob is sentinel "empty" — in both cases
+        the consumer treats absence as "start empty".
         """
         # writes_by_ch_by_cid[channel][cid] = list of (type, blob, task_id, idx)
         writes_by_ch_by_cid: dict[str, dict[str, list[tuple[str, bytes, str, int]]]] = {
@@ -473,6 +539,10 @@ class BasePostgresSaver(BaseCheckpointSaver[str]):
                 blob = seed_blob_by_ver.get((ch, seed_version))
                 if blob is not None and blob[0] != "empty":
                     entry["seed"] = self.serde.loads_typed(blob)
+                elif ch in seed_inline_by_ch:
+                    # Inline primitive: stored in the checkpoint, not the blobs
+                    # table, so stage 2 never returned a row for it.
+                    entry["seed"] = seed_inline_by_ch[ch]
             result[ch] = entry
         return result
 

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.2}/langgraph/checkpoint/postgres/shallow.py

@@ -334,7 +334,7 @@ class ShallowPostgresSaver(BasePostgresSaver):
             >>> checkpoint_tuple = memory.get_tuple(config)
             >>> print(checkpoint_tuple)
             CheckpointTuple(...)
-        """  # noqa
+        """
         thread_id = config["configurable"]["thread_id"]
         checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
         args = (thread_id, checkpoint_ns)
@@ -885,7 +885,7 @@ class AsyncShallowPostgresSaver(BasePostgresSaver):
         while True:
             try:
                 yield asyncio.run_coroutine_threadsafe(
-                    anext(aiter_),  # type: ignore[arg-type]  # noqa: F821
+                    anext(aiter_),  # type: ignore[arg-type]
                     self.loop,
                 ).result()
             except StopAsyncIteration: