pgdevkit 0.13.0__py3-none-any.whl → 0.14.2__py3-none-any.whl

pgdevkit/db/fetch.py

@@ -2,9 +2,10 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import math
 import re
 from collections.abc import AsyncIterator, Callable, Mapping, Sequence
-from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager, suppress
 from string.templatelib import Template
 from typing import TYPE_CHECKING, Any, LiteralString, Protocol, overload
 
@@ -84,8 +85,37 @@ def _render(query: SqlQuery) -> Any:
     return query.sql(dialect="postgres")
 
 
-async def _run_query(c: AsyncConnection, query: Any, params: QueryParams) -> list[dict[str, Any]]:
-    async with c.cursor(row_factory=dict_row) as cur:
+def _check_statement_timeout(statement_timeout: float | None) -> None:
+    if statement_timeout is not None and statement_timeout <= 0:
+        raise ValueError(f"statement_timeout must be a positive number of seconds, got {statement_timeout}")
+
+
+@asynccontextmanager
+async def _statement_timeout(c: AsyncConnection, seconds: float | None) -> AsyncIterator[None]:
+    """Run the block under Postgres' `statement_timeout`, set with `set_config(..., is_local => true)`: it is
+    scoped to the current transaction (so it can't leak into a pool, and it is safe behind PgBouncer's
+    transaction pooling) and put back afterwards for a borrowed connection that stays in its transaction.
+    `None` leaves the connection's own setting alone."""
+    if seconds is None:
+        yield
+        return
+    async with AsyncExitStack() as stack:
+        if c.autocommit:
+            await stack.enter_async_context(c.transaction())  # a local setting needs a transaction to live in
+        cur = await c.execute(
+            "SELECT current_setting('statement_timeout'), set_config('statement_timeout', %(ms)s, true)",
+            {"ms": str(max(1, math.ceil(seconds * 1000)))},
+        )
+        row = await cur.fetchone()
+        assert row is not None
+        yield
+        await c.execute("SELECT set_config('statement_timeout', %(previous)s, true)", {"previous": row[0]})
+
+
+async def _run_query(
+    c: AsyncConnection, query: Any, params: QueryParams, statement_timeout: float | None
+) -> list[dict[str, Any]]:
+    async with _statement_timeout(c, statement_timeout), c.cursor(row_factory=dict_row) as cur:
         await cur.execute(query, params)
         return await cur.fetchall()
 
@@ -129,11 +159,12 @@ async def _fetch_dicts(
     con: AsyncConnection | None,
     pool: ConnectionSource | None,
     cancel: asyncio.Event | None,
+    statement_timeout: float | None,
 ) -> list[dict[str, Any]]:
     if cancel is not None and cancel.is_set():
         raise QueryCanceled("fetch_all: cancelled before the query started")
     async with _acquire(con, pool) as c:
-        work = asyncio.ensure_future(_run_query(c, query, params))
+        work = asyncio.ensure_future(_run_query(c, query, params, statement_timeout))
         stop = asyncio.ensure_future(cancel.wait()) if cancel is not None else None
         try:
             await asyncio.wait([work, *([stop] if stop else [])], return_when=asyncio.FIRST_COMPLETED)
@@ -162,6 +193,7 @@ async def fetch_all[M: BaseModel](
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[M]: ...
 
 
@@ -174,6 +206,7 @@ async def fetch_all[T](
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[T]: ...
 
 
@@ -187,6 +220,7 @@ async def fetch_all(
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[dict[str, Any]]: ...
 
 
@@ -198,6 +232,7 @@ async def fetch_all[M: BaseModel](
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[M]: ...
 
 
@@ -209,6 +244,7 @@ async def fetch_all[T](
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[T]: ...
 
 
@@ -221,6 +257,7 @@ async def fetch_all(
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[dict[str, Any]]: ...
 
 
@@ -233,17 +270,25 @@ async def fetch_all(
     con: AsyncConnection | None = None,
     pool: ConnectionSource | None = None,
     cancel: asyncio.Event | None = None,
+    statement_timeout: float | None = None,
 ) -> list[Any]:
     """Run one query and return every row.
 
     Rows come back as plain dicts, or, with `model=` (a Pydantic model class), validated into
     that model; `row_mapper=` converts each dict row into any other shape. The two are exclusive.
 
+    Pass `statement_timeout` (seconds) to let Postgres abort the query after that long: `fetch_all` then
+    raises `psycopg.errors.QueryCanceled` ("canceling statement due to statement timeout"). It is applied
+    with `SET LOCAL` semantics, i.e. for this query's transaction only; a borrowed `con` in autocommit mode
+    gets a short transaction around the query, and any other borrowed `con` gets its previous setting back.
+    Without it, the connection's own `statement_timeout` (default: none) applies.
+
     Pass `con` to run on a connection you already hold (e.g. inside a transaction): it is
     borrowed, never committed, closed or returned to a pool. Without it, a connection is taken
     from `pool` or the pool registered via `set_default_pool()` and released afterwards.
 
-    Set `cancel` (an `asyncio.Event`, e.g. when the HTTP client disconnects) to abort a running
+    Set `cancel` (an `asyncio.Event`, e.g. when the HTTP client disconnects; to stream a large result
+    from FastAPI see `pgdevkit.fastapi.PostgresJsonResponse`, which does that wiring itself) to abort a running
     query on the server: `fetch_all` then raises `psycopg.errors.QueryCanceled`. If the awaiting
     task is cancelled instead, the query is cancelled server-side too and `CancelledError`
     propagates, so the query never keeps running unattended. `cancel` aborts whatever statement is
@@ -261,7 +306,8 @@ async def fetch_all(
         raise TypeError("Pass either `model` or `row_mapper`, not both.")
     if isinstance(query, Template) and params is not None:
         raise TypeError("A t-string query carries its own values; don't pass `params` with it.")
-    rows = await _fetch_dicts(_render(query), params, con, pool, cancel)
+    _check_statement_timeout(statement_timeout)
+    rows = await _fetch_dicts(_render(query), params, con, pool, cancel, statement_timeout)
     if model is not None:
         return [model.model_validate(row) for row in rows]
     if row_mapper is not None:

pgdevkit/fastapi/__init__.py

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

pgdevkit/fastapi/json_response.py

@@ -0,0 +1,259 @@
+"""Stream a Postgres query to the client as a JSON array, cancelling the query if the client goes away.
+
+Requires the ``fastapi`` extra: ``pip install pgdevkit[fastapi]``.
+"""
+
+import asyncio
+import json
+import logging
+from contextlib import aclosing
+from collections.abc import AsyncGenerator, Mapping
+from string.templatelib import Template
+from typing import Any, cast
+
+import anyio
+from fastapi.responses import StreamingResponse
+from psycopg import AsyncConnection, pq
+from psycopg.errors import QueryCanceled
+from psycopg.pq import TransactionStatus
+from psycopg.rows import tuple_row
+from psycopg.sql import SQL, Composable, Composed
+from starlette.exceptions import HTTPException
+from starlette.requests import ClientDisconnect
+from starlette.types import Message, Receive, Scope, Send
+
+from ..db.fetch import (
+    ConnectionSource,
+    QueryParams,
+    SqlQuery,
+    _acquire,
+    _check_statement_timeout,
+    _render,
+    _statement_timeout,
+)
+
+logger = logging.getLogger(__name__)
+
+_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
+
+
+class PostgresJsonResponse(StreamingResponse):
+    """Run ``query`` and stream its rows as ``[{...},\\n{...}]`` (``row_to_json`` per row, computed by Postgres).
+
+    Connections work as in ``pgdevkit.db.fetch_all``: pass ``con`` (one you opened; it must stay open until the
+    response has been sent, e.g. a ``Depends`` with ``yield``), or ``pool`` (anything with ``.connection()``), or
+    register the app's pool once with ``set_default_pool()``. A pooled connection is acquired when streaming starts
+    and released when it ends. ``query`` and ``params`` are those of ``fetch_all`` too (a literal string, a
+    ``psycopg.sql`` composable, a sqlglot expression or a t-string) with values bound via ``params``; a t-string carries
+    its own values and takes no ``params``.
+
+    The query is wrapped as a subquery, so it cannot be a data-modifying CTE; for that (or for custom JSON) pass
+    ``query_produces_json=True`` and make it return one *text* column holding the JSON of each row.
+
+    If the client disconnects (or the request is cancelled) while the query is still running, the query is
+    cancelled in Postgres. A connection that was mid-query at that point is closed instead of being reused.
+
+    ``statement_timeout`` (seconds) lets Postgres abort the query after that long, as in ``fetch_all``: before the
+    first byte that is a 504 ``{"error": "Query timed out"}``, later the response is cut short like any other
+    error. It limits query execution only: a client that stops reading is *not* freed by it (Postgres defers the
+    cancel while blocked writing), so keep a write timeout in the reverse proxy. Needs a connection that is not in
+    autocommit mode.
+
+    Errors before the first byte become a JSON ``{"error": ...}`` response (status 500, or the status of a raised
+    ``HTTPException``). After that the status line is gone: the error is logged and re-raised, and the response
+    ends without its closing ``]``, so clients can't mistake it for a complete array. Subclass and set
+    ``expose_errors = True`` (e.g. in dev/test) to include ``str(error)`` in the 500 response.
+
+    Postgres sends rows in 8 kB buffers, so a slow query with small rows delivers its first bytes late.
+    """
+
+    expose_errors: bool = False
+
+    def __init__(
+        self,
+        query: SqlQuery,
+        params: QueryParams = None,
+        *,
+        con: AsyncConnection | None = None,
+        pool: ConnectionSource | None = None,
+        query_produces_json: bool = False,
+        batch_size: int = 1000,
+        statement_timeout: float | None = None,
+        status_code: int = 200,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        if con is not None and pool is not None:
+            raise TypeError("Pass either `con` or `pool`, not both.")
+        if batch_size < 1:
+            raise ValueError(f"batch_size must be >= 1, got {batch_size}")
+        _check_statement_timeout(statement_timeout)
+        if isinstance(query, Template) and params is not None:
+            raise TypeError("A t-string query carries its own values; don't pass `params` with it.")
+        rendered = _render(query)
+        self.query = rendered if query_produces_json else _as_json_rows(rendered)
+        self.params = params
+        self.con = con
+        self.pool = pool
+        self.batch_size = batch_size
+        self.statement_timeout = statement_timeout
+        # The body is produced by stream_response() itself, so the base class' iterator is never used.
+        super().__init__((), status_code=status_code, headers=headers, media_type="application/json")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # 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()
+
+        async def watch_for_disconnect(cancel_scope: asyncio.Timeout) -> None:
+            while (await receive())["type"] != "http.disconnect":
+                pass
+            cancel_scope.reschedule(loop.time())  # i.e. cancel the stream now
+
+        try:
+            async with asyncio.timeout(None) as cancel_scope:
+                watcher = asyncio.create_task(watch_for_disconnect(cancel_scope))
+                try:
+                    await self.stream_response(send)
+                finally:
+                    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
+        if self.background is not None:
+            await self.background()
+
+    async def stream_response(self, send: Send) -> None:
+        started = False
+        try:
+            async with _acquire(self.con, self.pool) as conn:
+                try:
+                    # aclosing: an `async for` leaves its generator suspended when the body fails (e.g. send()
+                    # raising); the event loop would finalize it later, after the connection is closed.
+                    async with aclosing(self._chunks(conn)) as chunks:
+                        async for chunk in chunks:
+                            if not started:
+                                await _send(send, self._start_message(self.status_code, self.raw_headers))
+                                started = True
+                            await _send(send, {"type": "http.response.body", "body": chunk, "more_body": True})
+                finally:
+                    # Runs for completion too, but only acts if the query is still in flight.
+                    await _cancel_if_running(conn)
+        except ClientDisconnect:  # nobody to report to
+            raise
+        except Exception as err:
+            if started:
+                logger.exception("Postgres query failed after the response had started; it is cut short")
+                raise
+            if self.statement_timeout is not None and isinstance(err, QueryCanceled):
+                logger.warning("Postgres query exceeded the statement_timeout of %ss", self.statement_timeout)
+                err = HTTPException(status_code=504, detail="Query timed out")
+            if isinstance(err, HTTPException):
+                logger.info("Request refused: %s", err.detail)
+            else:
+                logger.exception("Error executing Postgres query")
+            await self._send_error(send, err)
+            return
+        if not started:
+            await _send(send, self._start_message(self.status_code, self.raw_headers))
+        await _send(send, {"type": "http.response.body", "body": b"", "more_body": False})
+
+    @staticmethod
+    def _start_message(status: int, headers: list[tuple[bytes, bytes]]) -> Message:
+        return {"type": "http.response.start", "status": status, "headers": headers}
+
+    async def _send_error(self, send: Send, err: Exception) -> None:
+        if isinstance(err, HTTPException):
+            status, message = err.status_code, err.detail
+        else:
+            status, message = 500, str(err) if self.expose_errors else "Internal Server Error"
+        body = json.dumps({"error": message}).encode()
+        headers = [(b"content-type", b"application/json"), (b"content-length", str(len(body)).encode())]
+        if isinstance(err, HTTPException) and err.headers:
+            headers += [(k.lower().encode(), v.encode()) for k, v in err.headers.items()]
+        await _send(send, self._start_message(status, headers))
+        await _send(send, {"type": "http.response.body", "body": body, "more_body": False})
+
+    async def _chunks(self, conn: AsyncConnection) -> AsyncGenerator[bytes]:
+        """Yield the JSON array in pieces of ``batch_size`` rows. Nothing is yielded before the first batch is
+        complete, so a failing query surfaces before any byte (and the status line) is sent."""
+        if self.statement_timeout is not None and conn.autocommit:
+            # (a transaction block would try to roll back a connection that a disconnect left mid-query)
+            raise TypeError("statement_timeout needs a connection that is not in autocommit mode")
+        batch: list[str] = []
+        prefix = "["
+        async with (
+            _statement_timeout(conn, self.statement_timeout),
+            conn.cursor(row_factory=tuple_row) as cur,  # whatever the connection was configured with
+        ):
+            # (typed as an iterator, but it is an async generator, which is what aclosing() needs)
+            size = self.batch_size if _CHUNKED_ROWS else 1
+            rows = cast("AsyncGenerator[tuple[Any, ...]]", cur.stream(self.query, self.params, size=size))
+            async with aclosing(rows):  # same reason as in stream_response(): finish psycopg's cleanup in order
+                async for (row_json,) in rows:
+                    batch.append(row_json)
+                    if len(batch) >= self.batch_size:
+                        yield (prefix + ",\n".join(batch)).encode()
+                        batch, prefix = [], ","
+        if batch or prefix == "[":  # remaining rows, or an empty result
+            yield (prefix + ",\n".join(batch) + "]").encode()
+        else:  # the last batch was full and has been sent already
+            yield b"]"
+
+
+def _as_json_rows(query: Any) -> Composed | Template:
+    if isinstance(query, Template):
+        # psycopg expands a Template nested with `:q` in place, its own values staying bound parameters
+        return t"select row_to_json(s)::text from (\n{query:q}\n) s"
+    if isinstance(query, Composable):
+        inner = query
+    else:
+        # bdt-lint: ignore sql-unverified-call -- callers pass a trusted literal (type-checked only); stacked statements
+        # are rejected by the extended protocol that cursor.stream() uses
+        inner = SQL(query.strip().rstrip(";"))
+    # newline before the closing paren: the query may end in a line comment
+    return SQL("select row_to_json(s)::text from (\n{}\n) s").format(inner)
+
+
+async def _send(send: Send, message: Message) -> None:
+    try:
+        await send(message)
+    except OSError:  # what servers speaking ASGI spec >= 2.4 do when the client is gone
+        raise ClientDisconnect from None
+
+
+async def _cancel_if_running(conn: AsyncConnection) -> None:
+    """Cancel the in-flight query on ``conn`` and close it, however often the request is cancelled meanwhile.
+
+    The connection can't be reused afterwards (the cancelled query's results are still pending), and a pool must
+    not get it back mid-query, so it is closed; a pool simply opens a fresh one.
+
+    Only a query that is still running (status ACTIVE) is cancelled: a cancel request that arrives after the
+    query finished would hit whatever statement the connection runs next once it is back in the pool.
+    """
+    if conn.closed or conn.info.transaction_status != TransactionStatus.ACTIVE:
+        return
+    # Its own task, awaited through asyncio.shield: a native task.cancel() (e.g. the disconnect watcher firing
+    # while we are already cleaning up) would otherwise interrupt it. The anyio shield covers scope cancellation.
+    cleanup = asyncio.ensure_future(_cancel_and_close(conn))
+    interrupted = False
+    with anyio.CancelScope(shield=True):
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                interrupted = True
+    cleanup.result()
+    if interrupted:
+        raise asyncio.CancelledError
+
+
+async def _cancel_and_close(conn: AsyncConnection) -> None:
+    try:
+        async with asyncio.timeout(_CANCEL_TIMEOUT_SECONDS):
+            await conn.cancel_safe(timeout=_CANCEL_TIMEOUT_SECONDS)
+    except Exception:
+        logger.warning("Could not cancel Postgres query", exc_info=True)
+    await conn.close()

pgdevkit/skills/pgdevkit/SKILL.md

@@ -4,8 +4,9 @@ plugin: coding
 description: >
   Use pgdevkit for any PostgreSQL work in a Python project: a local
   Docker/Podman test database (`pgdb testdb`), importable ORM-free CRUD and
-  query helpers (`pgdevkit.db`: `pg_*`, `fetch_all`, `PgPool`, `SqlLoader`), and the `database/`-folder schema-as-code
-  convention. Supersedes the old postgres-test-setup, postgres-best-practices,
+  query helpers (`pgdevkit.db`: `pg_*`, `fetch_all`, `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,
   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
@@ -43,7 +44,7 @@ Core rules for every piece of database code in a project using pgdevkit:
 uv add pgdevkit[cli,db]
 ```
 
-`cli` pulls in `typer`/`rich` for the `pgdb` command; `db` pulls in `pydantic`/`psycopg-pool` for the importable CRUD helpers. Skip either extra if the project doesn't need it (e.g. a project using only `pgdb testdb` doesn't need `db`).
+`cli` pulls in `typer`/`rich` for the `pgdb` command; `db` pulls in `pydantic`/`psycopg-pool` for the importable CRUD helpers; `fastapi` adds `pgdevkit.fastapi` (streaming JSON responses; FastAPI apps use `pgdevkit[cli,db,fastapi]`). Skip any extra the project doesn't need (e.g. a project using only `pgdb testdb` doesn't need `db`).
 
 ---
 
@@ -220,7 +221,8 @@ async with pool.connection() as conn:  # inside a transaction you already hold
 
 - `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.
-- `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).
+- `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).
+- `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.
 - `query` is typed `SqlQuery`: a literal string (`SqlLoader.load_sql()`), a sqlglot expression, 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, and write a literal `%` as `%%` when you also pass `params`. A t-string carries its own values, so don't also pass `params`.
 
 ### Dynamic SQL
@@ -255,6 +257,28 @@ test-data seeding and `pgdevkit.db.crud`'s CRUD helpers. Pass a `normalizers`
 dict (keyed by composite type name) if a project needs to reshape a value
 before conversion (e.g. backfilling missing locale keys).
 
+### Streaming JSON from FastAPI — `pgdevkit.fastapi`
+
+For large/grid-style read endpoints, return a `PostgresJsonResponse` instead of `fetch_all()` + a list of
+dicts: Postgres builds the JSON, rows are streamed, and the query is **cancelled in Postgres when the client
+disconnects**. Needs the `fastapi` extra (FastAPI >= 0.118). The pool registered with `set_default_pool()` (see
+*Connection pool*) is used, as in `fetch_all`.
+
+```python
+from pgdevkit.fastapi import PostgresJsonResponse
+
+@router.get("/articles", responses={200: {"model": list[ArticleOut]}})
+async def articles(lng: str) -> PostgresJsonResponse:
+    return PostgresJsonResponse(sql.load_sql("articles", "list_articles"), {"lng": lng})
+```
+
+- Query: from a `.sql` file via `SqlLoader` like any non-trivial query (or `psycopg.sql`, sqlglot or a t-string for dynamic SQL), values via `params` (`%(name)s`; none with a t-string, it carries its own). That it is a literal is enforced by the type checker only: never build it from user input. Data-modifying CTE or custom JSON: `query_produces_json=True` (one text column per row).
+- `responses={200: {"model": ...}}` keeps the OpenAPI schema typed for the generated frontend client; `response_model` is ignored and rows are **not validated**.
+- Connections as in `fetch_all`: default pool, `pool=`, or `con=`. Prefer the pool: a `con` you opened must outlive the response (`Depends` with `yield`, never `async with ... as conn: return PostgresJsonResponse(q, con=conn)`), and a disconnect aborts its transaction.
+- Errors show as `{"error": "Internal Server Error"}` (500); `expose_errors = IS_DEV` in a subclass shows the text (leaks SQL/values: never in prod). An error after the first byte leaves the array unterminated, so clients fail to parse it.
+- `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.
+
 ### SQL formatting
 
 ```bash
@@ -331,6 +355,7 @@ Reports drift between the `database/` `.sql` files and the actual schema — tab
 - [ ] Inline SQL only for trivial queries ≤ 4 lines; anything with JOINs/CTEs/aggregations/subqueries uses a `.sql` file
 - [ ] All parameters use `%(name)s` style with a dict argument
 - [ ] Custom read queries use `fetch_all(...)` (`model=` where the shape is stable; pass `con=` inside a transaction); results mapped to a Pydantic model; table-mapped models extend `PostgresTableModel`
+- [ ] Large/grid reads from FastAPI may use `pgdevkit.fastapi.PostgresJsonResponse` (streams, cancels on disconnect, no model validation)
 - [ ] 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.13.0.dist-info → pgdevkit-0.14.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgdevkit
-Version: 0.13.0
+Version: 0.14.2
 Summary: A helper for developing with Postgres
 Requires-Python: >=3.14
 Requires-Dist: docker>=7.1.0
@@ -15,6 +15,10 @@ Requires-Dist: typer>=0.26.7; extra == 'cli'
 Provides-Extra: db
 Requires-Dist: psycopg-pool>=3.3.0; extra == 'db'
 Requires-Dist: pydantic>=2.0; extra == 'db'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.118.0; extra == 'fastapi'
+Requires-Dist: psycopg-pool>=3.3.0; extra == 'fastapi'
+Requires-Dist: pydantic>=2.0; extra == 'fastapi'
 Provides-Extra: mssql
 Requires-Dist: mssql-python>=1.0.0; extra == 'mssql'
 Description-Content-Type: text/markdown
@@ -427,14 +431,17 @@ Install with the `db` extra: `pip install pgdevkit[db]`.
   `--entra-user`. For Lakebase hosts, also set the
   `{env_prefix}DATABRICKS_WORKSPACE_HOST` and `{env_prefix}DATABRICKS_INSTANCE`
   env vars.
-- **`fetch_all(query, params=None, *, model=None, row_mapper=None, con=None, pool=None, cancel=None)`**
+- **`fetch_all(query, params=None, *, model=None, row_mapper=None, con=None, pool=None, cancel=None, statement_timeout=None)`**
   — run one custom query and get every row back as dicts, as validated
   Pydantic `model` instances, or through a `row_mapper`. Pass `con` to run on a
   connection you already hold (it is borrowed: never committed, closed or
   released); otherwise a connection is taken from `pool` or the pool registered
   with `set_default_pool()`. Set the `cancel` `asyncio.Event` to abort the query on the server
-  (`QueryCanceled`); cancelling the awaiting task cancels it there too, and
-  `CancelledError` propagates as usual. `query` must be a literal string, a sqlglot
+  (`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
+  `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). `query` must be a literal string, a sqlglot
   expression, a `psycopg.sql` composable or a t-string — never an f-string (a sqlglot
   expression is only as safe as the strings it was built from: pass user values as
   `exp.Placeholder` + `params`).
@@ -482,6 +489,97 @@ async with pool.connection() as con:
     await pg_upsert(con, Widget(id=1, name="thing"), Widget)
 ```
 
+## `pgdevkit.fastapi` — streaming JSON responses
+
+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.)
+
+```python
+from pgdevkit.db import PgPool, set_default_pool
+from pgdevkit.fastapi import PostgresJsonResponse
+
+pool = PgPool(env_prefix="APP_POSTGRES_")
+set_default_pool(pool)  # once at startup, shared with fetch_all
+
+@router.get("/articles", responses={200: {"model": list[ArticleOut]}})
+async def articles(lng: str) -> PostgresJsonResponse:
+    return PostgresJsonResponse(
+        "select id, name from articles where lng = %(lng)s order by name",
+        {"lng": lng},
+    )
+```
+
+The `responses=` entry keeps the OpenAPI schema (and a generated frontend client) typed; `response_model` is ignored
+for a `Response`, and the rows are *not* validated against the model.
+
+- **Connections** work as in `fetch_all`: the pool registered with `set_default_pool()`, an explicit `pool=` (anything
+  with `.connection()`, e.g. `PgPool`), or a `con=` you opened yourself. A pooled connection is acquired when streaming
+  starts and released when it ends. A `con` must stay open until the response has been sent, i.e. come from a `Depends`
+  with `yield` (FastAPI >= 0.118); `async with pool.connection() as conn: return PostgresJsonResponse(q, con=conn)`
+  closes it too early. Prefer the pool.
+- **Query** — a literal string, a `psycopg.sql` composable, a sqlglot expression or a t-string, with values bound
+  through `params` (`%(name)s`; a t-string carries its own values and takes no `params`). Passing only literals
+  is enforced by the type checker, **not at runtime**: the query is wrapped as a subquery, never parsed, so never
+  build it from user input. For a data-modifying CTE, or custom JSON, pass `query_produces_json=True` and return one
+  *text* column per row (a `json` column or NULL fails). A trailing `;` is fine in a string, a `;` followed by a
+  comment is not.
+- **Options** — `batch_size` (rows per chunk, >= 1, default 1000; don't take it from user input),
+  `statement_timeout` (seconds, see below), `status_code`, `headers` (e.g. `{"Cache-Control": "max-age=3600"}`).
+
+### Cancellation
+
+The response watches for `http.disconnect` itself (Starlette only does that for ASGI spec < 2.4), also while the
+query is still running and nothing has been sent yet. It then cancels the query with `cancel_safe()`, shielded from
+the cancellation that is tearing the request down, and closes the connection if it was left mid-query: a pool opens a
+fresh one instead of reusing it. Only a query that is still running is cancelled, so a late cancel can never
+hit the next statement on a reused connection. A frontend `AbortController` / closed tab therefore frees the database.
+
+With `con=`, a disconnect aborts the query *and your transaction*, unlike `fetch_all`: the connection is afterwards
+either left in an aborted transaction (idle, with autocommit) or closed, depending on whether the stream was waiting for
+Postgres or for the client.
+Don't use it afterwards, and don't count on earlier writes in that transaction.
+
+Connections are held while the client reads, so a client that reads very slowly pins one (`statement_timeout` does not
+help, see below). Enforce a write timeout in the 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`.
+
+### Statement timeout
+
+`statement_timeout=<seconds>` (optional, also on `fetch_all`) lets **Postgres** abort the query after that long. It
+is set with `SET LOCAL` semantics for this one query: transaction-scoped, so it can't leak into the pool and works
+behind PgBouncer's transaction pooling, and a `con` you passed gets its previous setting back. Before the first byte
+the client gets a `504 {"error": "Query timed out"}`; after that the response is cut short like any other error. It
+needs a connection that is not in autocommit mode. Without it, the connection's own `statement_timeout` applies.
+
+It limits *query execution*, nothing else: Postgres defers a cancel while it is blocked writing to a client that
+has stopped reading, so a stalled reader keeps its connection regardless (a backend was observed staying `active`
+in `ClientWrite` well past a 1 s timeout). For that, use a write timeout in the reverse proxy.
+
+### Errors
+
+An error before the first byte becomes a JSON `{"error": ...}` response (500, or the status and headers of an
+`HTTPException` raised by a custom pool); the text is hidden unless you subclass and set `expose_errors = True`
+(it contains SQL fragments and parameter values: never in production):
+
+```python
+class AppJsonResponse(PostgresJsonResponse):
+    expose_errors = IS_DEV
+```
+
+After the first byte the status line is gone: the error is logged and re-raised, and the response ends **without
+the closing `]`**, so clients fail to parse it rather than accepting a silently shortened array. (Granian, which our
+apps run on, ends such a response cleanly with the truncated body.)
+
+### Notes
+
+It does no authorization: scope the query yourself. The first byte is sent once `batch_size` rows (or the whole
+result) are available, so lower `batch_size` for earlier output; Postgres itself also sends rows in 8 kB buffers,
+so a slow query with tiny rows delivers late either way.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{pgdevkit-0.13.0.dist-info → pgdevkit-0.14.2.dist-info}/RECORD

@@ -24,11 +24,13 @@ pgdevkit/db/__init__.py,sha256=_NdK4qAy0_0bSl3__dM0Mfi5n38NPIU-I6OMlAzR1sI,949
 pgdevkit/db/complex_types.py,sha256=bv3oMztSnrhz4-OJROBXfiouL2jJ8TxpSR_83HMLmTI,11197
 pgdevkit/db/connection.py,sha256=ylc_KVYsOvPeuW5GL1ebDDH0O3w93oe-EHwkUH4KoVs,5793
 pgdevkit/db/crud.py,sha256=t49aZmEJCIetn0du9OdWse3VSYAQe39S-jDaEt1SjmI,12537
-pgdevkit/db/fetch.py,sha256=gwCqI2fu2skahb98syPgrUpv3Y7EPl5iNlpIXTcN5X0,11059
+pgdevkit/db/fetch.py,sha256=i_BXBnJjVh7cOiKFmHFH9HBWg6owXThvgRGrMC0v204,13595
 pgdevkit/db/loader.py,sha256=0Swmp0h0s7I4acG0Dv3cem2YD4lFvq8aFEbFQPPQrxg,616
 pgdevkit/db/model.py,sha256=ntuXonq-SCGkbNw-lvdMS5VuzLjxYRT8O6xaVqiw56I,980
 pgdevkit/db/mssql_crud.py,sha256=yN4izZ0fsFwAs14008JECHH4dqjNbdHUHGEG8kidyNs,11374
 pgdevkit/db/mssql_sql.py,sha256=DO3UMsTFN9pg0tNdaPGb0wf6lWlHGcqwqzkrGVhJF2g,2292
+pgdevkit/fastapi/__init__.py,sha256=Oku0U7wNblWJj_wbyiw_ik299vAsdl1fX6FCth0KliI,84
+pgdevkit/fastapi/json_response.py,sha256=9NbsHeGARrhKoORIFEJtMivprXyHe_QvGgu6CEK0DKk,13058
 pgdevkit/testdb/__init__.py,sha256=tphuORo4t0QHQp_gFi6ZHXXgd32w6qUoKlaQCab6izA,366
 pgdevkit/testdb/_docker.py,sha256=-W59YBbcSIl9H_YmySRtVbOV4ImZPHOq9hxmlO-p56s,2807
 pgdevkit/testdb/api.py,sha256=13YgTz6hPcYWfsUlQJhJ7k20-W_4hzepedVaT8gWhxI,9709
@@ -43,10 +45,10 @@ pgdevkit/testdb/mssql/api.py,sha256=Ah95QTsOLvtubyHxRWDywjX9NCvTVgurmANLP5RY2Ck,
 pgdevkit/testdb/mssql/constants.py,sha256=qyA1FCv-2LAQ_C8OydePEXhyG_ZBPPB7vg1686xVpVU,3453
 pgdevkit/testdb/mssql/container.py,sha256=sqJPAuhN1by3kZZ96gLet4pRt3uJmUMO6Kkmvjydg1w,3791
 pgdevkit/docs/database-layout.md,sha256=j9N8GuT63D2oVf9rIOEv8GTWs4yTtjZTGH-zM5Wrg5o,8163
-pgdevkit/skills/pgdevkit/SKILL.md,sha256=50WxwVCPl3ZmQewnWMxtzydtx7O4e_Lwq3ZVs95cDUE,16384
+pgdevkit/skills/pgdevkit/SKILL.md,sha256=pAJF-Xd6wLeiGJ2VPyOfVaSIw1yWUNczjA-x4HICz_A,19258
 pgdevkit/skills/pgdevkit/references/dynamic-sql.md,sha256=jA-sO8Z10CaFFjYhGHlzZFrvNeXxj1QiAxoCn8RPPVc,2974
 pgdevkit/skills/pgdevkit/references/temporal-tables.md,sha256=LwZnItvQWI7bB0oRHxIfUc0ynnq7N0V5Mnv-QHvFN3Q,1364
-pgdevkit-0.13.0.dist-info/METADATA,sha256=s11Iw3wBk9tnukjuworzYlO6UjT91H-nq0DRy9RG_cQ,24886
-pgdevkit-0.13.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-pgdevkit-0.13.0.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
-pgdevkit-0.13.0.dist-info/RECORD,,
+pgdevkit-0.14.2.dist-info/METADATA,sha256=QD23CSUwKMdpV_AesUYjoM15XeHW1ftPNHt_WbL5YcU,31283
+pgdevkit-0.14.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pgdevkit-0.14.2.dist-info/entry_points.txt,sha256=FK2P55lf0WaGlOZJIINOGgCt8WB7ep0OnPsgnrp80bg,42
+pgdevkit-0.14.2.dist-info/RECORD,,