chore: import upstream snapshot with attribution

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

@@ -0,0 +1,645 @@
+from __future__ import annotations
+
+import json
+import random
+import sqlite3
+import threading
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
+from contextlib import closing, contextmanager
+from typing import Any, cast
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    WRITES_IDX_MAP,
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    DeltaChannelHistory,
+    SerializerProtocol,
+    get_checkpoint_id,
+    get_checkpoint_metadata,
+)
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+from langgraph.checkpoint.sqlite._delta import (
+    DELTA_STAGE1_SQL,
+    build_delta_channels_writes_history,
+    build_delta_stage2_sql,
+    step_walk_with_row,
+)
+from langgraph.checkpoint.sqlite.utils import search_where
+
+_AIO_ERROR_MSG = (
+    "The SqliteSaver does not support async methods. "
+    "Consider using AsyncSqliteSaver instead.\n"
+    "from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver\n"
+    "Note: AsyncSqliteSaver requires the aiosqlite package to use.\n"
+    "Install with:\n`pip install aiosqlite`\n"
+    "See https://langchain-ai.github.io/langgraph/reference/checkpoints/#langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver"
+    "for more information."
+)
+
+
+class SqliteSaver(BaseCheckpointSaver[str]):
+    """A checkpoint saver that stores checkpoints in a SQLite database.
+
+    Note:
+        This class is meant for lightweight, synchronous use cases
+        (demos and small projects) and does not
+        scale to multiple threads.
+        For a similar sqlite saver with `async` support,
+        consider using [AsyncSqliteSaver][langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver].
+
+    Args:
+        conn (sqlite3.Connection): The SQLite database connection.
+        serde (Optional[SerializerProtocol]): The serializer to use for serializing and deserializing checkpoints. Defaults to JsonPlusSerializerCompat.
+
+    Examples:
+
+        >>> import sqlite3
+        >>> from langgraph.checkpoint.sqlite import SqliteSaver
+        >>> from langgraph.graph import StateGraph
+        >>>
+        >>> builder = StateGraph(int)
+        >>> builder.add_node("add_one", lambda x: x + 1)
+        >>> builder.set_entry_point("add_one")
+        >>> builder.set_finish_point("add_one")
+        >>> # Create a new SqliteSaver instance
+        >>> # Note: check_same_thread=False is OK as the implementation uses a lock
+        >>> # to ensure thread safety.
+        >>> conn = sqlite3.connect("checkpoints.sqlite", check_same_thread=False)
+        >>> memory = SqliteSaver(conn)
+        >>> graph = builder.compile(checkpointer=memory)
+        >>> config = {"configurable": {"thread_id": "1"}}
+        >>> graph.get_state(config)
+        >>> result = graph.invoke(3, config)
+        >>> graph.get_state(config)
+        StateSnapshot(values=4, next=(), config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '0c62ca34-ac19-445d-bbb0-5b4984975b2a'}}, parent_config=None)
+    """  # noqa
+
+    conn: sqlite3.Connection
+    is_setup: bool
+
+    def __init__(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        serde: SerializerProtocol | None = None,
+    ) -> None:
+        super().__init__(serde=serde)
+        self.jsonplus_serde = JsonPlusSerializer()
+        self.conn = conn
+        self.is_setup = False
+        self.lock = threading.Lock()
+
+    @classmethod
+    @contextmanager
+    def from_conn_string(cls, conn_string: str) -> Iterator[SqliteSaver]:
+        """Create a new SqliteSaver instance from a connection string.
+
+        Args:
+            conn_string: The SQLite connection string.
+
+        Yields:
+            SqliteSaver: A new SqliteSaver instance.
+
+        Examples:
+
+            In memory:
+
+                with SqliteSaver.from_conn_string(":memory:") as memory:
+                    ...
+
+            To disk:
+
+                with SqliteSaver.from_conn_string("checkpoints.sqlite") as memory:
+                    ...
+        """
+        with closing(
+            sqlite3.connect(
+                conn_string,
+                # https://ricardoanderegg.com/posts/python-sqlite-thread-safety/
+                check_same_thread=False,
+            )
+        ) as conn:
+            yield cls(conn)
+
+    def setup(self) -> None:
+        """Set up the checkpoint database.
+
+        This method creates the necessary tables in the SQLite database if they don't
+        already exist. It is called automatically when needed and should not be called
+        directly by the user.
+        """
+        if self.is_setup:
+            return
+
+        self.conn.executescript(
+            """
+            PRAGMA journal_mode=WAL;
+            CREATE TABLE IF NOT EXISTS checkpoints (
+                thread_id TEXT NOT NULL,
+                checkpoint_ns TEXT NOT NULL DEFAULT '',
+                checkpoint_id TEXT NOT NULL,
+                parent_checkpoint_id TEXT,
+                type TEXT,
+                checkpoint BLOB,
+                metadata BLOB,
+                PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+            );
+            CREATE TABLE IF NOT EXISTS writes (
+                thread_id TEXT NOT NULL,
+                checkpoint_ns TEXT NOT NULL DEFAULT '',
+                checkpoint_id TEXT NOT NULL,
+                task_id TEXT NOT NULL,
+                idx INTEGER NOT NULL,
+                channel TEXT NOT NULL,
+                type TEXT,
+                value BLOB,
+                PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+            );
+            """
+        )
+
+        self.is_setup = True
+
+    @contextmanager
+    def cursor(self, transaction: bool = True) -> Iterator[sqlite3.Cursor]:
+        """Get a cursor for the SQLite database.
+
+        This method returns a cursor for the SQLite database. It is used internally
+        by the SqliteSaver and should not be called directly by the user.
+
+        Args:
+            transaction (bool): Whether to commit the transaction when the cursor is closed. Defaults to True.
+
+        Yields:
+            sqlite3.Cursor: A cursor for the SQLite database.
+        """
+        with self.lock:
+            self.setup()
+            cur = self.conn.cursor()
+            try:
+                yield cur
+            finally:
+                if transaction:
+                    self.conn.commit()
+                cur.close()
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple from the database.
+
+        This method retrieves a checkpoint tuple from the SQLite database based on the
+        provided config. If the config contains a `checkpoint_id` key, the checkpoint with
+        the matching thread ID and checkpoint ID is retrieved. Otherwise, the latest checkpoint
+        for the given thread ID is retrieved.
+
+        Args:
+            config: The config to use for retrieving the checkpoint.
+
+        Returns:
+            The retrieved checkpoint tuple, or None if no matching checkpoint was found.
+
+        Examples:
+
+            Basic:
+            >>> config = {"configurable": {"thread_id": "1"}}
+            >>> checkpoint_tuple = memory.get_tuple(config)
+            >>> print(checkpoint_tuple)
+            CheckpointTuple(...)
+
+            With checkpoint ID:
+
+            >>> config = {
+            ...    "configurable": {
+            ...        "thread_id": "1",
+            ...        "checkpoint_ns": "",
+            ...        "checkpoint_id": "1ef4f797-8335-6428-8001-8a1503f9b875",
+            ...    }
+            ... }
+            >>> checkpoint_tuple = memory.get_tuple(config)
+            >>> print(checkpoint_tuple)
+            CheckpointTuple(...)
+        """  # noqa
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        with self.cursor(transaction=False) as cur:
+            # find the latest checkpoint for the thread_id
+            if checkpoint_id := get_checkpoint_id(config):
+                cur.execute(
+                    "SELECT thread_id, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?",
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        checkpoint_ns,
+                        checkpoint_id,
+                    ),
+                )
+            else:
+                cur.execute(
+                    "SELECT thread_id, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = ? ORDER BY checkpoint_id DESC LIMIT 1",
+                    (str(config["configurable"]["thread_id"]), checkpoint_ns),
+                )
+            # if a checkpoint is found, return it
+            if value := cur.fetchone():
+                (
+                    thread_id,
+                    checkpoint_id,
+                    parent_checkpoint_id,
+                    type,
+                    checkpoint,
+                    metadata,
+                ) = value
+                if not get_checkpoint_id(config):
+                    config = {
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    }
+                # find any pending writes
+                cur.execute(
+                    "SELECT task_id, channel, type, value FROM writes WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ? ORDER BY task_id, idx",
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        checkpoint_ns,
+                        str(config["configurable"]["checkpoint_id"]),
+                    ),
+                )
+                # deserialize the checkpoint and metadata
+                return CheckpointTuple(
+                    config,
+                    self.serde.loads_typed((type, checkpoint)),
+                    cast(
+                        CheckpointMetadata,
+                        json.loads(metadata) if metadata is not None else {},
+                    ),
+                    (
+                        {
+                            "configurable": {
+                                "thread_id": thread_id,
+                                "checkpoint_ns": checkpoint_ns,
+                                "checkpoint_id": parent_checkpoint_id,
+                            }
+                        }
+                        if parent_checkpoint_id
+                        else None
+                    ),
+                    [
+                        (task_id, channel, self.serde.loads_typed((type, value)))
+                        for task_id, channel, type, value in cur
+                    ],
+                )
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints from the database.
+
+        This method retrieves a list of checkpoint tuples from the SQLite database based
+        on the provided config. The checkpoints are ordered by checkpoint ID in descending order (newest first).
+
+        Args:
+            config: The config to use for listing the checkpoints.
+            filter: Additional filtering criteria for metadata.
+            before: If provided, only checkpoints before the specified checkpoint ID are returned.
+            limit: The maximum number of checkpoints to return.
+
+        Yields:
+            An iterator of checkpoint tuples.
+
+        Examples:
+            >>> from langgraph.checkpoint.sqlite import SqliteSaver
+            >>> with SqliteSaver.from_conn_string(":memory:") as memory:
+            ... # Run a graph, then list the checkpoints
+            >>>     config = {"configurable": {"thread_id": "1"}}
+            >>>     checkpoints = list(memory.list(config, limit=2))
+            >>> print(checkpoints)
+            [CheckpointTuple(...), CheckpointTuple(...)]
+
+            >>> config = {"configurable": {"thread_id": "1"}}
+            >>> before = {"configurable": {"checkpoint_id": "1ef4f797-8335-6428-8001-8a1503f9b875"}}
+            >>> with SqliteSaver.from_conn_string(":memory:") as memory:
+            ... # Run a graph, then list the checkpoints
+            >>>     checkpoints = list(memory.list(config, before=before))
+            >>> print(checkpoints)
+            [CheckpointTuple(...), ...]
+        """
+        where, param_values = search_where(config, filter, before)
+        query = f"""SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+        FROM checkpoints
+        {where}
+        ORDER BY checkpoint_id DESC"""
+        if limit is not None:
+            query += " LIMIT ?"
+            param_values = (*param_values, limit)
+        with self.cursor(transaction=False) as cur, closing(self.conn.cursor()) as wcur:
+            cur.execute(query, param_values)
+            for (
+                thread_id,
+                checkpoint_ns,
+                checkpoint_id,
+                parent_checkpoint_id,
+                type,
+                checkpoint,
+                metadata,
+            ) in cur:
+                wcur.execute(
+                    "SELECT task_id, channel, type, value FROM writes WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ? ORDER BY task_id, idx",
+                    (thread_id, checkpoint_ns, checkpoint_id),
+                )
+                yield CheckpointTuple(
+                    {
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    },
+                    self.serde.loads_typed((type, checkpoint)),
+                    cast(
+                        CheckpointMetadata,
+                        json.loads(metadata) if metadata is not None else {},
+                    ),
+                    (
+                        {
+                            "configurable": {
+                                "thread_id": thread_id,
+                                "checkpoint_ns": checkpoint_ns,
+                                "checkpoint_id": parent_checkpoint_id,
+                            }
+                        }
+                        if parent_checkpoint_id
+                        else None
+                    ),
+                    [
+                        (task_id, channel, self.serde.loads_typed((type, value)))
+                        for task_id, channel, type, value in wcur
+                    ],
+                )
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the database.
+
+        This method saves a checkpoint to the SQLite database. The checkpoint is associated
+        with the provided config and its parent config (if any).
+
+        Args:
+            config: The config to associate with the checkpoint.
+            checkpoint: The checkpoint to save.
+            metadata: Additional metadata to save with the checkpoint.
+            new_versions: New channel versions as of this write.
+
+        Returns:
+            RunnableConfig: Updated configuration after storing the checkpoint.
+
+        Examples:
+
+            >>> from langgraph.checkpoint.sqlite import SqliteSaver
+            >>> with SqliteSaver.from_conn_string(":memory:") as memory:
+            >>>     config = {"configurable": {"thread_id": "1", "checkpoint_ns": ""}}
+            >>>     checkpoint = {"ts": "2024-05-04T06:32:42.235444+00:00", "id": "1ef4f797-8335-6428-8001-8a1503f9b875", "channel_values": {"key": "value"}}
+            >>>     saved_config = memory.put(config, checkpoint, {"source": "input", "step": 1, "writes": {"key": "value"}}, {})
+            >>> print(saved_config)
+            {'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef4f797-8335-6428-8001-8a1503f9b875'}}
+        """
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"]["checkpoint_ns"]
+        type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
+        serialized_metadata = json.dumps(
+            get_checkpoint_metadata(config, metadata), ensure_ascii=False
+        ).encode("utf-8", "ignore")
+        with self.cursor() as cur:
+            cur.execute(
+                "INSERT OR REPLACE INTO checkpoints (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    str(config["configurable"]["thread_id"]),
+                    checkpoint_ns,
+                    checkpoint["id"],
+                    config["configurable"].get("checkpoint_id"),
+                    type_,
+                    serialized_checkpoint,
+                    serialized_metadata,
+                ),
+            )
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint["id"],
+            }
+        }
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Store intermediate writes linked to a checkpoint.
+
+        This method saves intermediate writes associated with a checkpoint to the SQLite database.
+
+        Args:
+            config: Configuration of the related checkpoint.
+            writes: List of writes to store, each as (channel, value) pair.
+            task_id: Identifier for the task creating the writes.
+            task_path: Path of the task creating the writes.
+        """
+        query = (
+            "INSERT OR REPLACE INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+            if all(w[0] in WRITES_IDX_MAP for w in writes)
+            else "INSERT OR IGNORE INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+        )
+        with self.cursor() as cur:
+            cur.executemany(
+                query,
+                [
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        str(config["configurable"]["checkpoint_ns"]),
+                        str(config["configurable"]["checkpoint_id"]),
+                        task_id,
+                        WRITES_IDX_MAP.get(channel, idx),
+                        channel,
+                        *self.serde.dumps_typed(value),
+                    )
+                    for idx, (channel, value) in enumerate(writes)
+                ],
+            )
+
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete all checkpoints and writes associated with a thread ID.
+
+        Args:
+            thread_id: The thread ID to delete.
+
+        Returns:
+            None
+        """
+        with self.cursor() as cur:
+            cur.execute(
+                "DELETE FROM checkpoints WHERE thread_id = ?",
+                (str(thread_id),),
+            )
+            cur.execute(
+                "DELETE FROM writes WHERE thread_id = ?",
+                (str(thread_id),),
+            )
+
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.get_delta_channel_history`.
+
+        Two-stage query:
+
+        * Stage 1 (paged): newest-first slice of `checkpoints` returning
+          `(checkpoint_id, parent_checkpoint_id, type, checkpoint)` per
+          ancestor. Sqlite has no JSONB, so we ship the full serialized
+          checkpoint blob and inspect `channel_values` in Python. Pages
+          newest-first by `checkpoint_id` with a `< cursor` predicate;
+          page size is `DELTA_PAGE_SIZE`. Stops paging when every channel
+          has found its seed or the chain is exhausted.
+
+        * Stage 2 (per-channel UNION ALL): one branch per channel reading
+          `writes` filtered to that channel's specific `chain_cids`. No
+          separate seed-blob fetch — sqlite stores `channel_values` inline
+          in the checkpoint blob, so seeds come back from stage 1.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = self.get_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_val_by_ch: dict[str, Any] = {}
+        walk_state: dict[str, Any] = {}
+        seeded: set[str] = set()
+
+        with self.cursor(transaction=False) as cur:
+            cur.execute(DELTA_STAGE1_SQL, (thread_id, checkpoint_ns, checkpoint_id))
+            for row in cur:
+                cid, parent_cid, type_tag, blob = row
+                if step_walk_with_row(
+                    cid=cid,
+                    parent_cid=parent_cid,
+                    type_tag=type_tag,
+                    blob=blob,
+                    target_id=checkpoint_id,
+                    serde=self.serde,
+                    chain_by_ch=chain_by_ch,
+                    seed_val_by_ch=seed_val_by_ch,
+                    walk_state=walk_state,
+                    seeded=seeded,
+                    channels=channels,
+                ):
+                    break
+
+            channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+            stage2_sql = build_delta_stage2_sql(
+                chain_lens=[len(chain_by_ch[ch]) for ch in channels_with_chain],
+            )
+            if stage2_sql:
+                stage2_params: list[Any] = []
+                for ch in channels_with_chain:
+                    stage2_params.extend(
+                        [thread_id, checkpoint_ns, ch, *chain_by_ch[ch]]
+                    )
+                cur.execute(stage2_sql, stage2_params)
+                stage2_rows = cast(
+                    "list[tuple[str, str, str, int, str, bytes]]", cur.fetchall()
+                )
+            else:
+                stage2_rows = []
+
+        return build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_val_by_ch=seed_val_by_ch,
+            seeded=seeded,
+            stage2_rows=stage2_rows,
+            serde=self.serde,
+        )
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple from the database asynchronously.
+
+        Note:
+            This async method is not supported by the SqliteSaver class.
+            Use get_tuple() instead, or consider using [AsyncSqliteSaver][langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver].
+        """
+        raise NotImplementedError(_AIO_ERROR_MSG)
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """List checkpoints from the database asynchronously.
+
+        Note:
+            This async method is not supported by the SqliteSaver class.
+            Use list() instead, or consider using [AsyncSqliteSaver][langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver].
+        """
+        raise NotImplementedError(_AIO_ERROR_MSG)
+        yield
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the database asynchronously.
+
+        Note:
+            This async method is not supported by the SqliteSaver class.
+            Use put() instead, or consider using [AsyncSqliteSaver][langgraph.checkpoint.sqlite.aio.AsyncSqliteSaver].
+        """
+        raise NotImplementedError(_AIO_ERROR_MSG)
+
+    def get_next_version(self, current: str | None, channel: None) -> str:
+        """Generate the next version ID for a channel.
+
+        This method creates a new version identifier for a channel based on its current version.
+
+        Args:
+            current (Optional[str]): The current version identifier of the channel.
+
+        Returns:
+            str: The next version identifier, which is guaranteed to be monotonically increasing.
+        """
+        if current is None:
+            current_v = 0
+        elif isinstance(current, int):
+            current_v = current
+        else:
+            current_v = int(current.split(".")[0])
+        next_v = current_v + 1
+        next_h = random.random()
+        return f"{next_v:032}.{next_h:016}"

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/_delta.py

@@ -0,0 +1,172 @@
+"""Shared helpers for `get_delta_channel_history` on sqlite savers.
+
+Mirrors the two-stage shape of `BasePostgresSaver` (ancestor walk +
+per-channel UNION ALL writes fetch), but adapted for sqlite's
+constraints. The structural differences:
+
+* No JSONB — to inspect `channel_values` for a checkpoint we must
+  deserialize the full blob. Stage 1 streams the cursor row-by-row and
+  deserializes only the rows the merged walk visits, freeing each blob
+  before advancing.
+* No separate blob table — `channel_values` lives inline in the
+  checkpoint, so seeds come back from stage 1 with no second fetch.
+* Single merged walk (not K independent walks): each visited cid is
+  deserialized exactly once, regardless of how many channels are still
+  seeking their seed.
+
+The streaming design keeps peak in-flight memory at roughly one
+deserialized checkpoint at a time, instead of holding the entire
+ancestor chain's worth of raw blobs as a `fetchall()`-materialized list.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from langgraph.checkpoint.base import DeltaChannelHistory, PendingWrite
+
+# Stage 1 streams ancestors of `target_cid` newest-first. The `<=`
+# predicate keeps target itself in the stream so we can read its
+# `parent_checkpoint_id` from the first row without a separate lookup;
+# the caller skips target's own writes/seed (matches the
+# `BaseCheckpointSaver` contract).
+DELTA_STAGE1_SQL = (
+    "SELECT checkpoint_id, parent_checkpoint_id, type, checkpoint "
+    "FROM checkpoints "
+    "WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id <= ? "
+    "ORDER BY checkpoint_id DESC"
+)
+
+
+def build_delta_stage2_sql(*, chain_lens: Sequence[int]) -> str:
+    """Stage-2 per-channel UNION ALL fetching writes from `writes`.
+
+    One branch per channel with a non-empty chain. Each branch inlines its
+    own `IN (?, ?, ...)` placeholder list because sqlite has no array-bind
+    equivalent of postgres's `= ANY(%s)`. Caller passes parameters in
+    matching order: `[thread_id, checkpoint_ns, channel, *chain_cids]` per
+    branch.
+
+    Returns an empty string when no channel has a chain (caller skips
+    executing in that case). Per-channel UNION ALL avoids the over-fetch
+    of a single `channel = ANY(channels)` filter when channels have
+    different chain depths — same rationale as postgres.
+    """
+    branches: list[str] = []
+    for n in chain_lens:
+        cid_placeholders = ",".join("?" * n)
+        branches.append(
+            "SELECT checkpoint_id, channel, task_id, idx, type, value "
+            "FROM writes "
+            "WHERE thread_id = ? AND checkpoint_ns = ? AND channel = ? "
+            f"AND checkpoint_id IN ({cid_placeholders})"
+        )
+    return " UNION ALL ".join(branches)
+
+
+def step_walk_with_row(
+    *,
+    cid: str,
+    parent_cid: str | None,
+    type_tag: str,
+    blob: bytes,
+    target_id: str,
+    serde: Any,
+    chain_by_ch: dict[str, list[str]],
+    seed_val_by_ch: dict[str, Any],
+    walk_state: dict[str, Any],
+    seeded: set[str],
+    channels: Sequence[str],
+) -> bool:
+    """Process one streamed stage-1 row in the merged ancestor walk.
+
+    The cursor returns (cid, parent_cid, type, blob) rows in
+    `checkpoint_id` DESC order starting at target. The first row is
+    target itself; we read its parent_cid to seed the walk and otherwise
+    skip it (target's own writes/seed are not part of the contract).
+
+    For each subsequent row, if `cid` matches the walk's current
+    position, we deserialize the blob, append the cid to every
+    not-yet-seeded channel's chain, and check `channel_values` for
+    seeds. The deserialized checkpoint is dropped before advancing — no
+    cross-row cache, so peak in-flight is one deserialized checkpoint.
+
+    Off-path rows (different branch on the same thread) advance the
+    cursor without doing any work.
+
+    Returns True when every requested channel is seeded — the caller
+    can stop iterating and close the cursor.
+    """
+    if "started" not in walk_state:
+        if cid == target_id:
+            walk_state["started"] = True
+            walk_state["cur_cid"] = parent_cid
+            walk_state["active"] = {ch for ch in channels if ch not in seeded}
+        # Not target yet (or target not present): keep streaming.
+        return False
+    active: set[str] = walk_state["active"]
+    if not active:
+        return True
+    if cid != walk_state["cur_cid"]:
+        # Off-path row from a sibling branch — skip without deserializing.
+        return False
+    for ch in active:
+        chain_by_ch[ch].append(cid)
+    ckpt = serde.loads_typed((type_tag, blob))
+    channel_values: Mapping[str, Any] = ckpt.get("channel_values") or {}
+    for ch in [ch for ch in active if ch in channel_values]:
+        seed_val_by_ch[ch] = channel_values[ch]
+        seeded.add(ch)
+        active.discard(ch)
+    del ckpt, channel_values
+    walk_state["cur_cid"] = parent_cid
+    return not active
+
+
+def build_delta_channels_writes_history(
+    *,
+    channels: Sequence[str],
+    chain_by_ch: Mapping[str, list[str]],
+    seed_val_by_ch: Mapping[str, Any],
+    seeded: set[str],
+    stage2_rows: Sequence[tuple[str, str, str, int, str, bytes]],
+    serde: Any,
+) -> dict[str, DeltaChannelHistory]:
+    """Demux stage-2 rows per channel; produce per-channel histories.
+
+    Stage-2 rows are `(checkpoint_id, channel, task_id, idx, type, value)`.
+    Final write order is oldest→newest globally and `(task_id, idx)` within
+    a checkpoint, matching the contract on `DeltaChannelHistory.writes`.
+
+    `seed` is omitted when the walk reached a true root with no snapshot
+    found (channel never entered `seeded`); consumers treat absence as
+    "start empty".
+    """
+    writes_by_ch_by_cid: dict[str, dict[str, list[tuple[str, bytes, str, int]]]] = {
+        ch: {} for ch in channels
+    }
+    for cid, ch, task_id, idx, type_tag, value_blob in stage2_rows:
+        writes_by_ch_by_cid.setdefault(ch, {}).setdefault(cid, []).append(
+            (type_tag, value_blob, task_id, idx)
+        )
+    for cid_map in writes_by_ch_by_cid.values():
+        for ws in cid_map.values():
+            ws.sort(key=lambda w: (w[2], w[3]))
+
+    result: dict[str, DeltaChannelHistory] = {}
+    for ch in channels:
+        chain_cids = chain_by_ch.get(ch, [])
+        cid_writes = writes_by_ch_by_cid.get(ch, {})
+        collected: list[PendingWrite] = []
+        # Chain is newest-first; iterate oldest-first for the public order.
+        for cid in reversed(chain_cids):
+            for type_tag, value_blob, task_id, _idx in cid_writes.get(cid, []):
+                collected.append(
+                    (task_id, ch, serde.loads_typed((type_tag, value_blob)))
+                )
+        entry: DeltaChannelHistory = {"writes": collected}
+        if ch in seeded:
+            entry["seed"] = seed_val_by_ch[ch]
+        result[ch] = entry
+    return result

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

@@ -0,0 +1,738 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import threading
+from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+from typing import Any, TypeVar, cast
+
+import aiosqlite
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    WRITES_IDX_MAP,
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    DeltaChannelHistory,
+    SerializerProtocol,
+    get_checkpoint_id,
+    get_checkpoint_metadata,
+)
+from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+from langgraph.checkpoint.sqlite._delta import (
+    DELTA_STAGE1_SQL,
+    build_delta_channels_writes_history,
+    build_delta_stage2_sql,
+    step_walk_with_row,
+)
+from langgraph.checkpoint.sqlite.utils import search_where
+
+T = TypeVar("T", bound=Callable)
+
+
+class AsyncSqliteSaver(BaseCheckpointSaver[str]):
+    """An asynchronous checkpoint saver that stores checkpoints in a SQLite database.
+
+    This class provides an asynchronous interface for saving and retrieving checkpoints
+    using a SQLite database. It's designed for use in asynchronous environments and
+    offers better performance for I/O-bound operations compared to synchronous alternatives.
+
+    Attributes:
+        conn (aiosqlite.Connection): The asynchronous SQLite database connection.
+        serde (SerializerProtocol): The serializer used for encoding/decoding checkpoints.
+
+    Tip:
+        Requires the [aiosqlite](https://pypi.org/project/aiosqlite/) package.
+        Install it with `pip install aiosqlite`.
+
+    Warning:
+        While this class supports asynchronous checkpointing, it is not recommended
+        for production workloads due to limitations in SQLite's write performance.
+        For production use, consider a more robust database like PostgreSQL.
+
+    Tip:
+        Remember to **close the database connection** after executing your code,
+        otherwise, you may see the graph "hang" after execution (since the program
+        will not exit until the connection is closed).
+
+        The easiest way is to use the `async with` statement as shown in the examples.
+
+        ```python
+        async with AsyncSqliteSaver.from_conn_string("checkpoints.sqlite") as saver:
+            # Your code here
+            graph = builder.compile(checkpointer=saver)
+            config = {"configurable": {"thread_id": "thread-1"}}
+            async for event in graph.astream_events(..., config, version="v1"):
+                print(event)
+        ```
+
+    Examples:
+        Usage within StateGraph:
+
+        ```pycon
+        >>> import asyncio
+        >>>
+        >>> from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+        >>> from langgraph.graph import StateGraph
+        >>>
+        >>> async def main():
+        >>>     builder = StateGraph(int)
+        >>>     builder.add_node("add_one", lambda x: x + 1)
+        >>>     builder.set_entry_point("add_one")
+        >>>     builder.set_finish_point("add_one")
+        >>>     async with AsyncSqliteSaver.from_conn_string("checkpoints.db") as memory:
+        >>>         graph = builder.compile(checkpointer=memory)
+        >>>         coro = graph.ainvoke(1, {"configurable": {"thread_id": "thread-1"}})
+        >>>         print(await asyncio.gather(coro))
+        >>>
+        >>> asyncio.run(main())
+        Output: [2]
+        ```
+        Raw usage:
+
+        ```pycon
+        >>> import asyncio
+        >>> import aiosqlite
+        >>> from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+        >>>
+        >>> async def main():
+        >>>     async with aiosqlite.connect("checkpoints.db") as conn:
+        ...         saver = AsyncSqliteSaver(conn)
+        ...         config = {"configurable": {"thread_id": "1", "checkpoint_ns": ""}}
+        ...         checkpoint = {"ts": "2023-05-03T10:00:00Z", "data": {"key": "value"}, "id": "0c62ca34-ac19-445d-bbb0-5b4984975b2a"}
+        ...         saved_config = await saver.aput(config, checkpoint, {}, {})
+        ...         print(saved_config)
+        >>> asyncio.run(main())
+        {'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '0c62ca34-ac19-445d-bbb0-5b4984975b2a'}}
+        ```
+    """
+
+    lock: asyncio.Lock
+    is_setup: bool
+
+    def __init__(
+        self,
+        conn: aiosqlite.Connection,
+        *,
+        serde: SerializerProtocol | None = None,
+    ):
+        super().__init__(serde=serde)
+        self.jsonplus_serde = JsonPlusSerializer()
+        self.conn = conn
+        self.lock = asyncio.Lock()
+        self.loop = asyncio.get_running_loop()
+        self.is_setup = False
+
+    @classmethod
+    @asynccontextmanager
+    async def from_conn_string(
+        cls, conn_string: str
+    ) -> AsyncIterator[AsyncSqliteSaver]:
+        """Create a new AsyncSqliteSaver instance from a connection string.
+
+        Args:
+            conn_string: The SQLite connection string.
+
+        Yields:
+            AsyncSqliteSaver: A new AsyncSqliteSaver instance.
+        """
+        async with aiosqlite.connect(conn_string) as conn:
+            yield cls(conn)
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple from the database.
+
+        This method retrieves a checkpoint tuple from the SQLite database based on the
+        provided config. If the config contains a `checkpoint_id` key, the checkpoint with
+        the matching thread ID and checkpoint ID is retrieved. Otherwise, the latest checkpoint
+        for the given thread ID is retrieved.
+
+        Args:
+            config: The config to use for retrieving the checkpoint.
+
+        Returns:
+            The retrieved checkpoint tuple, or None if no matching checkpoint was found.
+        """
+        try:
+            # check if we are in the main thread, only bg threads can block
+            # we don't check in other methods to avoid the overhead
+            if asyncio.get_running_loop() is self.loop:
+                raise asyncio.InvalidStateError(
+                    "Synchronous calls to AsyncSqliteSaver are only allowed from a "
+                    "different thread. From the main thread, use the async interface. "
+                    "For example, use `await checkpointer.aget_tuple(...)` or `await "
+                    "graph.ainvoke(...)`."
+                )
+        except RuntimeError:
+            pass
+        return asyncio.run_coroutine_threadsafe(
+            self.aget_tuple(config), self.loop
+        ).result()
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints from the database asynchronously.
+
+        This method retrieves a list of checkpoint tuples from the SQLite database based
+        on the provided config. The checkpoints are ordered by checkpoint ID in descending order (newest first).
+
+        Args:
+            config: Base configuration for filtering checkpoints.
+            filter: Additional filtering criteria for metadata.
+            before: If provided, only checkpoints before the specified checkpoint ID are returned.
+            limit: Maximum number of checkpoints to return.
+
+        Yields:
+            An iterator of matching checkpoint tuples.
+        """
+        try:
+            # check if we are in the main thread, only bg threads can block
+            # we don't check in other methods to avoid the overhead
+            if asyncio.get_running_loop() is self.loop:
+                raise asyncio.InvalidStateError(
+                    "Synchronous calls to AsyncSqliteSaver are only allowed from a "
+                    "different thread. From the main thread, use the async interface. "
+                    "For example, use `checkpointer.alist(...)` or `await "
+                    "graph.ainvoke(...)`."
+                )
+        except RuntimeError:
+            pass
+        aiter_ = self.alist(config, filter=filter, before=before, limit=limit)
+        while True:
+            try:
+                yield asyncio.run_coroutine_threadsafe(
+                    anext(aiter_),  # type: ignore[arg-type]  # noqa: F821
+                    self.loop,
+                ).result()
+            except StopAsyncIteration:
+                break
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the database.
+
+        This method saves a checkpoint to the SQLite database. The checkpoint is associated
+        with the provided config and its parent config (if any).
+
+        Args:
+            config: The config to associate with the checkpoint.
+            checkpoint: The checkpoint to save.
+            metadata: Additional metadata to save with the checkpoint.
+            new_versions: New channel versions as of this write.
+
+        Returns:
+            RunnableConfig: Updated configuration after storing the checkpoint.
+        """
+        return asyncio.run_coroutine_threadsafe(
+            self.aput(config, checkpoint, metadata, new_versions), self.loop
+        ).result()
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        return asyncio.run_coroutine_threadsafe(
+            self.aput_writes(config, writes, task_id, task_path), self.loop
+        ).result()
+
+    def delete_thread(self, thread_id: str) -> None:
+        """Delete all checkpoints and writes associated with a thread ID.
+
+        Args:
+            thread_id: The thread ID to delete.
+
+        Returns:
+            None
+        """
+        try:
+            # check if we are in the main thread, only bg threads can block
+            # we don't check in other methods to avoid the overhead
+            if asyncio.get_running_loop() is self.loop:
+                raise asyncio.InvalidStateError(
+                    "Synchronous calls to AsyncSqliteSaver are only allowed from a "
+                    "different thread. From the main thread, use the async interface. "
+                    "For example, use `checkpointer.alist(...)` or `await "
+                    "graph.ainvoke(...)`."
+                )
+        except RuntimeError:
+            pass
+        return asyncio.run_coroutine_threadsafe(
+            self.adelete_thread(thread_id), self.loop
+        ).result()
+
+    def get_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Sync bridge to `aget_delta_channel_history`.
+
+        Mirrors the same cross-thread guard as `get_tuple` /
+        `delete_thread` — calling from the loop thread raises rather than
+        deadlocking.
+        """
+        try:
+            if asyncio.get_running_loop() is self.loop:
+                raise asyncio.InvalidStateError(
+                    "Synchronous calls to AsyncSqliteSaver are only allowed from a "
+                    "different thread. From the main thread, use the async interface. "
+                    "For example, use `await checkpointer.aget_delta_channel_history(...)`."
+                )
+        except RuntimeError:
+            pass
+        return asyncio.run_coroutine_threadsafe(
+            self.aget_delta_channel_history(config=config, channels=channels),
+            self.loop,
+        ).result()
+
+    async def setup(self) -> None:
+        """Set up the checkpoint database asynchronously.
+
+        This method creates the necessary tables in the SQLite database if they don't
+        already exist. It is called automatically when needed and should not be called
+        directly by the user.
+        """
+        async with self.lock:
+            if self.is_setup:
+                return
+            await _ensure_connected(self.conn)
+            async with self.conn.executescript(
+                """
+                PRAGMA journal_mode=WAL;
+                CREATE TABLE IF NOT EXISTS checkpoints (
+                    thread_id TEXT NOT NULL,
+                    checkpoint_ns TEXT NOT NULL DEFAULT '',
+                    checkpoint_id TEXT NOT NULL,
+                    parent_checkpoint_id TEXT,
+                    type TEXT,
+                    checkpoint BLOB,
+                    metadata BLOB,
+                    PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+                );
+                CREATE TABLE IF NOT EXISTS writes (
+                    thread_id TEXT NOT NULL,
+                    checkpoint_ns TEXT NOT NULL DEFAULT '',
+                    checkpoint_id TEXT NOT NULL,
+                    task_id TEXT NOT NULL,
+                    idx INTEGER NOT NULL,
+                    channel TEXT NOT NULL,
+                    type TEXT,
+                    value BLOB,
+                    PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+                );
+                """
+            ):
+                await self.conn.commit()
+
+            self.is_setup = True
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        """Get a checkpoint tuple from the database asynchronously.
+
+        This method retrieves a checkpoint tuple from the SQLite database based on the
+        provided config. If the config contains a `checkpoint_id` key, the checkpoint with
+        the matching thread ID and checkpoint ID is retrieved. Otherwise, the latest checkpoint
+        for the given thread ID is retrieved.
+
+        Args:
+            config: The config to use for retrieving the checkpoint.
+
+        Returns:
+            The retrieved checkpoint tuple, or None if no matching checkpoint was found.
+        """
+        await self.setup()
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        async with self.lock, self.conn.cursor() as cur:
+            # find the latest checkpoint for the thread_id
+            if checkpoint_id := get_checkpoint_id(config):
+                await cur.execute(
+                    "SELECT thread_id, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?",
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        checkpoint_ns,
+                        checkpoint_id,
+                    ),
+                )
+            else:
+                await cur.execute(
+                    "SELECT thread_id, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata FROM checkpoints WHERE thread_id = ? AND checkpoint_ns = ? ORDER BY checkpoint_id DESC LIMIT 1",
+                    (str(config["configurable"]["thread_id"]), checkpoint_ns),
+                )
+            # if a checkpoint is found, return it
+            if value := await cur.fetchone():
+                (
+                    thread_id,
+                    checkpoint_id,
+                    parent_checkpoint_id,
+                    type,
+                    checkpoint,
+                    metadata,
+                ) = value
+                if not get_checkpoint_id(config):
+                    config = {
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    }
+                # find any pending writes
+                await cur.execute(
+                    "SELECT task_id, channel, type, value FROM writes WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ? ORDER BY task_id, idx",
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        checkpoint_ns,
+                        str(config["configurable"]["checkpoint_id"]),
+                    ),
+                )
+                # deserialize the checkpoint and metadata
+                return CheckpointTuple(
+                    config,
+                    self.serde.loads_typed((type, checkpoint)),
+                    cast(
+                        CheckpointMetadata,
+                        (json.loads(metadata) if metadata is not None else {}),
+                    ),
+                    (
+                        {
+                            "configurable": {
+                                "thread_id": thread_id,
+                                "checkpoint_ns": checkpoint_ns,
+                                "checkpoint_id": parent_checkpoint_id,
+                            }
+                        }
+                        if parent_checkpoint_id
+                        else None
+                    ),
+                    [
+                        (task_id, channel, self.serde.loads_typed((type, value)))
+                        async for task_id, channel, type, value in cur
+                    ],
+                )
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        """List checkpoints from the database asynchronously.
+
+        This method retrieves a list of checkpoint tuples from the SQLite database based
+        on the provided config. The checkpoints are ordered by checkpoint ID in descending order (newest first).
+
+        Args:
+            config: Base configuration for filtering checkpoints.
+            filter: Additional filtering criteria for metadata.
+            before: If provided, only checkpoints before the specified checkpoint ID are returned.
+            limit: Maximum number of checkpoints to return.
+
+        Yields:
+            An asynchronous iterator of matching checkpoint tuples.
+        """
+        await self.setup()
+        where, params = search_where(config, filter, before)
+        query = f"""SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+        FROM checkpoints
+        {where}
+        ORDER BY checkpoint_id DESC"""
+        if limit is not None:
+            query += " LIMIT ?"
+            params = (*params, limit)
+        async with (
+            self.lock,
+            self.conn.execute(query, params) as cur,
+            self.conn.cursor() as wcur,
+        ):
+            async for (
+                thread_id,
+                checkpoint_ns,
+                checkpoint_id,
+                parent_checkpoint_id,
+                type,
+                checkpoint,
+                metadata,
+            ) in cur:
+                await wcur.execute(
+                    "SELECT task_id, channel, type, value FROM writes WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ? ORDER BY task_id, idx",
+                    (thread_id, checkpoint_ns, checkpoint_id),
+                )
+                yield CheckpointTuple(
+                    {
+                        "configurable": {
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    },
+                    self.serde.loads_typed((type, checkpoint)),
+                    cast(
+                        CheckpointMetadata,
+                        (json.loads(metadata) if metadata is not None else {}),
+                    ),
+                    (
+                        {
+                            "configurable": {
+                                "thread_id": thread_id,
+                                "checkpoint_ns": checkpoint_ns,
+                                "checkpoint_id": parent_checkpoint_id,
+                            }
+                        }
+                        if parent_checkpoint_id
+                        else None
+                    ),
+                    [
+                        (task_id, channel, self.serde.loads_typed((type, value)))
+                        async for task_id, channel, type, value in wcur
+                    ],
+                )
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint to the database asynchronously.
+
+        This method saves a checkpoint to the SQLite database. The checkpoint is associated
+        with the provided config and its parent config (if any).
+
+        Args:
+            config: The config to associate with the checkpoint.
+            checkpoint: The checkpoint to save.
+            metadata: Additional metadata to save with the checkpoint.
+            new_versions: New channel versions as of this write.
+
+        Returns:
+            RunnableConfig: Updated configuration after storing the checkpoint.
+        """
+        await self.setup()
+        thread_id = config["configurable"]["thread_id"]
+        checkpoint_ns = config["configurable"]["checkpoint_ns"]
+        type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
+        serialized_metadata = json.dumps(
+            get_checkpoint_metadata(config, metadata), ensure_ascii=False
+        ).encode("utf-8", "ignore")
+        async with (
+            self.lock,
+            self.conn.execute(
+                "INSERT OR REPLACE INTO checkpoints (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    str(config["configurable"]["thread_id"]),
+                    checkpoint_ns,
+                    checkpoint["id"],
+                    config["configurable"].get("checkpoint_id"),
+                    type_,
+                    serialized_checkpoint,
+                    serialized_metadata,
+                ),
+            ),
+        ):
+            await self.conn.commit()
+        return {
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": checkpoint_ns,
+                "checkpoint_id": checkpoint["id"],
+            }
+        }
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Store intermediate writes linked to a checkpoint asynchronously.
+
+        This method saves intermediate writes associated with a checkpoint to the database.
+
+        Args:
+            config: Configuration of the related checkpoint.
+            writes: List of writes to store, each as (channel, value) pair.
+            task_id: Identifier for the task creating the writes.
+            task_path: Path of the task creating the writes.
+        """
+        query = (
+            "INSERT OR REPLACE INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+            if all(w[0] in WRITES_IDX_MAP for w in writes)
+            else "INSERT OR IGNORE INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+        )
+        await self.setup()
+        async with self.lock, self.conn.cursor() as cur:
+            await cur.executemany(
+                query,
+                [
+                    (
+                        str(config["configurable"]["thread_id"]),
+                        str(config["configurable"]["checkpoint_ns"]),
+                        str(config["configurable"]["checkpoint_id"]),
+                        task_id,
+                        WRITES_IDX_MAP.get(channel, idx),
+                        channel,
+                        *self.serde.dumps_typed(value),
+                    )
+                    for idx, (channel, value) in enumerate(writes)
+                ],
+            )
+            await self.conn.commit()
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        """Delete all checkpoints and writes associated with a thread ID.
+
+        Args:
+            thread_id: The thread ID to delete.
+
+        Returns:
+            None
+        """
+        async with self.lock, self.conn.cursor() as cur:
+            await cur.execute(
+                "DELETE FROM checkpoints WHERE thread_id = ?",
+                (str(thread_id),),
+            )
+            await cur.execute(
+                "DELETE FROM writes WHERE thread_id = ?",
+                (str(thread_id),),
+            )
+            await self.conn.commit()
+
+    async def aget_delta_channel_history(
+        self, *, config: RunnableConfig, channels: Sequence[str]
+    ) -> Mapping[str, DeltaChannelHistory]:
+        """Fast-path override of `BaseCheckpointSaver.aget_delta_channel_history`.
+
+        See `SqliteSaver.get_delta_channel_history` for design notes; this
+        is the async equivalent using `aiosqlite` cursors. Stage 1 pages
+        the parent chain newest-first and Python-deserializes each
+        checkpoint blob to find per-channel snapshots; stage 2 fetches
+        only the relevant writes via per-channel UNION ALL.
+        """
+        if not channels:
+            return {}
+        channels = list(channels)
+        await self.setup()
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = get_checkpoint_id(config)
+        if checkpoint_id is None:
+            target = await self.aget_tuple(config)
+            if target is None:
+                return {ch: {"writes": []} for ch in channels}
+            checkpoint_id = target.config["configurable"]["checkpoint_id"]
+
+        chain_by_ch: dict[str, list[str]] = {ch: [] for ch in channels}
+        seed_val_by_ch: dict[str, Any] = {}
+        walk_state: dict[str, Any] = {}
+        seeded: set[str] = set()
+
+        async with self.lock, self.conn.cursor() as cur:
+            await cur.execute(
+                DELTA_STAGE1_SQL, (thread_id, checkpoint_ns, checkpoint_id)
+            )
+            async for row in cur:
+                cid, parent_cid, type_tag, blob = row
+                if step_walk_with_row(
+                    cid=cid,
+                    parent_cid=parent_cid,
+                    type_tag=type_tag,
+                    blob=blob,
+                    target_id=checkpoint_id,
+                    serde=self.serde,
+                    chain_by_ch=chain_by_ch,
+                    seed_val_by_ch=seed_val_by_ch,
+                    walk_state=walk_state,
+                    seeded=seeded,
+                    channels=channels,
+                ):
+                    break
+
+            channels_with_chain = [ch for ch in channels if chain_by_ch[ch]]
+            stage2_sql = build_delta_stage2_sql(
+                chain_lens=[len(chain_by_ch[ch]) for ch in channels_with_chain],
+            )
+            if stage2_sql:
+                stage2_params: list[Any] = []
+                for ch in channels_with_chain:
+                    stage2_params.extend(
+                        [thread_id, checkpoint_ns, ch, *chain_by_ch[ch]]
+                    )
+                await cur.execute(stage2_sql, stage2_params)
+                stage2_rows = cast(
+                    "list[tuple[str, str, str, int, str, bytes]]",
+                    await cur.fetchall(),
+                )
+            else:
+                stage2_rows = []
+
+        return build_delta_channels_writes_history(
+            channels=channels,
+            chain_by_ch=chain_by_ch,
+            seed_val_by_ch=seed_val_by_ch,
+            seeded=seeded,
+            stage2_rows=stage2_rows,
+            serde=self.serde,
+        )
+
+    def get_next_version(self, current: str | None, channel: None) -> str:
+        """Generate the next version ID for a channel.
+
+        This method creates a new version identifier for a channel based on its current version.
+
+        Args:
+            current (Optional[str]): The current version identifier of the channel.
+
+        Returns:
+            str: The next version identifier, which is guaranteed to be monotonically increasing.
+        """
+        if current is None:
+            current_v = 0
+        elif isinstance(current, int):
+            current_v = current
+        else:
+            current_v = int(current.split(".")[0])
+        next_v = current_v + 1
+        next_h = random.random()
+        return f"{next_v:032}.{next_h:016}"
+
+
+async def _ensure_connected(conn: aiosqlite.Connection) -> None:
+    if not _CONN_STARTED_CHECK(conn):
+        await conn
+
+
+def _build_conn_started_check() -> Callable[[aiosqlite.Connection], bool]:
+    is_alive = getattr(aiosqlite.Connection, "is_alive", None)
+    if callable(is_alive):
+        return lambda conn: conn.is_alive()  # type: ignore[attr-defined]
+
+    def _started(conn: aiosqlite.Connection) -> bool:
+        thread: threading.Thread | None = getattr(conn, "_thread", None)
+        return False if thread is None else thread.is_alive()
+
+    return _started
+
+
+_CONN_STARTED_CHECK = _build_conn_started_check()

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/utils.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import get_checkpoint_id
+
+_FILTER_PATTERN = re.compile(r"^[a-zA-Z0-9_.-]+$")
+
+
+def _validate_filter_key(key: str) -> None:
+    """Validate that a filter key is safe for use in SQL queries.
+
+    Args:
+        key: The filter key to validate
+
+    Raises:
+        ValueError: If the key contains invalid characters that could enable SQL injection
+    """
+    # Allow alphanumeric characters, underscores, dots, and hyphens
+    # This covers typical JSON property names while preventing SQL injection
+    if not _FILTER_PATTERN.match(key):
+        raise ValueError(
+            f"Invalid filter key: '{key}'. Filter keys must contain only alphanumeric characters, underscores, dots, and hyphens."
+        )
+
+
+def _metadata_predicate(
+    metadata_filter: dict[str, Any],
+) -> tuple[Sequence[str], Sequence[Any]]:
+    """Return WHERE clause predicates for (a)search() given metadata filter.
+
+    This method returns a tuple of a string and a tuple of values. The string
+    is the parametered WHERE clause predicate (excluding the WHERE keyword):
+    "column1 = ? AND column2 IS ?". The tuple of values contains the values
+    for each of the corresponding parameters.
+    """
+
+    def _where_value(query_value: Any) -> tuple[str, Any]:
+        """Return tuple of operator and value for WHERE clause predicate."""
+        if query_value is None:
+            return ("IS ?", None)
+        elif (
+            isinstance(query_value, str)
+            or isinstance(query_value, int)
+            or isinstance(query_value, float)
+        ):
+            return ("= ?", query_value)
+        elif isinstance(query_value, bool):
+            return ("= ?", 1 if query_value else 0)
+        elif isinstance(query_value, dict) or isinstance(query_value, list):
+            # query value for JSON object cannot have trailing space after separators (, :)
+            # SQLite json_extract() returns JSON string without whitespace
+            return ("= ?", json.dumps(query_value, separators=(",", ":")))
+        else:
+            return ("= ?", str(query_value))
+
+    predicates = []
+    param_values = []
+
+    # process metadata query
+    for query_key, query_value in metadata_filter.items():
+        _validate_filter_key(query_key)
+        operator, param_value = _where_value(query_value)
+        predicates.append(
+            f"json_extract(CAST(metadata AS TEXT), '$.{query_key}') {operator}"
+        )
+        param_values.append(param_value)
+
+    return (predicates, param_values)
+
+
+def search_where(
+    config: RunnableConfig | None,
+    filter: dict[str, Any] | None,
+    before: RunnableConfig | None = None,
+) -> tuple[str, Sequence[Any]]:
+    """Return WHERE clause predicates for (a)search() given metadata filter
+    and `before` config.
+
+    This method returns a tuple of a string and a tuple of values. The string
+    is the parametered WHERE clause predicate (including the WHERE keyword):
+    "WHERE column1 = ? AND column2 IS ?". The tuple of values contains the
+    values for each of the corresponding parameters.
+    """
+    wheres = []
+    param_values = []
+
+    # construct predicate for config filter
+    if config is not None:
+        wheres.append("thread_id = ?")
+        param_values.append(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns")
+        if checkpoint_ns is not None:
+            wheres.append("checkpoint_ns = ?")
+            param_values.append(checkpoint_ns)
+
+        if checkpoint_id := get_checkpoint_id(config):
+            wheres.append("checkpoint_id = ?")
+            param_values.append(checkpoint_id)
+
+    # construct predicate for metadata filter
+    if filter:
+        metadata_predicates, metadata_values = _metadata_predicate(filter)
+        wheres.extend(metadata_predicates)
+        param_values.extend(metadata_values)
+
+    # construct predicate for `before`
+    if before is not None:
+        wheres.append("checkpoint_id < ?")
+        param_values.append(get_checkpoint_id(before))
+
+    return ("WHERE " + " AND ".join(wheres) if wheres else "", param_values)