pgdevkit 0.15.2__tar.gz → 0.16.1__tar.gz

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.15.2
+Version: 0.16.1
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -442,7 +442,7 @@ Install with the `db` extra: `pip install pgdevkit[db]`.
   with `set_default_pool()` (a `ConnectionSource` such as `PgPool`, or a plain callable returning an
   async connection context manager). Set the `cancel` `asyncio.Event` to abort the query on the server
   (`QueryCanceled`; to stream a result as JSON from FastAPI see `PostgresJsonResponse`, which watches for the
-  disconnect itself); cancelling the awaiting task cancels it there too, and
+  disconnect itself, and for buffered endpoints see `CancelOnDisconnectRoute`); cancelling the awaiting task cancels it there too, and
   `CancelledError` propagates as usual. `statement_timeout=<seconds>` lets Postgres abort the query after that
   long (`QueryCanceled`, "canceling statement due to statement timeout"); it is applied per call with `SET LOCAL`
   semantics, so it never outlives the call (a borrowed `con` gets its previous setting back); see
@@ -536,14 +536,16 @@ async with pool.connection() as con:
     await pg_upsert(con, Widget(id=1, name="thing"), Widget)
 ```
 
-## `pgdevkit.fastapi` — streaming JSON responses
+## `pgdevkit.fastapi` — streaming JSON responses and cancel-on-disconnect
 
 Requires the `fastapi` extra (`pip install pgdevkit[fastapi]`, FastAPI >= 0.118).
 
 `PostgresJsonResponse` runs a query and streams its rows to the client as a JSON array. Postgres builds the JSON
 (`row_to_json`), so there is no row-by-row Python serialization and no pydantic round trip, and memory use stays flat
 for big results. **If the client goes away, the query is cancelled in Postgres** instead of running to completion.
-(`fetch_all(..., cancel=event)` cancels a buffered query too, but you wire the event to the disconnect yourself.)
+(`fetch_all(..., cancel=event)` cancels a buffered query too; for `fetch_all`-based endpoints put the route on
+`CancelOnDisconnectRoute` ([below](#cancelling-other-endpoints-when-the-client-leaves)) instead of wiring the event
+yourself.)
 
 ```python
 from pgdevkit.db import PgPool, set_default_pool
@@ -596,6 +598,49 @@ big results, can use up the pool and make every other request wait for a connect
 reverse proxy and size the pool accordingly. Disconnect behaviour can only be tested over a real socket
 (`httpx.ASGITransport` never sends `http.disconnect`); see `tests/test_pg_json_granian.py`.
 
+### Cancelling other endpoints when the client leaves
+
+`PostgresJsonResponse` is the only thing that notices a disconnect by itself. ASGI servers such as Granian do **not**
+cancel a request handler when the client goes away, so a handler built on `fetch_all` (or a raw cursor, Meilisearch,
+...) runs to the end and its result is thrown away, which defeats a frontend `AbortController`. Put such read
+endpoints on a router with `CancelOnDisconnectRoute`: it runs the handler as a task and cancels it on
+`http.disconnect` (in the request's own task, with an `asyncio.timeout` as the cancel scope, as
+`PostgresJsonResponse` does), and psycopg/pgdevkit then cancel the running statement on the server (see `fetch_all`'s
+`cancel`).
+
+```python
+from fastapi import APIRouter
+from pgdevkit.db import fetch_all
+from pgdevkit.fastapi import CancelOnDisconnectRoute
+
+cancellable = APIRouter(route_class=CancelOnDisconnectRoute)  # or router.add_api_route(..., route_class_override=...)
+
+@cancellable.post("/customers/overview")  # a POST that only reads
+async def overview(payload: Filter) -> list[Row]:
+    return await fetch_all("select ...", {"q": payload.q})  # aborted in Postgres when the client leaves
+
+app.include_router(cancellable)
+```
+
+- **Opt-in, reads only.** A cancelled write is rolled back at best and half-applied at worst. Don't select routes by
+  HTTP method: search and grid endpoints are often POSTs.
+- **Everything inside the route is cancelled**, dependencies included (authentication, audit logging, counters), and
+  the client gets no response, so `BackgroundTasks` registered by the handler never run. Don't rely on side effects
+  that must always happen in an opted-in route: shield them or do them in a middleware. A `Depends` with `yield` sees
+  an `HTTPException` (status 499) after the cancellation, so a transaction rolls back instead of committing.
+- The client that left gets a 499 nobody reads; the middleware stack sees a normal response (no
+  `No response returned`).
+- The request body is **not** buffered: the handler reads it from a `Request` whose `receive()` is fed by a reader
+  task that also spots the disconnect. That reader runs at most a few chunks ahead of the handler, so a route that
+  never reads a large body can't pin it in memory, but a disconnect is then only noticed once the body is consumed.
+- **Shared work must survive one caller's cancellation.** Await shared tasks and futures (single-flight caches,
+  "refresh once, many wait" loaders) through `asyncio.shield`; otherwise one aborted request cancels the load every
+  other request is waiting on.
+- A returned `StreamingResponse` is not covered (Starlette watches for the disconnect there only on servers with ASGI
+  spec < 2.4; `PostgresJsonResponse` always does). Threads (`asyncio.to_thread`) and
+  external services (Databricks statements, HTTP calls) keep running; only the awaiting stops.
+- Like the above, disconnects only show up over a real socket: see `tests/test_pg_json_granian.py` for a Granian test.
+
 ### Statement timeout
 
 `statement_timeout=<seconds>` (optional, also on `fetch_all`) lets **Postgres** abort the query after that long. It

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/README.md

@@ -417,7 +417,7 @@ Install with the `db` extra: `pip install pgdevkit[db]`.
   with `set_default_pool()` (a `ConnectionSource` such as `PgPool`, or a plain callable returning an
   async connection context manager). Set the `cancel` `asyncio.Event` to abort the query on the server
   (`QueryCanceled`; to stream a result as JSON from FastAPI see `PostgresJsonResponse`, which watches for the
-  disconnect itself); cancelling the awaiting task cancels it there too, and
+  disconnect itself, and for buffered endpoints see `CancelOnDisconnectRoute`); cancelling the awaiting task cancels it there too, and
   `CancelledError` propagates as usual. `statement_timeout=<seconds>` lets Postgres abort the query after that
   long (`QueryCanceled`, "canceling statement due to statement timeout"); it is applied per call with `SET LOCAL`
   semantics, so it never outlives the call (a borrowed `con` gets its previous setting back); see
@@ -511,14 +511,16 @@ async with pool.connection() as con:
     await pg_upsert(con, Widget(id=1, name="thing"), Widget)
 ```
 
-## `pgdevkit.fastapi` — streaming JSON responses
+## `pgdevkit.fastapi` — streaming JSON responses and cancel-on-disconnect
 
 Requires the `fastapi` extra (`pip install pgdevkit[fastapi]`, FastAPI >= 0.118).
 
 `PostgresJsonResponse` runs a query and streams its rows to the client as a JSON array. Postgres builds the JSON
 (`row_to_json`), so there is no row-by-row Python serialization and no pydantic round trip, and memory use stays flat
 for big results. **If the client goes away, the query is cancelled in Postgres** instead of running to completion.
-(`fetch_all(..., cancel=event)` cancels a buffered query too, but you wire the event to the disconnect yourself.)
+(`fetch_all(..., cancel=event)` cancels a buffered query too; for `fetch_all`-based endpoints put the route on
+`CancelOnDisconnectRoute` ([below](#cancelling-other-endpoints-when-the-client-leaves)) instead of wiring the event
+yourself.)
 
 ```python
 from pgdevkit.db import PgPool, set_default_pool
@@ -571,6 +573,49 @@ big results, can use up the pool and make every other request wait for a connect
 reverse proxy and size the pool accordingly. Disconnect behaviour can only be tested over a real socket
 (`httpx.ASGITransport` never sends `http.disconnect`); see `tests/test_pg_json_granian.py`.
 
+### Cancelling other endpoints when the client leaves
+
+`PostgresJsonResponse` is the only thing that notices a disconnect by itself. ASGI servers such as Granian do **not**
+cancel a request handler when the client goes away, so a handler built on `fetch_all` (or a raw cursor, Meilisearch,
+...) runs to the end and its result is thrown away, which defeats a frontend `AbortController`. Put such read
+endpoints on a router with `CancelOnDisconnectRoute`: it runs the handler as a task and cancels it on
+`http.disconnect` (in the request's own task, with an `asyncio.timeout` as the cancel scope, as
+`PostgresJsonResponse` does), and psycopg/pgdevkit then cancel the running statement on the server (see `fetch_all`'s
+`cancel`).
+
+```python
+from fastapi import APIRouter
+from pgdevkit.db import fetch_all
+from pgdevkit.fastapi import CancelOnDisconnectRoute
+
+cancellable = APIRouter(route_class=CancelOnDisconnectRoute)  # or router.add_api_route(..., route_class_override=...)
+
+@cancellable.post("/customers/overview")  # a POST that only reads
+async def overview(payload: Filter) -> list[Row]:
+    return await fetch_all("select ...", {"q": payload.q})  # aborted in Postgres when the client leaves
+
+app.include_router(cancellable)
+```
+
+- **Opt-in, reads only.** A cancelled write is rolled back at best and half-applied at worst. Don't select routes by
+  HTTP method: search and grid endpoints are often POSTs.
+- **Everything inside the route is cancelled**, dependencies included (authentication, audit logging, counters), and
+  the client gets no response, so `BackgroundTasks` registered by the handler never run. Don't rely on side effects
+  that must always happen in an opted-in route: shield them or do them in a middleware. A `Depends` with `yield` sees
+  an `HTTPException` (status 499) after the cancellation, so a transaction rolls back instead of committing.
+- The client that left gets a 499 nobody reads; the middleware stack sees a normal response (no
+  `No response returned`).
+- The request body is **not** buffered: the handler reads it from a `Request` whose `receive()` is fed by a reader
+  task that also spots the disconnect. That reader runs at most a few chunks ahead of the handler, so a route that
+  never reads a large body can't pin it in memory, but a disconnect is then only noticed once the body is consumed.
+- **Shared work must survive one caller's cancellation.** Await shared tasks and futures (single-flight caches,
+  "refresh once, many wait" loaders) through `asyncio.shield`; otherwise one aborted request cancels the load every
+  other request is waiting on.
+- A returned `StreamingResponse` is not covered (Starlette watches for the disconnect there only on servers with ASGI
+  spec < 2.4; `PostgresJsonResponse` always does). Threads (`asyncio.to_thread`) and
+  external services (Databricks statements, HTTP calls) keep running; only the awaiting stops.
+- Like the above, disconnects only show up over a real socket: see `tests/test_pg_json_granian.py` for a Granian test.
+
 ### Statement timeout
 
 `statement_timeout=<seconds>` (optional, also on `fetch_all`) lets **Postgres** abort the query after that long. It

pgdevkit-0.16.1/pgdevkit/fastapi/__init__.py

@@ -0,0 +1,4 @@
+from .cancel_on_disconnect import CancelOnDisconnectRoute
+from .json_response import PostgresJsonResponse
+
+__all__ = ["CancelOnDisconnectRoute", "PostgresJsonResponse"]

pgdevkit-0.16.1/pgdevkit/fastapi/cancel_on_disconnect.py

@@ -0,0 +1,136 @@
+"""Cancel a FastAPI handler when its client goes away, so the database work it started stops too.
+
+Requires the ``fastapi`` extra: ``pip install pgdevkit[fastapi]``.
+
+ASGI servers such as Granian do not cancel a request handler when the client disconnects: the handler runs to the
+end and its result is thrown away. ``PostgresJsonResponse`` watches for the disconnect itself, but ``fetch_all`` and
+friends (or any other awaitable work, raw psycopg cursors included) only stop when the awaiting task is cancelled.
+``CancelOnDisconnectRoute`` closes that gap: it runs the route handler as a task and cancels it on
+``http.disconnect``; psycopg and pgdevkit then cancel the running statement on the server.
+"""
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from fastapi import HTTPException, Request, Response
+from fastapi.routing import APIRoute
+from starlette.requests import ClientDisconnect
+from starlette.types import Message, Receive
+
+from .json_response import CLIENT_CLOSED_REQUEST
+
+logger = logging.getLogger(__name__)
+
+# Body chunks read ahead of the handler: enough to never stall it, too few to buffer an upload in memory.
+_MAX_PENDING_MESSAGES = 8
+
+
+class CancelOnDisconnectRoute(APIRoute):
+    """An ``APIRoute`` that cancels its handler as soon as the client disconnects.
+
+    Opt in per router, never for the whole app, and only for routes that are safe to abort halfway: reads, searches,
+    exports. A cancelled write is rolled back at best and half-applied at worst::
+
+        cancellable = APIRouter(route_class=CancelOnDisconnectRoute)
+
+        @cancellable.post("/customers/overview")  # a POST that only reads
+        async def overview(payload: Filter) -> Page:
+            return await fetch_all(...)  # aborted in Postgres when the client leaves
+
+        app.include_router(cancellable)
+
+    A single route can opt in with ``router.add_api_route(..., route_class_override=CancelOnDisconnectRoute)``
+    (``APIRouter`` only; the ``@router.get`` decorators don't take it).
+
+    Things to know:
+
+    * **Everything inside the route is cancelled**, dependencies included (authentication, audit logging, counters)
+      and so is ``BackgroundTasks`` registration, since the client gets no response. Don't rely on side effects that
+      must always happen; shield them or do them in a middleware. A ``Depends`` with ``yield`` sees the 499
+      ``HTTPException`` after the cancellation, so its cleanup rolls back instead of committing.
+    * The request body is not buffered: the handler reads it as usual, from a ``Request`` whose ``receive()`` is fed
+      by a reader task that also spots the disconnect. While the handler isn't reading a large body, the reader
+      stops after a few chunks, so a disconnect is only noticed once the handler has consumed the body.
+    * Work shared with other requests must survive the cancellation of one of them: await shared tasks and futures
+      through ``asyncio.shield`` (cache single-flight loaders, background refreshes), otherwise one aborted request
+      cancels the load every other request is waiting on.
+    * A returned ``StreamingResponse`` is not covered (the handler has finished by the time it is sent): Starlette
+      watches for the disconnect there only on servers with ASGI spec < 2.4, ``PostgresJsonResponse`` always does.
+    * Threads (``asyncio.to_thread``) and external services (Databricks statements, HTTP calls) keep running after
+      the cancellation; only awaiting them stops.
+    """
+
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        handler = super().get_route_handler()
+
+        async def cancel_on_disconnect(request: Request) -> Response:
+            # The handler runs in the request's own task, as without this route (context variables, dependencies with
+            # `yield`, an outer `asyncio.timeout` all behave as usual); an asyncio timeout is the cancel scope, as in
+            # PostgresJsonResponse. The disconnect pulls its deadline to "now".
+            loop = asyncio.get_running_loop()
+            receiver = _Receiver(request.receive)
+            request._receive = receiver.receive  # the same Request object, so a cached body is seen by everyone
+            reader = asyncio.create_task(receiver.read())
+
+            handled = False  # as in PostgresJsonResponse: once set, the cancel scope may be gone
+
+            async def cancel_when_gone(cancel_scope: asyncio.Timeout) -> None:
+                await receiver.disconnected.wait()
+                if not handled:  # (the Event can't swallow the cancellation; this keeps reschedule() safe anyway)
+                    cancel_scope.reschedule(loop.time())
+
+            try:
+                async with asyncio.timeout(None) as cancel_scope:
+                    watcher = asyncio.create_task(cancel_when_gone(cancel_scope))
+                    try:
+                        return await handler(request)
+                    finally:
+                        handled = True
+                        watcher.cancel()
+            except TimeoutError:
+                if not cancel_scope.expired():  # the handler's own timeout
+                    raise
+            except ClientDisconnect:  # it was reading the body when the client left
+                pass
+            finally:
+                reader.cancel()
+            logger.debug("client disconnected, cancelled %s %s", request.method, request.url.path)
+            # Raised, not returned: the dependencies' exit code (e.g. a transaction) must see a failure, not a success.
+            raise HTTPException(status_code=CLIENT_CLOSED_REQUEST, detail="Client closed the request")
+
+        return cancel_on_disconnect
+
+
+class _Receiver:
+    """Gives the handler's ``Request`` its own ``receive()`` while one reader task watches for the disconnect."""
+
+    def __init__(self, receive: Receive) -> None:
+        self._receive = receive
+        self._messages: asyncio.Queue[Message | Exception] = asyncio.Queue(maxsize=_MAX_PENDING_MESSAGES)
+        self._gone: Message | None = None
+        self.disconnected = asyncio.Event()
+
+    async def read(self) -> None:
+        """Pump the server's messages into the queue until the client is gone (the queue's limit is the back-pressure)."""
+        try:
+            while True:
+                message = await self._receive()
+                if message["type"] == "http.disconnect":
+                    self.disconnected.set()
+                await self._messages.put(message)
+                if message["type"] == "http.disconnect":
+                    return
+        except Exception as exc:  # noqa: BLE001 - a broken server: the handler sees it, the client is not treated as gone
+            await self._messages.put(exc)
+
+    async def receive(self) -> Message:
+        if self._gone is not None:  # the disconnect is final, whoever asks again
+            return self._gone
+        message = await self._messages.get()
+        if isinstance(message, Exception):
+            raise message
+        if message["type"] == "http.disconnect":
+            self._gone = message
+        return message

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/pgdevkit/fastapi/json_response.py

@@ -4,10 +4,11 @@ Requires the ``fastapi`` extra: ``pip install pgdevkit[fastapi]``.
 """
 
 import asyncio
+import contextlib
 import json
 import logging
-from contextlib import aclosing
 from collections.abc import AsyncGenerator, Mapping
+from contextlib import aclosing
 from string.templatelib import Template
 from typing import Any, cast
 
@@ -34,6 +35,8 @@ from ..db.fetch import (
 
 logger = logging.getLogger(__name__)
 
+CLIENT_CLOSED_REQUEST = 499  # nginx's code for a client that left; nobody reads it
+
 _CANCEL_TIMEOUT_SECONDS = 5.0
 # libpq < 17 (a system libpq; psycopg's binary wheels bundle a newer one) has no chunked rows mode.
 _CHUNKED_ROWS = pq.version() >= 170000
@@ -109,23 +112,41 @@ class PostgresJsonResponse(StreamingResponse):
         # Starlette only watches for http.disconnect on ASGI spec < 2.4, so do it ourselves. An asyncio timeout is
         # the cancel scope: unlike an anyio task group, it doesn't leave Granian hanging when the body fails.
         loop = asyncio.get_running_loop()
+        streamed = False  # set before the watcher is cancelled: from then on the cancel scope may be gone
 
         async def watch_for_disconnect(cancel_scope: asyncio.Timeout) -> None:
-            while (await receive())["type"] != "http.disconnect":
+            # Checked again after every receive(): a wrapped receive() can swallow the watcher's cancellation and
+            # return instead (BaseHTTPMiddleware's turns it into an http.disconnect once the response has been sent),
+            # and reschedule() raises once the scope has been exited.
+            while not streamed and (await receive())["type"] != "http.disconnect":
                 pass
-            cancel_scope.reschedule(loop.time())  # i.e. cancel the stream now
+            if not streamed:
+                cancel_scope.reschedule(loop.time())  # i.e. cancel the stream now
+
+        started = False
+
+        async def tracking_send(message: Message) -> None:
+            nonlocal started
+            started = started or message["type"] == "http.response.start"
+            await send(message)
 
         try:
             async with asyncio.timeout(None) as cancel_scope:
                 watcher = asyncio.create_task(watch_for_disconnect(cancel_scope))
                 try:
-                    await self.stream_response(send)
+                    await self.stream_response(tracking_send)
                 finally:
+                    streamed = True
                     watcher.cancel()
         except TimeoutError:
             if not cancel_scope.expired():
                 raise
-            # the client is gone and the query has been cancelled: nobody is left to answer
+            # The client is gone and the query has been cancelled: nobody is left to answer. A middleware in front
+            # (BaseHTTPMiddleware) still expects a response, though, or it fails with "No response returned.".
+            if not started:
+                with contextlib.suppress(OSError, ClientDisconnect):
+                    await send(self._start_message(CLIENT_CLOSED_REQUEST, []))
+                    await send({"type": "http.response.body", "body": b"", "more_body": False})
         if self.background is not None:
             await self.background()
 

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/pyproject.toml

@@ -11,7 +11,7 @@ packages = ["pgdevkit"]
 
 [project]
 name = "pgdevkit"
-version = "0.15.2"
+version = "0.16.1"
 description = "A helper for developing with Postgres"
 readme = "README.md"
 requires-python = ">=3.14"

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/skills/pgdevkit/SKILL.md

@@ -6,7 +6,8 @@ description: >
   Docker/Podman test database (`pgdb testdb`), importable ORM-free CRUD and
   query helpers (`pgdevkit.db`: `pg_*`, `fetch_all`/`fetch_one`/`fetch_scalar`/`execute`, `readonly_transaction`, `PgPool`, `SqlLoader`), streaming a query as JSON from a
   FastAPI endpoint with query cancellation on client disconnect (`pgdevkit.fastapi.PostgresJsonResponse`: large grid
-  endpoints), and the `database/`-folder schema-as-code convention. Supersedes the old postgres-test-setup, postgres-best-practices,
+  endpoints; `pgdevkit.fastapi.CancelOnDisconnectRoute`: cancel plain `fetch_all`/cursor read handlers when the client
+  aborts, e.g. a frontend AbortController), and the `database/`-folder schema-as-code convention. Supersedes the old postgres-test-setup, postgres-best-practices,
   and database-in-source skills — pgdevkit is a real dependency now, not
   copy-pasted reference files. Use whenever the user wants to set up a local
   test Postgres, write or review psycopg code, add a table/view/function to
@@ -233,7 +234,7 @@ deleted = await execute("DELETE FROM sessions WHERE user_id = %(id)s", {"id": 1}
 - `model=` validates each row into a Pydantic model; `row_mapper=` maps each dict row to anything else (exclusive with `model`).
 - Passing `con=` runs on *your* connection: `fetch_all` never commits, closes or releases it. Without it, a connection is borrowed from `pool=` (or the `set_default_pool()` pool) and released afterwards.
 - `statement_timeout=<seconds>` (optional) lets Postgres abort the query after that long, raising `QueryCanceled`; it is applied with `SET LOCAL` semantics for this call only (a borrowed `con` gets its previous value back). A plain value *replaces* the connection's own setting in both directions, so a per-call 900 s overrides a database-level safety net of 600 s; `statement_timeout=at_most(120)` (`from pgdevkit.db import at_most`) never loosens it: the effective timeout is `min(current, 120)`.
-- `cancel=` takes an `asyncio.Event`: set it (e.g. when the HTTP client disconnects) and the running query is cancelled on the server, raising `psycopg.errors.QueryCanceled`. If the awaiting task is cancelled instead, the server-side query is cancelled too and `CancelledError` propagates as usual (not `QueryCanceled`), so no query keeps running unattended. Don't use `cancel=` on a `con` that concurrent tasks share (it aborts whatever statement is running on it); if the cancel request itself can't be delivered, the connection is closed. After `QueryCanceled` a borrowed `con` is usable again once you `await con.rollback()` (autocommit connections need nothing). To stream a whole result as JSON from FastAPI (it wires the disconnect itself) see `PostgresJsonResponse` below.
+- `cancel=` takes an `asyncio.Event`: set it (e.g. when the HTTP client disconnects) and the running query is cancelled on the server, raising `psycopg.errors.QueryCanceled`. If the awaiting task is cancelled instead, the server-side query is cancelled too and `CancelledError` propagates as usual (not `QueryCanceled`), so no query keeps running unattended. Don't use `cancel=` on a `con` that concurrent tasks share (it aborts whatever statement is running on it); if the cancel request itself can't be delivered, the connection is closed. After `QueryCanceled` a borrowed `con` is usable again once you `await con.rollback()` (autocommit connections need nothing). To stream a whole result as JSON from FastAPI (it wires the disconnect itself) see `PostgresJsonResponse` below; to cancel a plain `fetch_all` endpoint when the client leaves, see `CancelOnDisconnectRoute` below.
 - `query` is typed `SqlQuery`: a literal string (`SqlLoader.load_sql()`), a sqlglot expression (any `exp.Expr`, so Select, Union, Subquery and other `exp.Query` values are fine), a `psycopg.sql` composable or a t-string. A plain `str` fails type checking on purpose, so don't build SQL with f-strings/concatenation. A sqlglot expression is only as safe as the strings it was built from (its builders parse plain strings as SQL): pass user values as `exp.Placeholder` + `params`, never as literals/raw text. A literal `%` in a sqlglot expression (`LIKE 'a%'`, modulo) just works, with or without `params`; in a plain string or `psycopg.sql` composable it is psycopg's rule: write `%%` when you pass `params`. A t-string carries its own values, so don't also pass `params`.
 
 ### Dynamic SQL
@@ -326,6 +327,29 @@ async def articles(lng: str) -> PostgresJsonResponse:
 - `statement_timeout=<seconds>` (optional, as in `fetch_all`): Postgres aborts a slow query; before the first byte the client gets a 504. It does not free a client that stopped reading (use a proxy write timeout), and needs a non-autocommit connection.
 - It does no authorization; scope the query yourself. Full reference: the `pgdevkit.fastapi` section of the README.
 
+### Cancelling `fetch_all` endpoints when the client leaves
+
+Granian does not cancel a request handler on disconnect, so a frontend abort (debounced search, grid filter change) only stops `PostgresJsonResponse` endpoints. Put other read endpoints — including POSTs that only read, e.g. grid/search — on a router with `CancelOnDisconnectRoute`: the handler task is cancelled on `http.disconnect` and psycopg cancels the statement in Postgres.
+
+```python
+from fastapi import APIRouter
+from pgdevkit.fastapi import CancelOnDisconnectRoute
+
+cancellable = APIRouter(route_class=CancelOnDisconnectRoute)  # single route: router.add_api_route(..., route_class_override=CancelOnDisconnectRoute)
+
+@cancellable.post("/customers/overview")  # reads only
+async def overview(payload: Filter) -> list[Row]:
+    return await fetch_all(sql.load_sql("customers", "overview"), payload.model_dump())
+
+app.include_router(cancellable)
+```
+
+- **Reads only, opt-in.** Never for writes; don't select by HTTP method (searches are POSTs).
+- **Everything in the route is cancelled**, dependencies included (auth, audit logging), and `BackgroundTasks` never run; a `yield` dependency sees an `HTTPException` (499) and rolls back. Don't put must-happen side effects in such a route.
+- The client that left gets a 499 nobody reads. The body is not buffered (the handler gets a `Request` fed by a reader task).
+- Shared work (single-flight caches, "refresh once, many wait" loaders) must be awaited through `asyncio.shield`, or one aborted request cancels it for all waiters.
+- `to_thread` work and external services (Databricks statements, HTTP calls) keep running; only awaiting them stops. Returned `StreamingResponse`s aren't covered (use `PostgresJsonResponse`).
+
 ### SQL formatting
 
 ```bash
@@ -405,6 +429,7 @@ Reports drift between the `database/` `.sql` files and the actual schema — tab
 - [ ] Untrusted SQL runs under a SELECT-only role (plus `readonly_transaction(con)` and an `at_most(...)` timeout as safety nets, not as a sandbox)
 - [ ] `set_default_pool()` at startup; `helper.clear_cache()` after DDL on a long-lived connection when using `complex_helper=`
 - [ ] Large/grid reads from FastAPI may use `pgdevkit.fastapi.PostgresJsonResponse` (streams, cancels on disconnect, no model validation)
+- [ ] Other read endpoints built on `fetch_all` that should stop when the client leaves use `APIRouter(route_class=CancelOnDisconnectRoute)` (never writes)
 - [ ] No `LATERAL JOIN` — use a CTE that groups/aggregates first, then joins it
 - [ ] `.<env>.sql` files (e.g. `.prod.sql`) are skipped by `pgdb testdb` unless it's run with a matching `--env`
 - [ ] Every table (and non-obvious column) has a `COMMENT ON`, placed in the object's own `.sql` file

{pgdevkit-0.15.2 → pgdevkit-0.16.1}/tests/_asgi.py

@@ -1,8 +1,10 @@
 """Drive an ASGI response by hand, with a client that can disconnect at will (httpx's ASGITransport can't)."""
 
 import asyncio
+import contextlib
+import gc
 import time
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable
 
 import psycopg
 
@@ -13,6 +15,7 @@ class FakeClient:
         self.sent: list[dict] = []
         self.fail_sends_after: int | None = None  # simulate ASGI spec >= 2.4: send() raises OSError once gone
         self.disconnect_when_send_fails = False  # ... and http.disconnect arrives at that very moment
+        self.send_iterations = 0  # event loop iterations each send() takes, as a write to a real socket does
 
     async def receive(self) -> dict:
         await self.disconnect.wait()
@@ -24,6 +27,8 @@ class FakeClient:
                 self.disconnect.set()
             raise OSError("client went away")
         self.sent.append(message)
+        for _ in range(self.send_iterations):
+            await asyncio.sleep(0)
 
     async def call(self, app: Callable[..., Awaitable[None]]) -> None:
         await app({"type": "http", "asgi": {"spec_version": "2.3"}}, self.receive, self.send)
@@ -51,3 +56,19 @@ async def wait_until(condition: Callable[[], Awaitable[bool] | bool], *, timeout
             return True
         await asyncio.sleep(0.05)
     return False
+
+
+@contextlib.asynccontextmanager
+async def unhandled_loop_errors() -> AsyncIterator[list[dict]]:
+    """Collect what the event loop would log, e.g. "Task exception was never retrieved" for a failed watcher task."""
+    loop = asyncio.get_running_loop()
+    errors: list[dict] = []
+    previous_handler = loop.get_exception_handler()
+    loop.set_exception_handler(lambda _, context: errors.append(context))
+    try:
+        yield errors
+        for _ in range(5):  # let leftover tasks finish, then have the failed ones reported
+            await asyncio.sleep(0)
+        gc.collect()
+    finally:
+        loop.set_exception_handler(previous_handler)

pgdevkit-0.16.1/tests/_granian_app.py

@@ -0,0 +1,72 @@
+"""The app served by Granian in test_pg_json_granian.py (its DSN comes from the environment)."""
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import APIRouter, FastAPI, Request
+from psycopg_pool import AsyncConnectionPool
+
+from pgdevkit.db import fetch_all
+from pgdevkit.fastapi import CancelOnDisconnectRoute, PostgresJsonResponse
+
+pool = AsyncConnectionPool(os.environ["PGJSON_TEST_DSN"], min_size=1, max_size=2, open=False)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    async with pool:
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.middleware("http")  # a BaseHTTPMiddleware, as in our apps: it must cope with a handler that was cancelled
+async def passthrough(request: Request, call_next):
+    return await call_next(request)
+
+
+cancellable = APIRouter(route_class=CancelOnDisconnectRoute)
+
+
+@cancellable.post("/cancellable-sleep")
+async def cancellable_sleep() -> list[dict]:
+    return await fetch_all("select pg_sleep(30) as slept", pool=pool)
+
+
+@cancellable.post("/cancellable-ok")
+async def cancellable_ok() -> list[dict]:
+    return await fetch_all("select 1 as one", pool=pool)
+
+
+app.include_router(cancellable)
+
+
+@app.post("/plain-sleep")  # not opted in: runs to completion even if the client is gone
+async def plain_sleep() -> list[dict]:
+    return await fetch_all("select pg_sleep(3) as slept", pool=pool)
+
+
+@app.get("/ok")
+async def ok():
+    return PostgresJsonResponse("select i from generate_series(1, 3) i", pool=pool)
+
+
+@app.get("/sleep")
+async def sleep():
+    return PostgresJsonResponse("select pg_sleep(30) as slept", pool=pool)
+
+
+@app.get("/fails-at-once")  # before the first byte: a 500 JSON error
+async def fails_at_once():
+    return PostgresJsonResponse("select 1 / 0 as boom", pool=pool)
+
+
+@app.get("/fails-midway")
+async def fails_midway():
+    return PostgresJsonResponse(
+        "select i, repeat('x', 100) as pad, 1 / (case when i = 1500 then 0 else 1 end) as boom "
+        "from generate_series(1, 2000) i",
+        pool=pool,
+    )