iron-sql 0.4.2__tar.gz → 0.4.3__tar.gz

{iron_sql-0.4.2 → iron_sql-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iron-sql
-Version: 0.4.2
+Version: 0.4.3
 Summary: iron_sql generates typed async PostgreSQL clients and runtime helpers from schemas and SQL queries
 Keywords: postgresql,sql,sqlc,psycopg,codegen,async
 Author: Ilia Ablamonov
@@ -46,6 +46,7 @@ The `sqlc` binary is bundled automatically via the `sqlc` Python package.
 - **Query discovery.** `generate_sql_package` scans your codebase for calls like `<package>_sql("SELECT ...")`, runs `sqlc` for type analysis, and emits a typed module.
 - **Strong typing.** Generated dataclasses and method signatures flow through your IDE and type checker.
 - **Async runtime.** Built on `psycopg` v3 with pooled connections, context-based connection reuse, and transaction helpers.
+- **Streaming.** `query_stream()` uses server-side cursors for memory-efficient iteration over large result sets.
 - **Safe by default.** Helper methods enforce expected row counts instead of returning silent `None`.
 
 ## Package Layout
@@ -98,7 +99,8 @@ The `sqlc` binary is bundled automatically via the `sqlc` Python package.
 - `ConnectionPool` opens lazily and reopens after `close()`, with `ContextVar`-based connection reuse for nested contexts.
 - `*_listen_session()` uses a dedicated pooled connection and doesn't reuse `ContextVar` transaction connections.
 - `query_single_row()` raises `NoRowsError`; `query_optional_row()` returns `None`. Both raise `TooManyRowsError` on 2+ rows.
-- JSONB params are sent with `pgjson.Jsonb`; JSON with `pgjson.Json`. Scalar row factories validate types at runtime.
+- `query_stream()` returns an async context manager yielding an `AsyncIterator`; uses server-side cursors with automatic transaction management.
+- JSONB params are sent with `psycopg.types.json.Jsonb`; JSON with `psycopg.types.json.Json`. Scalar row factories validate types at runtime.
 - `json_validated` decorator applies Pydantic model validation to dataclass fields on construction.
 
 ## Example

{iron_sql-0.4.2 → iron_sql-0.4.3}/README.md

@@ -20,6 +20,7 @@ The `sqlc` binary is bundled automatically via the `sqlc` Python package.
 - **Query discovery.** `generate_sql_package` scans your codebase for calls like `<package>_sql("SELECT ...")`, runs `sqlc` for type analysis, and emits a typed module.
 - **Strong typing.** Generated dataclasses and method signatures flow through your IDE and type checker.
 - **Async runtime.** Built on `psycopg` v3 with pooled connections, context-based connection reuse, and transaction helpers.
+- **Streaming.** `query_stream()` uses server-side cursors for memory-efficient iteration over large result sets.
 - **Safe by default.** Helper methods enforce expected row counts instead of returning silent `None`.
 
 ## Package Layout
@@ -72,7 +73,8 @@ The `sqlc` binary is bundled automatically via the `sqlc` Python package.
 - `ConnectionPool` opens lazily and reopens after `close()`, with `ContextVar`-based connection reuse for nested contexts.
 - `*_listen_session()` uses a dedicated pooled connection and doesn't reuse `ContextVar` transaction connections.
 - `query_single_row()` raises `NoRowsError`; `query_optional_row()` returns `None`. Both raise `TooManyRowsError` on 2+ rows.
-- JSONB params are sent with `pgjson.Jsonb`; JSON with `pgjson.Json`. Scalar row factories validate types at runtime.
+- `query_stream()` returns an async context manager yielding an `AsyncIterator`; uses server-side cursors with automatic transaction management.
+- JSONB params are sent with `psycopg.types.json.Jsonb`; JSON with `psycopg.types.json.Json`. Scalar row factories validate types at runtime.
 - `json_validated` decorator applies Pydantic model validation to dataclass fields on construction.
 
 ## Example

{iron_sql-0.4.2 → iron_sql-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iron-sql"
-version = "0.4.2"
+version = "0.4.3"
 
 description = "iron_sql generates typed async PostgreSQL clients and runtime helpers from schemas and SQL queries"
 readme = "README.md"

{iron_sql-0.4.2 → iron_sql-0.4.3}/src/iron_sql/codegen/generator.py

@@ -55,9 +55,9 @@ class ParamSpec:
 
         match self.db_type:
             case "json":
-                expr = f"pgjson.Json({self.name})"
+                expr = f"psycopg.types.json.Json({self.name})"
             case "jsonb":
-                expr = f"pgjson.Jsonb({self.name})"
+                expr = f"psycopg.types.json.Jsonb({self.name})"
             case _:
                 return self.name
 
@@ -312,7 +312,6 @@ def generate_sql_package(  # noqa: PLR0913, PLR0914
         render_query_class(
             q.name,
             q.text,
-            package_name,
             [
                 resolver.param_spec(
                     p.column,
@@ -385,16 +384,20 @@ import uuid
 from collections.abc import AsyncGenerator
 from collections.abc import AsyncIterator
 from collections.abc import Sequence
+from contextlib import AbstractAsyncContextManager
 from contextlib import asynccontextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
 from enum import StrEnum
+from typing import ClassVar
 from typing import Literal
 from typing import overload
 
 import psycopg
+import psycopg.abc
 import psycopg.rows
-from psycopg.types import json as pgjson
+import psycopg.sql
+import psycopg.types.json
 
 from iron_sql import runtime
 
@@ -447,8 +450,28 @@ async def {package_name}_notify(channel: str, payload: str = "") -> None:
 {"\n\n\n".join(entities)}
 
 
-class Query:
-    pass
+class Query[T]:
+    _stmt: ClassVar[psycopg.sql.SQL]
+    _row_factory: psycopg.rows.BaseRowFactory[T]
+
+    @asynccontextmanager
+    async def _client_cursor(self, params: psycopg.abc.Params | None):
+        async with (
+            {package_name}_connection() as conn,
+            psycopg.AsyncRawCursor(conn, row_factory=self._row_factory) as cur,
+        ):
+            await cur.execute(self._stmt, params)
+            yield cur
+
+    @asynccontextmanager
+    async def _server_cursor(self, params: psycopg.abc.Params | None):
+        async with (
+            {package_name}_connection() as conn,
+            runtime.ensure_transaction(conn),
+            psycopg.AsyncRawServerCursor(conn, row_factory=self._row_factory, name=runtime.next_cursor_name()) as cur,
+        ):
+            await cur.execute(self._stmt, params)
+            yield cur
 
 
 {"\n\n\n".join(query_classes)}
@@ -470,7 +493,7 @@ def {sql_fn_name}(stmt: str, row_type: str | None = None) -> Query:
     msg = f"Unknown statement: {{stmt!r}}"
     raise KeyError(msg)
 
-    """.strip()
+    """.strip()  # noqa: E501
 
 
 def render_enum_class(
@@ -536,7 +559,6 @@ def deduplicate_params(params: list[ParamSpec]) -> list[ParamSpec]:
 def render_query_class(
     query_name: str,
     stmt: str,
-    package_name: str,
     query_params: list[ParamSpec],
     result: str,
     columns_num: int,
@@ -582,39 +604,35 @@ def render_query_class(
         methods = f"""
 
 async def query_all_rows({", ".join(query_fn_params)}) -> list[{result}]:
-    async with self._execute({params_arg}) as cur:
+    async with self._client_cursor({params_arg}) as cur:
         return await cur.fetchall()
 
 async def query_single_row({", ".join(query_fn_params)}) -> {result}:
-    async with self._execute({params_arg}) as cur:
+    async with self._client_cursor({params_arg}) as cur:
         return runtime.get_one_row(await cur.fetchmany(2))
 
 async def query_optional_row({", ".join(query_fn_params)}) -> {base_result} | None:
-    async with self._execute({params_arg}) as cur:
+    async with self._client_cursor({params_arg}) as cur:
         return runtime.get_one_row_or_none(await cur.fetchmany(2))
 
-        """.strip()
+def query_stream({", ".join(query_fn_params)}) -> AbstractAsyncContextManager[AsyncIterator[{result}]]:
+    return self._server_cursor({params_arg})
+
+        """.strip()  # noqa: E501
     else:
         methods = f"""
 
 async def execute({", ".join(query_fn_params)}) -> None:
-    async with self._execute({params_arg}):
+    async with self._client_cursor({params_arg}):
         pass
 
         """.strip()
 
     return f"""
 
-class {query_name}(Query):
-    @asynccontextmanager
-    async def _execute(self, params) -> AsyncIterator[psycopg.AsyncRawCursor[{result}]]:
-        stmt = {stmt!r}
-        async with (
-            {package_name}_connection() as conn,
-            psycopg.AsyncRawCursor(conn, row_factory={row_factory}) as cur,
-        ):
-            await cur.execute(stmt, params)
-            yield cur
+class {query_name}(Query[{result}]):
+    _stmt = psycopg.sql.SQL({stmt!r})
+    _row_factory = staticmethod({row_factory})
 
     {indent_block(methods, "    ")}
 

{iron_sql-0.4.2 → iron_sql-0.4.3}/src/iron_sql/runtime.py

@@ -1,4 +1,5 @@
 import contextlib
+import itertools
 import types
 from collections.abc import AsyncGenerator
 from collections.abc import AsyncIterator
@@ -14,9 +15,9 @@ from typing import overload
 
 import psycopg
 import psycopg.rows
+import psycopg.sql
+import psycopg.types.json
 import psycopg_pool
-from psycopg import sql
-from psycopg.types import json as pgjson
 from pydantic import TypeAdapter
 
 _adapter_cache: dict[object, TypeAdapter[object]] = {}
@@ -63,21 +64,25 @@ async def listen(
 async def notify(conn: psycopg.AsyncConnection, channel: str, payload: str) -> None:
     _validate_channel(channel)
     await conn.execute(
-        sql.SQL("NOTIFY {}, {}").format(
-            sql.Identifier(channel),
-            sql.Literal(payload),
+        psycopg.sql.SQL("NOTIFY {}, {}").format(
+            psycopg.sql.Identifier(channel),
+            psycopg.sql.Literal(payload),
         )
     )
 
 
 async def execute_listen(conn: psycopg.AsyncConnection, channel: str) -> None:
     _validate_channel(channel)
-    await conn.execute(sql.SQL("LISTEN {}").format(sql.Identifier(channel)))
+    await conn.execute(
+        psycopg.sql.SQL("LISTEN {}").format(psycopg.sql.Identifier(channel))
+    )
 
 
 async def execute_unlisten(conn: psycopg.AsyncConnection, channel: str) -> None:
     _validate_channel(channel)
-    await conn.execute(sql.SQL("UNLISTEN {}").format(sql.Identifier(channel)))
+    await conn.execute(
+        psycopg.sql.SQL("UNLISTEN {}").format(psycopg.sql.Identifier(channel))
+    )
 
 
 async def _has_active_listen_subscriptions(conn: psycopg.AsyncConnection) -> bool:
@@ -96,6 +101,26 @@ def _validate_channel(name: str) -> None:
         raise ValueError(msg)
 
 
+_cursor_seq = itertools.count()
+
+
+def next_cursor_name() -> str:
+    return f"_c{next(_cursor_seq)}"
+
+
+@asynccontextmanager
+async def ensure_transaction(conn: psycopg.AsyncConnection) -> AsyncIterator[None]:
+    match conn.info.transaction_status:
+        case psycopg.pq.TransactionStatus.IDLE:
+            async with conn.transaction():
+                yield
+        case psycopg.pq.TransactionStatus.INTRANS:
+            yield
+        case status:
+            msg = f"Cannot use server-side cursor: connection is in {status.name} state"
+            raise psycopg.InterfaceError(msg)
+
+
 class ConnectionPool:
     def __init__(
         self,
@@ -196,9 +221,9 @@ def serialize_json_param(typ: object, value: object, db_type: str) -> object:
     adapter = get_adapter(typ)
     match db_type:
         case "json":
-            return pgjson.Json(adapter.dump_python(value, mode="json"))
+            return psycopg.types.json.Json(adapter.dump_python(value, mode="json"))
         case "jsonb":
-            return pgjson.Jsonb(adapter.dump_python(value, mode="json"))
+            return psycopg.types.json.Jsonb(adapter.dump_python(value, mode="json"))
         case _:
             return adapter.dump_json(value).decode()