community-agent-framework-postgres 0.1.1__py3-none-any.whl

agent_framework_community_postgres/_framework.py

@@ -0,0 +1,148 @@
+"""Every import of a private Agent Framework name, and the check against the tested MAF versions, in one place.
+
+Microsoft's own Cosmos DB and Redis packages import these same names from the
+same private modules. Keeping them here means an upstream rename breaks one
+file, and ``tests/unit/test_framework.py`` fails before a user notices.
+
+Verified against agent-framework-core 1.20.0 and 1.21.0 on 11 October 2026. 1.20 is the
+floor because 1.19's ``filter_new_messages`` dropped any incoming message whose
+content matched one already stored, so a repeated "yes" was lost.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+
+SUPPORTED_CORE = ">=1.20.0,<2"
+"""The declared ``agent-framework-core`` range: MAF keeps breaking changes for major versions."""
+
+TESTED_CORE = ("1.20", "1.21")
+"""The ``agent-framework-core`` minors this release was tested on (major.minor)."""
+
+TESTED_AG_UI = ("1.5",)
+"""The ``agent-framework-ag-ui`` minors this release was tested on (major.minor)."""
+
+logger = logging.getLogger("agent_framework_community_postgres")
+_logged = False
+
+
+def installed_core_version() -> str:
+    """The installed agent-framework-core version, or ``unknown``."""
+    try:
+        return version("agent-framework-core")
+    except PackageNotFoundError:  # pragma: no cover
+        return "unknown"
+
+
+def _major_minor(text: str) -> tuple[int, int] | None:
+    """The numeric major.minor at the start of a version string; pre-release and local parts are ignored."""
+    match = re.match(r"(\d+)\.(\d+)", text)
+    return (int(match[1]), int(match[2])) if match else None
+
+
+@dataclass(frozen=True)
+class Compatibility:
+    """Installed Agent Framework versions next to the minors this release was tested on."""
+
+    core_installed: str
+    core_tested: tuple[str, ...]
+    ag_ui_installed: str | None
+    ag_ui_tested: tuple[str, ...]
+
+    def _pairs(self) -> list[tuple[str, str, tuple[str, ...]]]:
+        pairs = [("agent-framework-core", self.core_installed, self.core_tested)]
+        if self.ag_ui_installed is not None:
+            pairs.append(("agent-framework-ag-ui", self.ag_ui_installed, self.ag_ui_tested))
+        return pairs
+
+    @property
+    def untested(self) -> tuple[str, ...]:
+        """Distributions whose installed major.minor is newer than any tested one."""
+        return tuple(name for name, installed, tested in self._pairs() if _newer(installed, tested) is not None)
+
+    @property
+    def out_of_range(self) -> tuple[str, ...]:
+        """Distributions whose installed major is newer than the tested major: outside the declared range."""
+        return tuple(name for name, installed, tested in self._pairs() if _newer(installed, tested) == "major")
+
+
+def _newer(installed: str, tested: tuple[str, ...]) -> str | None:
+    current = _major_minor(installed)
+    newest = max(filter(None, map(_major_minor, tested)))
+    if current is None or current <= newest:
+        return None
+    return "major" if current[0] > newest[0] else "minor"
+
+
+def compatibility() -> Compatibility:
+    """What is installed and what was tested; ``untested`` is empty when every version is covered."""
+    try:
+        ag_ui: str | None = version("agent-framework-ag-ui")
+    except PackageNotFoundError:
+        ag_ui = None
+    return Compatibility(installed_core_version(), TESTED_CORE, ag_ui, TESTED_AG_UI)
+
+
+def log_untested_once() -> None:
+    """Log one warning per process when an installed Agent Framework is newer than any tested minor.
+
+    Called by every store and hub constructor. Importing the package logs nothing.
+    """
+    global _logged
+    if _logged:
+        return
+    _logged = True
+    report = compatibility()
+    for name, installed, tested in report._pairs():  # pyright: ignore[reportPrivateUsage]
+        kind = _newer(installed, tested)
+        if kind is None:
+            continue
+        current = _major_minor(installed)
+        if current is None:
+            continue
+        if kind == "major":
+            advice = (
+                f"{name} {installed} is a new major version, outside the declared range and likely to break;"
+                f" pin {name}<{current[0]} and open an issue."
+            )
+        else:
+            advice = (
+                "It is expected to work, since Agent Framework keeps breaking changes for major versions;"
+                f" if something fails, pin {name}<{current[0]}.{current[1]} and open an issue."
+            )
+        logger.warning(
+            "community-agent-framework-postgres has not been tested with %s %s (tested: %s). %s",
+            name,
+            installed,
+            ", ".join(tested),
+            advice,
+        )
+
+
+try:
+    # The shared dedupe every history provider (Cosmos, Redis, File) uses.
+    from agent_framework._sessions import filter_new_messages
+
+    # The hybrid JSON + restricted-pickle encoding File and Cosmos storage use.
+    from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
+except ImportError as exc:  # pragma: no cover - exercised only by an incompatible upstream release
+    raise ImportError(
+        f"agent-framework-core {installed_core_version()} no longer provides a private name this package relies on "
+        f"({exc}). This release declares agent-framework-core {SUPPORTED_CORE} and was tested on "
+        f"{', '.join(TESTED_CORE)}; pin an earlier agent-framework-core or check for a newer "
+        "community-agent-framework-postgres, and open an issue."
+    ) from exc
+
+__all__ = [
+    "SUPPORTED_CORE",
+    "TESTED_AG_UI",
+    "TESTED_CORE",
+    "Compatibility",
+    "compatibility",
+    "decode_checkpoint_value",
+    "encode_checkpoint_value",
+    "filter_new_messages",
+    "installed_core_version",
+    "log_untested_once",
+]

agent_framework_community_postgres/_history_provider.py

@@ -0,0 +1,261 @@
+"""Conversation history in PostgreSQL, one row per message, scoped like the Redis provider."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+from typing import Any, ClassVar, cast
+
+from agent_framework import HistoryProvider, Message, SecretString
+from psycopg import AsyncConnection, sql
+
+from ._client import ClientHandle, PostgresClient, PostgresStorageError, optional_text, require_text
+from ._entra import EntraCredential
+from ._framework import filter_new_messages
+from ._json import encode_jsonb
+from ._retention import EXPIRES_AT, PurgeReport, RetentionPolicy, purge_rows
+from ._store import BaseStore
+
+logger = logging.getLogger(__name__)
+
+
+class PostgresHistoryProvider(HistoryProvider, BaseStore):
+    """PostgreSQL-backed ``HistoryProvider``.
+
+    Rows are isolated by application, optional tenant and agent, provider ``source_id``
+    and session id, the same boundaries ``RedisHistoryProvider`` uses. These identifiers
+    select stored history; they are not authorization. Bind them to authenticated
+    context in the application.
+
+    Saves to one session are serialized by a transaction-scoped advisory lock, so
+    concurrent writers never duplicate history. When an agent runs without an explicit
+    session, MAF creates a new session id per call, so each stateless run writes a new
+    history; pass a session or set ``retention``.
+    """
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "postgres_history"
+
+    def __init__(
+        self,
+        source_id: str = DEFAULT_SOURCE_ID,
+        *,
+        application_id: str,
+        tenant_id: str | None = None,
+        agent_id: str | None = None,
+        max_messages: int | None = None,
+        load_messages: bool = True,
+        store_inputs: bool = True,
+        store_context_messages: bool = False,
+        store_context_from: set[str] | None = None,
+        store_outputs: bool = True,
+        connection_string: str | SecretString | None = None,
+        client: PostgresClient | ClientHandle | None = None,
+        credential: EntraCredential | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        schema: str = "public",
+        table_prefix: str = "af_",
+        retention: RetentionPolicy | None = None,
+        pool_kwargs: Mapping[str, Any] | None = None,
+    ) -> None:
+        HistoryProvider.__init__(
+            self,
+            require_text(source_id, "source_id"),
+            load_messages=load_messages,
+            store_inputs=store_inputs,
+            store_context_messages=store_context_messages,
+            store_context_from=store_context_from,
+            store_outputs=store_outputs,
+        )
+        BaseStore.__init__(
+            self,
+            application_id=application_id,
+            connection_string=connection_string,
+            client=client,
+            credential=credential,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+            schema=schema,
+            table_prefix=table_prefix,
+            retention=retention,
+            pool_kwargs=pool_kwargs,
+        )
+        if max_messages is not None and max_messages < 0:
+            raise ValueError("max_messages must be None (unlimited) or a non-negative integer.")
+        self.tenant_id = optional_text(tenant_id, "tenant_id")
+        self.agent_id = optional_text(agent_id, "agent_id")
+        self.max_messages = max_messages
+
+    _SCOPE = sql.SQL(
+        "application_id = %(app)s AND tenant_id = %(tenant)s AND agent_id = %(agent)s"
+        " AND source_id = %(source)s AND session_id = %(session)s"
+    )
+
+    def _params(self, session_id: str | None) -> dict[str, Any]:
+        return {
+            "app": self.application_id,
+            "tenant": self.tenant_id,
+            "agent": self.agent_id,
+            "source": self.source_id,
+            "session": require_text(session_id, "session_id"),
+        }
+
+    async def get_messages(
+        self, session_id: str | None, *, state: dict[str, Any] | None = None, **kwargs: Any
+    ) -> list[Message]:
+        """All stored messages for the session, oldest first; set ``max_messages`` to bound the session."""
+        params = self._params(session_id)
+        async with self._client.connection(transactional=False) as connection:
+            return await self._read(connection, params)
+
+    @staticmethod
+    def _decode(payload: Any) -> Message:
+        if not isinstance(payload, dict):
+            raise ValueError("not an object")
+        return Message.from_dict(cast("dict[str, Any]", payload))
+
+    async def _read(self, connection: AsyncConnection[Any], params: dict[str, Any]) -> list[Message]:
+        cursor = await connection.execute(
+            sql.SQL("SELECT message FROM {history} WHERE {scope} ORDER BY id").format(
+                history=self._names.table("history_messages"), scope=self._SCOPE
+            ),
+            params,
+        )
+        messages: list[Message] = []
+        for (payload,) in await cursor.fetchall():
+            try:
+                messages.append(self._decode(payload))
+            except (ValueError, TypeError, KeyError, AttributeError):
+                logger.warning("Skipping a history row that failed to deserialize.")
+        return messages
+
+    async def _tail(self, connection: AsyncConnection[Any], params: dict[str, Any], limit: int) -> list[Message]:
+        """The newest ``limit`` stored messages, oldest first; raises when one no longer deserializes."""
+        cursor = await connection.execute(
+            sql.SQL("SELECT message FROM {history} WHERE {scope} ORDER BY id DESC LIMIT %(limit)s").format(
+                history=self._names.table("history_messages"), scope=self._SCOPE
+            ),
+            params | {"limit": limit},
+        )
+        rows = await cursor.fetchall()
+        try:
+            return [self._decode(payload) for (payload,) in reversed(rows)]
+        except (ValueError, TypeError, KeyError, AttributeError) as exc:
+            raise PostgresStorageError(
+                "A stored message in this session no longer deserializes; clear the session or repair the row."
+            ) from exc
+
+    _LOCK = sql.SQL(
+        "SELECT pg_advisory_xact_lock(hashtextextended(concat_ws(chr(31), %(schema)s::text, %(prefix)s::text,"
+        " %(app)s::text, %(tenant)s::text, %(agent)s::text, %(source)s::text, %(session)s::text), 0))"
+    )
+
+    def _lock_params(self, params: dict[str, Any]) -> dict[str, Any]:
+        return params | {"schema": self._names.schema, "prefix": self._names.prefix}
+
+    async def save_messages(
+        self,
+        session_id: str | None,
+        messages: Sequence[Message],
+        *,
+        state: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Append the messages not already stored; trim to ``max_messages`` when set.
+
+        Writers of one session take turns on a transaction-scoped advisory lock inside a
+        ``READ COMMITTED`` transaction, so the dedupe read sees every save committed before the
+        lock was granted, whatever the server's default isolation level. Dedupe needs only the
+        newest ``len(messages)`` stored rows: MAF's ``filter_new_messages`` compares a suffix of the
+        stored history with a prefix of the batch, or the whole stored history inside the batch,
+        and both fit in that window.
+        """
+        params = self._params(session_id)
+        if not messages or self.max_messages == 0:
+            return
+        history = self._names.table("history_messages")
+        # Encode before taking a connection, so a value JSONB refuses fails without holding one.
+        encoded = {id(message): encode_jsonb(message.to_dict(), what="History message") for message in messages}
+        async with self._client.connection(read_committed=True) as connection:
+            await connection.execute(self._LOCK, self._lock_params(params))
+            existing = await self._tail(connection, params, len(messages))
+            new_messages = filter_new_messages(existing, messages)
+            if not new_messages:
+                return
+            async with connection.cursor() as cursor:
+                await cursor.executemany(
+                    sql.SQL(
+                        "INSERT INTO {history}"
+                        " (application_id, tenant_id, agent_id, source_id, session_id, message, expires_at)"
+                        " VALUES (%(app)s, %(tenant)s, %(agent)s, %(source)s, %(session)s, %(message)s, {expires})"
+                    ).format(history=history, expires=EXPIRES_AT),
+                    [params | {"message": encoded[id(message)], "ttl": self._ttl()} for message in new_messages],
+                )
+            if self.max_messages is not None:
+                await connection.execute(
+                    sql.SQL(
+                        "DELETE FROM {history} WHERE {scope} AND id NOT IN"
+                        " (SELECT id FROM {history} WHERE {scope} ORDER BY id DESC LIMIT %(keep)s)"
+                    ).format(history=history, scope=self._SCOPE),
+                    params | {"keep": self.max_messages},
+                )
+
+    async def clear(self, session_id: str | None) -> None:
+        """Delete every stored message for the session; takes the session's save lock."""
+        params = self._params(session_id)
+        async with self._client.connection(read_committed=True) as connection:
+            await connection.execute(self._LOCK, self._lock_params(params))
+            await connection.execute(
+                sql.SQL("DELETE FROM {history} WHERE {scope}").format(
+                    history=self._names.table("history_messages"), scope=self._SCOPE
+                ),
+                params,
+            )
+
+    def _scope_params(self) -> dict[str, Any]:
+        return {"app": self.application_id, "tenant": self.tenant_id, "agent": self.agent_id, "source": self.source_id}
+
+    async def list_sessions(self, *, limit: int | None = None, after: str | None = None) -> list[str]:
+        """Session ids with stored history under this provider's scope, sorted; page with ``limit`` and ``after``."""
+        async with self._client.connection(transactional=False) as connection:
+            cursor = await connection.execute(
+                sql.SQL(
+                    "SELECT DISTINCT session_id FROM {history}"
+                    " WHERE application_id = %(app)s AND tenant_id = %(tenant)s AND agent_id = %(agent)s"
+                    " AND source_id = %(source)s AND (%(after)s::text IS NULL OR session_id > %(after)s)"
+                    " ORDER BY session_id LIMIT %(limit)s"
+                ).format(history=self._names.table("history_messages")),
+                self._scope_params() | {"after": after, "limit": limit},
+            )
+            return [row[0] for row in await cursor.fetchall()]
+
+    async def purge(self) -> PurgeReport:
+        """Delete the messages of sessions whose every message has expired, whatever policy stamped them."""
+        history = self._names.table("history_messages")
+        count = await purge_rows(
+            self._client,
+            table=history,
+            where=sql.SQL(
+                "c.tenant_id = %(tenant)s AND c.agent_id = %(agent)s AND c.source_id = %(source)s AND {whole}"
+            ).format(whole=whole_session_expired(history)),
+            params=self._scope_params(),
+            mode="delete",
+            tombstone=None,
+        )
+        return PurgeReport({f"{self._names.prefix}history_messages": count})
+
+
+def whole_session_expired(history: sql.Identifier) -> sql.Composable:
+    """Purge predicate on the candidate row ``c``: no message of its session is still live.
+
+    A session's rows are deleted only when no row of the session is still live; a row written while
+    ``ttl`` was ``None`` has no expiry and keeps its whole session. A conversation that goes on
+    never loses its head, and a tool call never loses its result. Nothing is rewritten on save; the
+    rule is applied at purge time.
+    """
+    return sql.SQL(
+        "c.application_id = %(app)s AND NOT EXISTS (SELECT 1 FROM {history} live"
+        " WHERE live.application_id = c.application_id AND live.tenant_id = c.tenant_id"
+        " AND live.agent_id = c.agent_id AND live.source_id = c.source_id AND live.session_id = c.session_id"
+        " AND (live.expires_at IS NULL OR live.expires_at >= now()))"
+    ).format(history=history)

agent_framework_community_postgres/_json.py

@@ -0,0 +1,34 @@
+"""Encode a JSONB value once, refusing what PostgreSQL would reject, without quoting the value."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from psycopg.types.json import Jsonb
+
+# json.dumps writes U+0000 as the escape \u0000, which JSONB rejects. An even run of backslashes
+# before it (none included) means the escape is real, not the literal text "\u0000" in a string.
+_NUL_ESCAPE = re.compile(r"(?<!\\)(?:\\\\)*\\u0000")
+
+
+def encode_jsonb(value: object, *, what: str) -> Jsonb:
+    """Serialize ``value`` once and wrap the text for psycopg.
+
+    Raises:
+        ValueError: ``value`` holds a NUL character, a lone surrogate, a non-finite float, a circular
+            reference or something ``json`` cannot encode. The message names ``what`` and never the value.
+    """
+    try:
+        text = json.dumps(value, allow_nan=False, ensure_ascii=False)
+        # A lone surrogate survives json.dumps but not psycopg's UTF-8 encoding; fail here, before any SQL.
+        text.encode("utf-8")
+    except UnicodeEncodeError:
+        raise ValueError(
+            f"{what} contains a lone surrogate, which is not valid UTF-8 and PostgreSQL cannot store."
+        ) from None
+    except (ValueError, TypeError, RecursionError) as exc:
+        raise ValueError(f"{what} is not JSON-serializable ({type(exc).__name__}).") from None
+    if _NUL_ESCAPE.search(text):
+        raise ValueError(f"{what} contains a NUL character, which PostgreSQL JSONB cannot store.")
+    return Jsonb(value, dumps=lambda _obj: text)

agent_framework_community_postgres/_leases.py

@@ -0,0 +1,196 @@
+"""Short, renewable, owner-tagged leases: the one coordination primitive this package offers."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from collections.abc import AsyncGenerator, Mapping
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import Any
+
+from agent_framework import SecretString
+from psycopg import sql
+
+from ._client import ClientHandle, LeaseLost, LeaseUnavailable, PostgresClient, require_text
+from ._entra import EntraCredential
+from ._retention import PurgeReport, RetentionPolicy, purge_rows
+from ._store import BaseStore
+
+logger = logging.getLogger(__name__)
+
+_FIRST_DELAY = 0.1
+_MAX_DELAY = 2.0
+_RELEASE_SECONDS = 5.0
+# Releases still running after their bound; the event loop keeps only weak references to tasks.
+_late_releases: set[asyncio.Task[None]] = set()
+
+
+async def _release_after_failure(lease: Lease) -> None:
+    """Release after a block raised, logging a failure here so the task never ends with an exception.
+
+    A shielded task that fails after its waiter gave up is otherwise logged by asyncio itself, with the
+    traceback, whatever its done callbacks retrieve.
+    """
+    try:
+        await lease.release()
+    except Exception:
+        logger.warning("Could not release a lease after its block raised; it frees itself on expiry.")
+
+
+class Lease:
+    """A lease the caller holds; ``renew`` extends it, ``release`` gives it up.
+
+    ``token`` is new on every acquisition, so two holders with the same ``owner`` never
+    renew or release each other's lease.
+    """
+
+    def __init__(self, store: PostgresLeases, resource: str, owner: str, ttl: timedelta, token: str) -> None:
+        self._store = store
+        self.resource = resource
+        self.owner = owner
+        self.ttl = ttl
+        self.token = token
+
+    async def renew(self) -> None:
+        """Extend the lease by ``ttl`` from now; raise ``LeaseLost`` if it expired or changed hands."""
+        await self._store._renew(self)  # pyright: ignore[reportPrivateUsage]
+
+    async def release(self) -> None:
+        """Give the lease up. Releasing a lease that is no longer ours does nothing."""
+        await self._store._release(self)  # pyright: ignore[reportPrivateUsage]
+
+
+class PostgresLeases(BaseStore):
+    """Leases keyed by ``(application_id, resource)``, judged by the database clock.
+
+    Acquisition is one upsert that succeeds only when the row is absent or expired, so
+    there is one holder per acquisition, whatever ``owner`` says; a holder that crashed
+    is recovered when its lease expires. No advisory locks are used, so a connection is
+    never pinned while the caller does slow work.
+    """
+
+    def __init__(
+        self,
+        *,
+        application_id: str,
+        connection_string: str | SecretString | None = None,
+        client: PostgresClient | ClientHandle | None = None,
+        credential: EntraCredential | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        schema: str = "public",
+        table_prefix: str = "af_",
+        pool_kwargs: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            application_id=application_id,
+            connection_string=connection_string,
+            client=client,
+            credential=credential,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+            schema=schema,
+            table_prefix=table_prefix,
+            retention=RetentionPolicy(),
+            pool_kwargs=pool_kwargs,
+        )
+
+    async def try_acquire(self, resource: str, *, owner: str, ttl: timedelta) -> Lease | None:
+        """Take the lease if it is free or expired; ``None`` while anyone, this owner included, holds it."""
+        require_text(resource, "resource")
+        require_text(owner, "owner")
+        if ttl <= timedelta(0):
+            raise ValueError("ttl must be positive.")
+        token = uuid.uuid4().hex
+        async with self._client.connection(read_committed=True) as connection:
+            cursor = await connection.execute(
+                sql.SQL(
+                    "INSERT INTO {leases} (application_id, resource, owner, token, expires_at)"
+                    " VALUES (%(app)s, %(resource)s, %(owner)s, %(token)s, now() + %(ttl)s)"
+                    " ON CONFLICT (application_id, resource) DO UPDATE"
+                    " SET owner = EXCLUDED.owner, token = EXCLUDED.token, expires_at = EXCLUDED.expires_at"
+                    " WHERE {leases}.expires_at < now()"
+                    " RETURNING token"
+                ).format(leases=self._names.table("leases")),
+                {"app": self.application_id, "resource": resource, "owner": owner, "token": token, "ttl": ttl},
+            )
+            row = await cursor.fetchone()
+        return Lease(self, resource, owner, ttl, token) if row is not None else None
+
+    @asynccontextmanager
+    async def acquire(
+        self, resource: str, *, owner: str, ttl: timedelta, wait: timedelta = timedelta(0)
+    ) -> AsyncGenerator[Lease]:
+        """Hold the lease for the block, waiting up to ``wait`` for it to free up; release on exit.
+
+        If the block raises and the release then fails, the release failure is logged and the
+        block's exception propagates. If the block succeeded, a release failure propagates.
+        """
+        deadline = time.monotonic() + wait.total_seconds()
+        delay = _FIRST_DELAY
+        while True:
+            lease = await self.try_acquire(resource, owner=owner, ttl=ttl)
+            if lease is not None:
+                break
+            if time.monotonic() >= deadline:
+                raise LeaseUnavailable("The lease is held by another acquisition.", resource=resource)
+            await asyncio.sleep(min(delay, max(0.0, deadline - time.monotonic())))
+            delay = min(delay * 2, _MAX_DELAY)
+        try:
+            yield lease
+        except BaseException:
+            # The block may have been cancelled; the release still runs, shielded and bounded, so a slow
+            # database cannot hold a cancelling task. An unreleased lease frees itself on expiry.
+            release = asyncio.ensure_future(_release_after_failure(lease))
+            _late_releases.add(release)
+            release.add_done_callback(_late_releases.discard)
+            try:
+                await asyncio.wait_for(asyncio.shield(release), timeout=_RELEASE_SECONDS)
+            except TimeoutError:
+                logger.warning(
+                    "A lease release did not finish in time after its block raised; it continues in the background."
+                )
+            raise
+        await lease.release()
+
+    async def purge(self) -> PurgeReport:
+        """Delete leases whose expiry has passed; an expired lease is already free, so nothing changes hands."""
+        count = await purge_rows(
+            self._client,
+            table=self._names.table("leases"),
+            where=sql.SQL("application_id = %(app)s"),
+            params={"app": self.application_id},
+            mode="delete",
+            tombstone=None,
+        )
+        return PurgeReport({f"{self._names.prefix}leases": count})
+
+    def _lease_params(self, lease: Lease) -> dict[str, object]:
+        return {"app": self.application_id, "resource": lease.resource, "owner": lease.owner, "token": lease.token}
+
+    async def _renew(self, lease: Lease) -> None:
+        async with self._client.connection(read_committed=True) as connection:
+            cursor = await connection.execute(
+                sql.SQL(
+                    "UPDATE {leases} SET expires_at = now() + %(ttl)s"
+                    " WHERE application_id = %(app)s AND resource = %(resource)s AND owner = %(owner)s"
+                    " AND token = %(token)s AND expires_at >= now() RETURNING owner"
+                ).format(leases=self._names.table("leases")),
+                self._lease_params(lease) | {"ttl": lease.ttl},
+            )
+            if await cursor.fetchone() is None:
+                raise LeaseLost("The lease expired or was taken over.", resource=lease.resource)
+
+    async def _release(self, lease: Lease) -> None:
+        async with self._client.connection(read_committed=True) as connection:
+            await connection.execute(
+                sql.SQL(
+                    "DELETE FROM {leases}"
+                    " WHERE application_id = %(app)s AND resource = %(resource)s AND owner = %(owner)s"
+                    " AND token = %(token)s"
+                ).format(leases=self._names.table("leases")),
+                self._lease_params(lease),
+            )