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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iron-sql
-Version: 0.4.2
+Version: 0.4.4
 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.4}/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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iron-sql"
-version = "0.4.2"
+version = "0.4.4"
 
 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.4}/src/iron_sql/codegen/generator.py

@@ -3,6 +3,7 @@ import dataclasses
 import hashlib
 import importlib
 import logging
+import re
 import warnings
 from collections import defaultdict
 from collections.abc import Callable
@@ -55,9 +56,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
 
@@ -186,6 +187,24 @@ def collect_used_enums(sqlc_res: SQLCResult) -> set[tuple[str, str]]:
     }
 
 
+def map_sqlc_error(
+    error: str,
+    block_starts: list[tuple[int, str]],
+    all_locations: dict[str, list[str]],
+) -> str:
+    def replace(m: re.Match[str]) -> str:
+        line = int(m.group(1))
+        name = next((n for start, n in reversed(block_starts) if start <= line), None)
+        if name is None:
+            return m.group(0)
+        locations = all_locations.get(name)
+        if not locations:
+            return m.group(0)
+        return f"{', '.join(locations)}:"
+
+    return re.sub(r"queries\.sql:(\d+)(?::\d+)?:", replace, error)
+
+
 def generate_sql_package(  # noqa: PLR0913, PLR0914
     *,
     schema_path: Path,
@@ -200,21 +219,14 @@ def generate_sql_package(  # noqa: PLR0913, PLR0914
     src_path: Path = Path(),
     tempdir_path: Path | None = None,
 ) -> bool:
-    dsn_import_package, dsn_import_path = dsn_import.split(":")
-
-    package_name = package_full_name.split(".")[-1]  # noqa: PLC0207
+    package_name = package_full_name.rsplit(".", maxsplit=1)[-1]
     sql_fn_name = f"{package_name}_sql"
 
-    target_package_path = src_path / f"{package_full_name.replace('.', '/')}.py"
-
-    queries = list(find_all_queries(src_path, sql_fn_name))
-    validate_stmt_has_single_row_type(queries)
-    queries = list({q.name: q for q in queries}.values())
+    queries, all_locations = collect_queries(src_path, sql_fn_name)
 
-    dsn_package = importlib.import_module(dsn_import_package)
-    dsn = eval(dsn_import_path, vars(dsn_package))  # noqa: S307
+    dsn, dsn_import_package, dsn_import_path = resolve_dsn(dsn_import)
 
-    sqlc_res = run_sqlc(
+    sqlc_res, block_starts = run_sqlc(
         src_path / schema_path,
         [(q.name, q.stmt) for q in queries],
         dsn=dsn,
@@ -223,63 +235,13 @@ def generate_sql_package(  # noqa: PLR0913, PLR0914
     )
 
     if sqlc_res.error:
-        logger.error("Error running SQLC:\n%s", sqlc_res.error)
+        mapped = map_sqlc_error(sqlc_res.error, block_starts, all_locations)
+        logger.error(f"Error running SQLC:\n{mapped}")
         return False
 
-    json_import_block = ""
-    json_col_overrides: dict[tuple[str, str], str] = {}
-
-    if json_model_overrides:
-        json_compatible_types = {"json", "jsonb", "text", "varchar"}
-        col_types = {
-            (table.rel.name, column.name): column.type.name.removeprefix("pg_catalog.")
-            for schema in sqlc_res.catalog.schemas
-            for table in schema.tables
-            for column in table.columns
-        }
-        tables = {table for table, _ in col_types}
-
-        parsed: dict[tuple[str, str], tuple[str, str]] = {}
-        for key, import_path in json_model_overrides.items():
-            table_name, sep, col_name = key.partition(".")
-            if not sep:
-                msg = f"json_model_overrides key must be 'table.column', got: {key!r}"
-                raise ValueError(msg)
-            if table_name not in tables:
-                msg = f"json_model_overrides: table {table_name!r} not found in catalog"
-                raise ValueError(msg)
-            if (table_name, col_name) not in col_types:
-                msg = (
-                    f"json_model_overrides: column {col_name!r} "
-                    f"not found in table {table_name!r}"
-                )
-                raise ValueError(msg)
-
-            db_type = col_types[table_name, col_name]
-            if db_type not in json_compatible_types:
-                msg = (
-                    f"json_model_overrides: column "
-                    f"{table_name}.{col_name} has type "
-                    f"{db_type!r}, expected one of "
-                    f"{json_compatible_types}"
-                )
-                raise ValueError(msg)
-
-            module_path, sep, class_name = import_path.partition(":")
-            if not sep:
-                msg = (
-                    "json_model_overrides value must be "
-                    f"'module:Class', got: {import_path!r}"
-                )
-                raise ValueError(msg)
-
-            parsed[table_name, col_name] = (module_path, class_name)
-
-        modules = sorted({module for module, _ in parsed.values()})
-        json_import_block = "\n" + "\n".join(f"import {m}" for m in modules)
-        json_col_overrides = {
-            key: f"{module}.{cls}" for key, (module, cls) in parsed.items()
-        }
+    json_import_block, json_col_overrides = resolve_json_model_overrides(
+        json_model_overrides or {}, sqlc_res.catalog
+    )
 
     resolver = TypeResolver(
         catalog=sqlc_res.catalog,
@@ -297,22 +259,82 @@ def generate_sql_package(  # noqa: PLR0913, PLR0914
         resolver,
     )
 
-    entities = [render_entity(e.name, e.column_specs) for e in ordered_entities]
+    entities = sorted(render_entity(e.name, e.column_specs) for e in ordered_entities)
 
     used_enums = collect_used_enums(sqlc_res)
 
-    enums = [
+    enums = sorted(
         render_enum_class(e, package_name, to_pascal_fn, to_snake_fn)
         for schema in sqlc_res.catalog.schemas
         for e in schema.enums
         if (schema.name, e.name) in used_enums
+    )
+
+    query_classes = render_query_classes(
+        sqlc_res.queries, queries, resolver, result_types, all_locations
+    )
+
+    query_overloads = [
+        render_query_overload(sql_fn_name, q.name, q.stmt, q.row_type) for q in queries
     ]
 
-    query_classes = [
+    query_dict_entries = [render_query_dict_entry(q.name, q.stmt) for q in queries]
+
+    target_package_path = src_path / f"{package_full_name.replace('.', '/')}.py"
+
+    new_content = render_package(
+        dsn_import_package,
+        dsn_import_path,
+        package_name,
+        sql_fn_name,
+        entities,
+        enums,
+        query_classes,
+        query_overloads,
+        query_dict_entries,
+        application_name,
+        json_import_block,
+    )
+    changed = write_if_changed(target_package_path, new_content + "\n")
+    if changed:
+        logger.info(f"Generated SQL package {package_full_name}")
+    return changed
+
+
+def collect_queries(
+    src_path: Path, sql_fn_name: str
+) -> tuple[list["CodeQuery"], defaultdict[str, list[str]]]:
+    raw = list(find_all_queries(src_path, sql_fn_name))
+    validate_stmt_has_single_row_type(raw)
+    all_locations: defaultdict[str, list[str]] = defaultdict(list)
+    first_occurrence: dict[str, CodeQuery] = {}
+    for q in raw:
+        all_locations[q.name].append(q.location)
+        if q.name not in first_occurrence:
+            first_occurrence[q.name] = q
+    queries = sorted(first_occurrence.values(), key=lambda q: (q.file, q.lineno))
+    return queries, all_locations
+
+
+def resolve_dsn(dsn_import: str) -> tuple[str, str, str]:
+    package_name, attr_path = dsn_import.split(":")
+    mod = importlib.import_module(package_name)
+    dsn: str = eval(attr_path, vars(mod))  # noqa: S307
+    return dsn, package_name, attr_path
+
+
+def render_query_classes(
+    sqlc_queries: tuple[Query, ...],
+    queries: list["CodeQuery"],
+    resolver: TypeResolver,
+    result_types: dict[str, str],
+    all_locations: defaultdict[str, list[str]],
+) -> list[str]:
+    query_order = {q.name: i for i, q in enumerate(queries)}
+    return [
         render_query_class(
             q.name,
             q.text,
-            package_name,
             [
                 resolver.param_spec(
                     p.column,
@@ -328,33 +350,67 @@ def generate_sql_package(  # noqa: PLR0913, PLR0914
                 if len(q.columns) == 1
                 else None
             ),
+            all_locations[q.name],
         )
-        for q in sqlc_res.queries
+        for q in sorted(sqlc_queries, key=lambda q: query_order[q.name])
     ]
 
-    query_overloads = [
-        render_query_overload(sql_fn_name, q.name, q.stmt, q.row_type) for q in queries
-    ]
 
-    query_dict_entries = [render_query_dict_entry(q.name, q.stmt) for q in queries]
+def resolve_json_model_overrides(
+    overrides: dict[str, str], catalog: Catalog
+) -> tuple[str, dict[tuple[str, str], str]]:
+    if not overrides:
+        return "", {}
 
-    new_content = render_package(
-        dsn_import_package,
-        dsn_import_path,
-        package_name,
-        sql_fn_name,
-        sorted(entities),
-        sorted(enums),
-        sorted(query_classes),
-        sorted(query_overloads),
-        sorted(query_dict_entries),
-        application_name,
-        json_import_block,
-    )
-    changed = write_if_changed(target_package_path, new_content + "\n")
-    if changed:
-        logger.info(f"Generated SQL package {package_full_name}")
-    return changed
+    json_compatible_types = {"json", "jsonb", "text", "varchar"}
+    col_types = {
+        (table.rel.name, column.name): column.type.name.removeprefix("pg_catalog.")
+        for schema in catalog.schemas
+        for table in schema.tables
+        for column in table.columns
+    }
+    tables = {table for table, _ in col_types}
+
+    parsed: dict[tuple[str, str], tuple[str, str]] = {}
+    for key, import_path in overrides.items():
+        table_name, sep, col_name = key.partition(".")
+        if not sep:
+            msg = f"json_model_overrides key must be 'table.column', got: {key!r}"
+            raise ValueError(msg)
+        if table_name not in tables:
+            msg = f"json_model_overrides: table {table_name!r} not found in catalog"
+            raise ValueError(msg)
+        if (table_name, col_name) not in col_types:
+            msg = (
+                f"json_model_overrides: column {col_name!r} "
+                f"not found in table {table_name!r}"
+            )
+            raise ValueError(msg)
+
+        db_type = col_types[table_name, col_name]
+        if db_type not in json_compatible_types:
+            msg = (
+                f"json_model_overrides: column "
+                f"{table_name}.{col_name} has type "
+                f"{db_type!r}, expected one of "
+                f"{json_compatible_types}"
+            )
+            raise ValueError(msg)
+
+        module_path, sep, class_name = import_path.partition(":")
+        if not sep:
+            msg = (
+                "json_model_overrides value must be "
+                f"'module:Class', got: {import_path!r}"
+            )
+            raise ValueError(msg)
+
+        parsed[table_name, col_name] = (module_path, class_name)
+
+    modules = sorted({module for module, _ in parsed.values()})
+    import_block = "\n" + "\n".join(f"import {m}" for m in modules)
+    col_overrides = {key: f"{module}.{cls}" for key, (module, cls) in parsed.items()}
+    return import_block, col_overrides
 
 
 def render_package(  # noqa: PLR0913, PLR0917
@@ -385,16 +441,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 +507,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 +550,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,11 +616,11 @@ 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,
-    scalar_json_type: str | None = None,
+    scalar_json_type: str | None,
+    locations: list[str],
 ) -> str:
     query_params = deduplicate_params(query_params)
 
@@ -582,39 +662,36 @@ 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}]):
+    # See: {", ".join(locations)}
+    _stmt = psycopg.sql.SQL({stmt!r})
+    _row_factory = staticmethod({row_factory})
 
     {indent_block(methods, "    ")}
 
@@ -749,7 +826,12 @@ def find_fn_calls(
         content = path.read_text(encoding="utf-8")
         if fn_name not in content:
             continue
-        for node in ast.walk(ast.parse(content, filename=str(path))):
+        try:
+            tree = ast.parse(content, filename=str(path))
+        except SyntaxError as exc:
+            msg = f"Failed to parse {path}: {exc.msg} (line {exc.lineno})"
+            raise SyntaxError(msg) from exc
+        for node in ast.walk(tree):
             match node:
                 case ast.Call(func=ast.Name(id=id)) if id == fn_name:
                     yield path, node.lineno, node
@@ -799,11 +881,15 @@ def find_all_queries(src_path: Path, sql_fn_name: str) -> Iterator[CodeQuery]:
 
 
 def validate_stmt_has_single_row_type(queries: list[CodeQuery]) -> None:
-    row_type_by_stmt: dict[str, str | None] = {}
+    first_by_stmt: dict[str, CodeQuery] = {}
     for query in queries:
-        if query.stmt in row_type_by_stmt:
-            if query.row_type != row_type_by_stmt[query.stmt]:
-                msg = f"row_type conflict (existing={row_type_by_stmt[query.stmt]!r})"
+        if query.stmt in first_by_stmt:
+            first = first_by_stmt[query.stmt]
+            if query.row_type != first.row_type:
+                msg = (
+                    f"row_type conflict: {first.location} has {first.row_type!r},"
+                    f" {query.location} has {query.row_type!r}"
+                )
                 raise ValueError(msg)
         else:
-            row_type_by_stmt[query.stmt] = query.row_type
+            first_by_stmt[query.stmt] = query

{iron_sql-0.4.2 → iron_sql-0.4.4}/src/iron_sql/codegen/sqlc.py

@@ -139,7 +139,7 @@ def run_sqlc(
     dsn: str | None,
     debug_path: Path | None = None,
     tempdir_path: Path | None = None,
-) -> SQLCResult:
+) -> tuple[SQLCResult, list[tuple[int, str]]]:
     if not schema_path.exists():
         msg = f"Schema file not found: {schema_path}"
         raise ValueError(msg)
@@ -148,7 +148,7 @@ def run_sqlc(
         return SQLCResult(
             catalog=Catalog(default_schema="", name="", schemas=()),
             queries=(),
-        )
+        ), []
 
     queries = list({q[0]: q for q in queries}.values())
 
@@ -156,13 +156,15 @@ def run_sqlc(
         dir=str(tempdir_path) if tempdir_path else None
     ) as tempdir:
         queries_path = Path(tempdir) / "queries.sql"
-        queries_path.write_text(
-            "\n\n".join(
-                f"-- name: {name} :exec\n{preprocess_sql(stmt)};"
-                for name, stmt in queries
-            ),
-            encoding="utf-8",
-        )
+        block_starts: list[tuple[int, str]] = []
+        blocks: list[str] = []
+        current_line = 1
+        for name, stmt in queries:
+            block = f"-- name: {name} :exec\n{preprocess_sql(stmt)};"
+            block_starts.append((current_line, name))
+            current_line += block.count("\n") + 2
+            blocks.append(block)
+        queries_path.write_text("\n\n".join(blocks), encoding="utf-8")
 
         (Path(tempdir) / "schema.sql").symlink_to(schema_path.absolute())
 
@@ -206,8 +208,10 @@ def run_sqlc(
                 error=sqlc_run_result.stderr.decode().strip(),
                 catalog=Catalog(default_schema="", name="", schemas=()),
                 queries=(),
-            )
-        return SQLCResult.model_validate_json(json_out_path.read_text(encoding="utf-8"))
+            ), block_starts
+        return SQLCResult.model_validate_json(
+            json_out_path.read_text(encoding="utf-8")
+        ), block_starts
 
 
 def preprocess_sql(stmt: str) -> str:

{iron_sql-0.4.2 → iron_sql-0.4.4}/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()