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

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-checkpoint-postgres
-Version: 3.1.0a4
+Version: 3.1.1
 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
@@ -135,3 +155,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.1}/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
@@ -118,3 +138,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.1}/langgraph/checkpoint/postgres/base.py

@@ -279,8 +279,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"

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.1}/langgraph/store/postgres/base.py

@@ -4,6 +4,7 @@ import asyncio
 import concurrent.futures
 import json
 import logging
+import re
 import threading
 from collections import defaultdict
 from collections.abc import Callable, Iterable, Iterator, Sequence
@@ -238,6 +239,12 @@ class BasePostgresStore(Generic[C]):
     conn: C
     _deserializer: Callable[[bytes | orjson.Fragment], dict[str, Any]] | None
     index_config: PostgresIndexConfig | None
+    ttl_config: TTLConfig | None
+
+    @property
+    def _omit_expired(self) -> bool:
+        """Whether expired-but-unswept rows should be filtered from reads."""
+        return bool(self.ttl_config and self.ttl_config.get("omit_expired"))
 
     def _get_batch_GET_ops_queries(
         self,
@@ -258,12 +265,17 @@ class BasePostgresStore(Generic[C]):
             namespace_groups[op.namespace].append((idx, op.key))
             refresh_ttls[op.namespace].append(op.refresh_ttl)
 
+        omit_expired = self._omit_expired
+        expiry_clause = (
+            "AND (s.expires_at IS NULL OR s.expires_at > NOW())" if omit_expired else ""
+        )
+
         results = []
         for namespace, items in namespace_groups.items():
             _, keys = zip(*items, strict=False)
             this_refresh_ttls = refresh_ttls[namespace]
 
-            query = """
+            query = f"""
                 WITH passed_in AS (
                     SELECT unnest(%s::text[]) AS key,
                         unnest(%s::bool[])  AS do_refresh
@@ -276,12 +288,14 @@ class BasePostgresStore(Generic[C]):
                     AND s.key    = p.key
                     AND p.do_refresh = TRUE
                     AND s.ttl_minutes IS NOT NULL
+                    {expiry_clause}
                     RETURNING s.key
                 )
                 SELECT s.key, s.value, s.created_at, s.updated_at
                 FROM store s
                 JOIN passed_in p ON s.key = p.key
                 WHERE s.prefix = %s
+                {expiry_clause}
             """
             ns_text = _namespace_to_text(namespace)
             params = (
@@ -422,6 +436,13 @@ class BasePostgresStore(Generic[C]):
         - embedding_requests: list of (original_index_in_search_ops, text_query)
         """
 
+        omit_expired = self._omit_expired
+        search_expiry_clause = (
+            "AND (store.expires_at IS NULL OR store.expires_at > NOW())"
+            if omit_expired
+            else ""
+        )
+
         queries = []
         embedding_requests = []
         for idx, (_, op) in enumerate(search_ops):
@@ -443,8 +464,9 @@ class BasePostgresStore(Generic[C]):
             ns_condition = "TRUE"
             ns_param: Sequence[str] | None = None
             if op.namespace_prefix:
-                ns_condition = "store.prefix LIKE %s"
-                ns_param = (f"{_namespace_to_text(op.namespace_prefix)}%",)
+                ns_condition, ns_param = _namespace_prefix_condition(
+                    op.namespace_prefix
+                )
             else:
                 ns_param = ()
 
@@ -491,7 +513,7 @@ class BasePostgresStore(Generic[C]):
                             {score_operator} AS neg_score
                         FROM store
                         JOIN store_vectors sv ON store.prefix = sv.prefix AND store.key = sv.key
-                        WHERE {ns_condition} {extra_filters}
+                        WHERE {ns_condition} {extra_filters} {search_expiry_clause}
                         ORDER BY {score_operator} ASC
                         LIMIT %s
                     """
@@ -527,7 +549,7 @@ class BasePostgresStore(Generic[C]):
                 base_query = f"""
                         SELECT store.prefix, store.key, store.value, store.created_at, store.updated_at, NULL AS score
                         FROM store
-                        WHERE {ns_condition} {extra_filters}
+                        WHERE {ns_condition} {extra_filters} {search_expiry_clause}
                         ORDER BY store.updated_at DESC
                         LIMIT %s
                         OFFSET %s
@@ -591,18 +613,23 @@ class BasePostgresStore(Generic[C]):
             """
             params: list[Any] = [op.max_depth, op.max_depth]
 
+            omit_expired = self._omit_expired
             conditions = []
+            if omit_expired:
+                conditions.append("(expires_at IS NULL OR expires_at > NOW())")
             if op.match_conditions:
                 for condition in op.match_conditions:
-                    if condition.match_type == "prefix":
-                        conditions.append("prefix LIKE %s")
+                    if condition.match_type in ("prefix", "suffix"):
+                        if not condition.path:
+                            # An empty path constrains nothing; skipping keeps it a
+                            # no-op rather than emitting a pattern that matches no
+                            # namespace at all.
+                            continue
+                        conditions.append("prefix ~ %s")
                         params.append(
-                            f"{_namespace_to_text(condition.path, handle_wildcards=True)}%"
-                        )
-                    elif condition.match_type == "suffix":
-                        conditions.append("prefix LIKE %s")
-                        params.append(
-                            f"%{_namespace_to_text(condition.path, handle_wildcards=True)}"
+                            _namespace_match_pattern(
+                                condition.path, condition.match_type
+                            )
                         )
                     else:
                         logger.warning(
@@ -1248,15 +1275,59 @@ def _get_index_params(store: Any) -> tuple[str, dict[str, Any]]:
     return kind, sanitized
 
 
-def _namespace_to_text(
-    namespace: tuple[str, ...], handle_wildcards: bool = False
-) -> str:
+def _namespace_to_text(namespace: tuple[str, ...]) -> str:
     """Convert namespace tuple to text string."""
-    if handle_wildcards:
-        namespace = tuple("%" if val == "*" else val for val in namespace)
     return ".".join(namespace)
 
 
+def _escape_like_literal(text: str) -> str:
+    """Escape LIKE metacharacters so `text` is matched literally.
+
+    Namespace labels may contain `_` and `%`, which would otherwise act as
+    wildcards: `("user_1",)` would match `("userX1",)`. Backslash is escaped
+    first so it cannot escape the following character. Requires an explicit
+    `ESCAPE '\\'` clause on the pattern.
+    """
+    return text.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
+def _namespace_prefix_condition(namespace_prefix: tuple[str, ...]) -> tuple[str, tuple]:
+    """Build the SQL scoping a search to a namespace and its descendants.
+
+    Matches the namespace exactly or requires the `.` separator before any
+    remainder, so a prefix of `("foo",)` does not also match `("foobar",)`.
+
+    Both arms stay index-friendly: equality on the `(prefix, key)` primary key,
+    the anchored LIKE on the `prefix text_pattern_ops` index.
+
+    Only the LIKE arm is escaped -- equality does not interpret metacharacters,
+    so escaping it would stop `("user_1",)` from matching itself.
+    """
+    path = _namespace_to_text(namespace_prefix)
+    condition = r"(store.prefix = %s OR store.prefix LIKE %s ESCAPE '\')"
+    return condition, (path, f"{_escape_like_literal(path)}.%")
+
+
+def _namespace_match_pattern(path: tuple[str, ...], match_type: str) -> str:
+    """Build a POSIX regex matching the dot-joined prefix on whole segments.
+
+    Needed because `LIKE` cannot express "any character except the separator".
+    Matches how `InMemoryStore` compares namespaces element-wise.
+
+    `*` matches exactly one segment. Prefix matches stay open-ended but must end
+    on a separator; suffix matches anchor at the end and begin on one.
+
+    Examples:
+        prefix ("uid", "*", "alice") -> ^uid\\.[^.]+\\.alice(\\.|\\Z)
+        suffix ("alice",)            -> (^|\\.)alice\\Z
+    """
+    segments = ("[^.]+" if part == "*" else re.escape(part) for part in path)
+    body = r"\.".join(segments)
+    if match_type == "suffix":
+        return rf"(^|\.){body}\Z"
+    return rf"^{body}(\.|\Z)"
+
+
 def _row_to_item(
     namespace: tuple[str, ...],
     row: Row,

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph-checkpoint-postgres"
-version = "3.1.0a4"
+version = "3.1.1"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 authors = []
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ readme = "README.md"
 license = "MIT"
 license-files = ['LICENSE']
 dependencies = [
-  "langgraph-checkpoint>=4.1.0a4,<5.0.0",
+  "langgraph-checkpoint>=4.1.0,<5.0.0",
   "orjson>=3.11.5",
   "psycopg>=3.2.0",
   "psycopg-pool>=3.2.0",
@@ -37,7 +37,7 @@ test = [
 lint = [
   "ruff",
   "codespell",
-  "mypy",
+  "ty",
 ]
 dev = [
   {include-group = "test"},
@@ -69,15 +69,15 @@ lint.select = [
 lint.ignore = ["E501", "B008"]
 target-version = "py310"
 
-[tool.mypy]
-# https://mypy.readthedocs.io/en/stable/config_file.html
-disallow_untyped_defs = "True"
-explicit_package_bases = "True"
-warn_no_return = "False"
-warn_unused_ignores = "True"
-warn_redundant_casts = "True"
-allow_redefinition = "True"
-disable_error_code = "typeddict-item, return-value"
+[tool.ty.rules]
+invalid-argument-type = "ignore"
+invalid-assignment = "ignore"
+invalid-key = "ignore"
+invalid-return-type = "ignore"
+invalid-typed-dict-field = "ignore"
+invalid-yield = "ignore"
+no-matching-overload = "ignore"
+unused-type-ignore-comment = "ignore"
 
 [tool.pytest-watcher]
 now = true

{langgraph_checkpoint_postgres-3.1.0a4 → langgraph_checkpoint_postgres-3.1.1}/tests/test_async_store.py

@@ -739,3 +739,135 @@ async def test_store_ttl(store):
     # Now has been (TTL_SECONDS-2)*2 > TTL_SECONDS + TTL_SECONDS/2
     results = await store.asearch(ns, query="bar", refresh_ttl=False)
     assert len(results) == 0
+
+
+async def _aexpire_now(
+    store: AsyncPostgresStore, ns: tuple[str, ...], key: str
+) -> None:
+    """Backdate a row's expires_at into the past without deleting it (unswept)."""
+    async with store._cursor() as cur:
+        await cur.execute(
+            "UPDATE store SET expires_at = NOW() - INTERVAL '1 minute' "
+            "WHERE prefix = %s AND key = %s",
+            (".".join(ns), key),
+        )
+
+
+async def _arow_exists(
+    store: AsyncPostgresStore, ns: tuple[str, ...], key: str
+) -> bool:
+    async with store._cursor() as cur:
+        await cur.execute(
+            "SELECT COUNT(*) AS n FROM store WHERE prefix = %s AND key = %s",
+            (".".join(ns), key),
+        )
+        return (await cur.fetchone())["n"] == 1
+
+
+async def _astored_expires_at(store: AsyncPostgresStore, ns: tuple[str, ...], key: str):
+    async with store._cursor() as cur:
+        await cur.execute(
+            "SELECT expires_at FROM store WHERE prefix = %s AND key = %s",
+            (".".join(ns), key),
+        )
+        return (await cur.fetchone())["expires_at"]
+
+
+async def test_omit_expired_filters_read_paths(store: AsyncPostgresStore) -> None:
+    await store.stop_ttl_sweeper()  # deterministic: no background deletion
+    store.ttl_config["omit_expired"] = True
+
+    expired_ns = ("omit", "expired")
+    control_ns = ("omit", "control")
+    await store.aput(expired_ns, "e", {"data": "gone"}, ttl=TTL_MINUTES)
+    await store.aput(control_ns, "c", {"data": "keep"}, ttl=None)
+    await _aexpire_now(store, expired_ns, "e")
+
+    # The row is expired but physically still present (unswept).
+    assert await _arow_exists(store, expired_ns, "e")
+
+    # aget omits it; the never-expiring control is still returned.
+    assert await store.aget(expired_ns, "e") is None
+    assert await store.aget(control_ns, "c") is not None
+
+    # asearch omits it but returns the control.
+    assert await store.asearch(expired_ns) == []
+    assert [i.key for i in await store.asearch(control_ns)] == ["c"]
+
+    # alist_namespaces drops the expired-only namespace, keeps the control.
+    namespaces = await store.alist_namespaces(prefix=("omit",))
+    assert expired_ns not in namespaces
+    assert control_ns in namespaces
+
+
+@pytest.mark.parametrize("omit", [None, False], ids=["default", "explicit-false"])
+async def test_omit_expired_disabled_preserves_expired_rows(
+    store: AsyncPostgresStore, omit
+) -> None:
+    await store.stop_ttl_sweeper()
+    if omit is not None:
+        store.ttl_config["omit_expired"] = omit
+
+    ns = ("keep",)
+    await store.aput(ns, "k", {"data": "still-here"}, ttl=TTL_MINUTES)
+    await _aexpire_now(store, ns, "k")
+
+    assert await store.aget(ns, "k", refresh_ttl=False) is not None
+    assert [i.key for i in await store.asearch(ns, refresh_ttl=False)] == ["k"]
+    assert ns in await store.alist_namespaces(prefix=("keep",))
+
+
+async def test_omit_expired_refresh_ttl_only_refreshes_live_rows(
+    store: AsyncPostgresStore,
+) -> None:
+    await store.stop_ttl_sweeper()
+    store.ttl_config["omit_expired"] = True
+
+    ns = ("refresh",)
+    await store.aput(ns, "expired", {"n": 0}, ttl=TTL_MINUTES)
+    await store.aput(ns, "live_get", {"n": 1}, ttl=TTL_MINUTES)
+    await store.aput(ns, "live_search", {"n": 2}, ttl=TTL_MINUTES)
+    await _aexpire_now(store, ns, "expired")
+
+    expired_before = await _astored_expires_at(store, ns, "expired")
+    get_before = await _astored_expires_at(store, ns, "live_get")
+    search_before = await _astored_expires_at(store, ns, "live_search")
+
+    # refresh_ttl=True must NOT resurrect the expired row (via aget or asearch)...
+    assert await store.aget(ns, "expired", refresh_ttl=True) is None
+    live_keys = [i.key for i in await store.asearch(ns, refresh_ttl=True)]
+    assert "expired" not in live_keys
+    assert await _astored_expires_at(store, ns, "expired") == expired_before
+
+    # ...but must still extend the live rows that were read.
+    assert await store.aget(ns, "live_get", refresh_ttl=True) is not None
+    assert await _astored_expires_at(store, ns, "live_get") > get_before
+    assert await _astored_expires_at(store, ns, "live_search") > search_before
+
+
+async def test_omit_expired_search_pagination(store: AsyncPostgresStore) -> None:
+    await store.stop_ttl_sweeper()
+    store.ttl_config["omit_expired"] = True
+
+    ns = ("page",)
+    for k in ("a", "b", "c"):
+        await store.aput(ns, k, {"k": k}, ttl=TTL_MINUTES)
+    await store.aput(ns, "expired", {"k": "x"}, ttl=TTL_MINUTES)
+    await _aexpire_now(store, ns, "expired")
+
+    seconds_ago = {"a": 1, "expired": 2, "b": 3, "c": 4}
+    # updated_at DESC orders these a, expired, b, c, so the expired row sits inside
+    # the first limit=2 window. Correct (pre-LIMIT) filtering yields live pages
+    # [a, b] then [c]; post-LIMIT filtering would underfill page 1 to just [a].
+    async with store._cursor() as cur:
+        for key, secs in seconds_ago.items():
+            await cur.execute(
+                "UPDATE store SET updated_at = NOW() - (%s * INTERVAL '1 second') "
+                "WHERE prefix = %s AND key = %s",
+                (secs, ".".join(ns), key),
+            )
+
+    page1 = await store.asearch(ns, limit=2, offset=0)
+    page2 = await store.asearch(ns, limit=2, offset=2)
+    assert [i.key for i in page1] == ["a", "b"]
+    assert [i.key for i in page2] == ["c"]