zero-server 0.0.1__py3-none-any.whl

zero_server/query/registry.py

@@ -0,0 +1,143 @@
+"""`define_query` and `define_queries`: named queries the query endpoint resolves by name.
+
+Ported from rocicorp/mono `packages/zql/src/query/query-registry.ts`, `validate-input.ts` and
+`error.ts` at zero/v1.10.0 (905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+
+A validator is anything with Pydantic's `validate_python` (a `TypeAdapter`, or a model class), or a
+plain callable that returns the parsed value and raises `ValueError` on bad input. Upstream takes a
+Standard Schema validator; the error it raises has the same shape.
+"""
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, overload
+
+from pydantic import ValidationError
+
+from zero_server.query.builder import Query
+from zero_server.shared.json import JSONValue
+from zero_server.shared.registry import Registry, build, merge, value_at_path
+
+type QueryFn = Callable[..., Query]
+"""Called as `fn(args=..., ctx=...)`."""
+
+_SEPARATOR = re.compile(r"[.|]")
+
+
+class QueryParseError(Exception):
+    """The query endpoint reports this as a `parse` error rather than an `app` error."""
+
+    def __init__(self, cause: BaseException | None = None) -> None:
+        message = (
+            f"Failed to parse arguments for query: {cause}"
+            if isinstance(cause, Exception) and str(cause)
+            else "Failed to parse arguments for query"
+        )
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class InputValidationError(Exception):
+    def __init__(self, message: str, issues: list[dict[str, Any]]) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details: dict[str, Any] = {"type": "InputValidationError", "result": {"issues": issues}}
+
+
+def _issues(error: Exception) -> list[dict[str, Any]]:
+    if isinstance(error, ValidationError):
+        return [{"message": e["msg"], "path": list(e["loc"])} for e in error.errors()]
+    return [{"message": str(error)}]
+
+
+def validate_input(name: str, value: Any, validator: Any, kind: str) -> Any:
+    if validator is None:
+        return value
+    try:
+        if hasattr(validator, "validate_python"):
+            return validator.validate_python(value)
+        if hasattr(validator, "model_validate"):
+            return validator.model_validate(value)
+        return validator(value)
+    except (ValidationError, ValueError, TypeError) as error:
+        issues = _issues(error)
+        joined = ", ".join(issue["message"] for issue in issues)
+        raise InputValidationError(f"Validation failed for {kind} {name}: {joined}", issues) from error
+
+
+@dataclass(frozen=True)
+class QueryDefinition:
+    fn: QueryFn
+    validator: Any = None
+
+
+def is_schema_validator(value: object) -> bool:
+    """A Pydantic model class or `TypeAdapter`, as opposed to a function."""
+    return hasattr(value, "validate_python") or (isinstance(value, type) and hasattr(value, "model_validate"))
+
+
+@overload
+def define_query(fn_or_validator: QueryFn, fn: None = None) -> QueryDefinition: ...
+@overload
+def define_query(fn_or_validator: Any, fn: QueryFn) -> QueryDefinition: ...
+@overload
+def define_query(fn_or_validator: Any, fn: None = None) -> Callable[[QueryFn], QueryDefinition]: ...
+def define_query(fn_or_validator: Any, fn: QueryFn | None = None) -> Any:
+    """Define a query, called as `fn(args=..., ctx=...)`. Three forms:
+
+    - `define_query(fn)`, or `@define_query` on `fn`: no validation, `args` as the client sent them.
+    - `define_query(validator, fn)`: `args` parsed by `validator` first.
+    - `@define_query(ArgsModel)` on `fn`: the same, for a Pydantic model or `TypeAdapter`. A plain
+      function validator needs the two-argument form, since it cannot be told apart from `fn`.
+    """
+    if fn is not None:
+        return QueryDefinition(fn=fn, validator=fn_or_validator)
+    if is_schema_validator(fn_or_validator):
+        return lambda decorated: QueryDefinition(fn=decorated, validator=fn_or_validator)
+    return QueryDefinition(fn=fn_or_validator)
+
+
+@dataclass(frozen=True)
+class QueryRequest:
+    query: "CustomQuery"
+    args: JSONValue | None
+
+
+class CustomQuery:
+    def __init__(self, name: str, definition: QueryDefinition) -> None:
+        self.query_name = name
+        self._definition = definition
+
+    def fn(self, *, args: JSONValue | None = None, ctx: Any = None) -> Query:
+        validated = validate_input(self.query_name, args, self._definition.validator, "query")
+        return self._definition.fn(args=validated, ctx=ctx)
+
+    def __call__(self, args: JSONValue | None = None) -> QueryRequest:
+        return QueryRequest(query=self, args=args)
+
+
+type QueryRegistry = Registry
+type QueryDefinitions = Mapping[str, "QueryDefinition | QueryDefinitions"]
+
+
+def define_queries(definitions: "QueryDefinitions | Registry", overrides: "QueryDefinitions | None" = None) -> Registry:
+    """Name each query by its path through `definitions`, dot-separated: `{"issue": {"byID": ...}}` is
+    `issue.byID`. `overrides` replaces or adds entries in a base registry."""
+    is_definition = lambda value: isinstance(value, QueryDefinition)  # noqa: E731
+    base = definitions if isinstance(definitions, Registry) else build(definitions, is_definition, CustomQuery)
+    if overrides is None:
+        return base
+    return merge(base, build(overrides, is_definition, CustomQuery))
+
+
+def get_query(queries: Registry, name: str) -> CustomQuery | None:
+    found = value_at_path(queries, name, _SEPARATOR)
+    return found if isinstance(found, CustomQuery) else None
+
+
+def must_get_query(queries: Registry, name: str) -> CustomQuery:
+    query = get_query(queries, name)
+    if query is None:
+        raise Exception(f"Query not found: {name}")
+    return query

zero_server/schema.py

@@ -0,0 +1,142 @@
+"""The Zero schema, loaded from the JSON of the TypeScript `schema.ts`, and its name mapping.
+
+The schema stays authored in TypeScript because the client needs it. Emit it with
+`JSON.stringify(schema)` and load that here; this module has no schema DSL of its own.
+
+Ported from rocicorp/mono `packages/zero-types/src/schema.ts`, `schema-value.ts`, `name-mapper.ts` and
+`packages/zero-schema/src/name-mapper.ts` at zero/v1.10.0 (905d08516ba0caaf314cd28e93a5a47e8acdd482).
+Apache-2.0, Copyright Rocicorp.
+"""
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from zero_server.shared.js import js_stringify
+
+type ValueType = Literal["string", "number", "boolean", "null", "json"]
+type Cardinality = Literal["one", "many"]
+
+
+class _SchemaModel(BaseModel):
+    model_config = ConfigDict(frozen=True, populate_by_name=True, extra="ignore")
+
+
+class ColumnSchema(_SchemaModel):
+    type: ValueType
+    optional: bool = False
+    server_name: str | None = Field(default=None, alias="serverName")
+
+
+class TableSchema(_SchemaModel):
+    name: str
+    server_name: str | None = Field(default=None, alias="serverName")
+    columns: dict[str, ColumnSchema]
+    primary_key: tuple[str, ...] = Field(alias="primaryKey", min_length=1)
+
+
+class Connection(_SchemaModel):
+    source_field: tuple[str, ...] = Field(alias="sourceField")
+    dest_field: tuple[str, ...] = Field(alias="destField")
+    dest_schema: str = Field(alias="destSchema")
+    cardinality: Cardinality
+
+
+type Relationship = tuple[Connection] | tuple[Connection, Connection]
+
+
+class Schema(_SchemaModel):
+    tables: dict[str, TableSchema]
+    # Upstream only has entries for tables that declare relationships.
+    relationships: dict[str, dict[str, Relationship]] = Field(default_factory=dict)
+    enable_legacy_queries: bool | None = Field(default=None, alias="enableLegacyQueries")
+    enable_legacy_mutators: bool | None = Field(default=None, alias="enableLegacyMutators")
+
+
+def load_schema(source: str | Path | Mapping[str, Any]) -> Schema:
+    """A schema from `JSON.stringify(schema)`: the JSON text, a path to it, or the parsed object."""
+    if isinstance(source, Path):
+        source = source.read_text()
+    if isinstance(source, str):
+        source = json.loads(source)
+    return Schema.model_validate(source)
+
+
+@dataclass(frozen=True)
+class DestNames:
+    table_name: str
+    columns: dict[str, str]
+    all_columns_same: bool
+
+
+def _in_context(context: Any) -> str:
+    return f"in {js_stringify(context)}" if context else ""
+
+
+class NameMapper:
+    def __init__(self, tables: dict[str, DestNames]) -> None:
+        self._tables = tables
+
+    def _table(self, src: str, context: Any = None) -> DestNames:
+        table = self._tables.get(src)
+        if table is None:
+            raise Exception(f'unknown table "{src}" {_in_context(context)}')
+        return table
+
+    def table_name(self, src: str, context: Any = None) -> str:
+        return self._table(src, context).table_name
+
+    def table_name_if_known(self, src: str) -> str | None:
+        table = self._tables.get(src)
+        return table.table_name if table is not None else None
+
+    def column_name(self, table: str, src: str, context: Any = None) -> str:
+        dest = self._table(table, context).columns.get(src)
+        if not dest:
+            raise Exception(f'unknown column "{src}" of "{table}" table {_in_context(context)}')
+        return dest
+
+    def row[V](self, table: str, row: Mapping[str, V]) -> dict[str, V]:
+        """Rename a row's columns. Columns the schema does not know pass through."""
+        dest = self._table(table)
+        if dest.all_columns_same:
+            return dict(row)
+        return {dest.columns.get(column, column): value for column, value in row.items()}
+
+    def columns(self, table: str, columns: tuple[str, ...]) -> tuple[str, ...]:
+        dest = self._table(table)
+        if dest.all_columns_same:
+            return columns
+        return tuple(dest.columns.get(column, column) for column in columns)
+
+
+def client_to_server(tables: Mapping[str, TableSchema]) -> NameMapper:
+    return _mapper("client", tables)
+
+
+def server_to_client(tables: Mapping[str, TableSchema]) -> NameMapper:
+    return _mapper("server", tables)
+
+
+def _mapper(src: Literal["client", "server"], tables: Mapping[str, TableSchema]) -> NameMapper:
+    mapping: dict[str, DestNames] = {}
+    for table_name, table in tables.items():
+        all_same = True
+        names: dict[str, str] = {}
+        for name, column in table.columns.items():
+            if column.server_name and column.server_name != name:
+                all_same = False
+            server_column = column.server_name if column.server_name is not None else name
+            if src == "client":
+                names[name] = server_column
+            else:
+                names[server_column] = name
+        server_table = table.server_name if table.server_name is not None else table_name
+        key = table_name if src == "client" else server_table
+        dest = server_table if src == "client" else table_name
+        mapping[key] = DestNames(table_name=dest, columns=names, all_columns_same=all_same)
+    return NameMapper(mapping)

zero_server/server/__init__.py

@@ -0,0 +1 @@
+"""The server SDK: what `@rocicorp/zero/server` gives a TypeScript backend."""

zero_server/server/adapters/__init__.py

@@ -0,0 +1 @@
+"""One `ZQLDatabase` per supported Postgres driver, as upstream has one per JavaScript driver."""

zero_server/server/adapters/asyncpg.py

@@ -0,0 +1,43 @@
+"""asyncpg, directly. Needs the `zero-server[asyncpg]` extra."""
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+import asyncpg
+
+from zero_server.schema import Schema
+from zero_server.server.transaction import DBTransaction, Row
+from zero_server.server.zql_database import PostgresError, ZQLDatabase
+
+
+class AsyncpgTransaction:
+    def __init__(self, connection: asyncpg.Connection) -> None:
+        self._connection = connection
+
+    @property
+    def wrapped_transaction(self) -> asyncpg.Connection:
+        return self._connection
+
+    async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
+        try:
+            records = await self._connection.fetch(sql, *params)
+        except asyncpg.PostgresError as error:
+            # asyncpg sets `message` on its error classes at runtime: the primary message alone.
+            raise PostgresError(getattr(error, "message", str(error))) from error
+        return [dict(record) for record in records]
+
+
+class AsyncpgConnection:
+    def __init__(self, pool: asyncpg.Pool) -> None:
+        self.pool = pool
+
+    async def transaction[R](self, fn: Callable[[DBTransaction[asyncpg.Connection]], Awaitable[R]]) -> R:
+        async with self.pool.acquire() as connection, connection.transaction():
+            return await fn(AsyncpgTransaction(connection))
+
+
+class AsyncpgDatabase(ZQLDatabase[asyncpg.Connection]):
+    """A `ZQLDatabase` on an asyncpg pool (`await asyncpg.create_pool(dsn)`)."""
+
+    def __init__(self, pool: asyncpg.Pool, schema: Schema | None = None) -> None:
+        super().__init__(AsyncpgConnection(pool), schema)

zero_server/server/adapters/psycopg.py

@@ -0,0 +1,55 @@
+"""psycopg 3, async. Needs the `zero-server[psycopg]` extra.
+
+Statements run through a raw cursor, which takes Postgres's own `$1` placeholders, so the SQL is the
+same text the other adapters send.
+"""
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+import psycopg
+from psycopg.rows import dict_row
+from psycopg_pool import AsyncConnectionPool
+
+from zero_server.schema import Schema
+from zero_server.server.transaction import DBTransaction, Row
+from zero_server.server.zql_database import PostgresError, ZQLDatabase
+
+
+class PsycopgTransaction:
+    def __init__(self, connection: psycopg.AsyncConnection[Any]) -> None:
+        self._connection = connection
+
+    @property
+    def wrapped_transaction(self) -> psycopg.AsyncConnection[Any]:
+        return self._connection
+
+    async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
+        cursor = psycopg.AsyncRawCursor(self._connection, row_factory=dict_row)
+        try:
+            await cursor.execute(sql, list(params))  # ty: ignore[invalid-argument-type]
+            return await cursor.fetchall() if cursor.description is not None else []
+        except psycopg.errors.Error as error:
+            if error.diag.sqlstate is None and "NUL (0x00)" in str(error):
+                # psycopg refuses a NUL in a text value before sending it. Report what Postgres reports
+                # for the same value through the other drivers.
+                raise PostgresError('invalid byte sequence for encoding "UTF8": 0x00') from error
+            raise PostgresError(error.diag.message_primary or str(error)) from error
+        finally:
+            await cursor.close()
+
+
+class PsycopgConnection:
+    def __init__(self, pool: AsyncConnectionPool) -> None:
+        self.pool = pool
+
+    async def transaction[R](self, fn: Callable[[DBTransaction[psycopg.AsyncConnection[Any]]], Awaitable[R]]) -> R:
+        async with self.pool.connection() as connection, connection.transaction():
+            return await fn(PsycopgTransaction(connection))
+
+
+class PsycopgDatabase(ZQLDatabase[psycopg.AsyncConnection[Any]]):
+    """A `ZQLDatabase` on a psycopg pool (`AsyncConnectionPool(conninfo, open=False)`, then `await pool.open()`)."""
+
+    def __init__(self, pool: AsyncConnectionPool, schema: Schema | None = None) -> None:
+        super().__init__(PsycopgConnection(pool), schema)

zero_server/server/adapters/sqlalchemy.py

@@ -0,0 +1,49 @@
+"""SQLAlchemy's asyncio engine, with the asyncpg driver.
+
+Needs the `zero-server[sqlalchemy]` extra.
+"""
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from sqlalchemy.exc import DBAPIError
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
+
+from zero_server.schema import Schema
+from zero_server.server.transaction import DBTransaction, Row
+from zero_server.server.zql_database import PostgresError, ZQLDatabase
+
+
+class SQLAlchemyTransaction:
+    def __init__(self, connection: AsyncConnection) -> None:
+        self._connection = connection
+
+    @property
+    def wrapped_transaction(self) -> AsyncConnection:
+        return self._connection
+
+    async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
+        try:
+            result = await self._connection.exec_driver_sql(sql, tuple(params))
+        except DBAPIError as error:
+            cause = error.orig.__cause__ if error.orig is not None and error.orig.__cause__ is not None else error.orig
+            # asyncpg's `message` is the primary message alone, which is all postgres.js reports.
+            message = getattr(cause, "message", None)
+            raise PostgresError(message if isinstance(message, str) else str(cause)) from error
+        return [dict(row) for row in result.mappings()] if result.returns_rows else []
+
+
+class SQLAlchemyConnection:
+    def __init__(self, engine: AsyncEngine) -> None:
+        self.engine = engine
+
+    async def transaction[R](self, fn: Callable[[DBTransaction[AsyncConnection]], Awaitable[R]]) -> R:
+        async with self.engine.begin() as connection:
+            return await fn(SQLAlchemyTransaction(connection))
+
+
+class SQLAlchemyDatabase(ZQLDatabase[AsyncConnection]):
+    """A `ZQLDatabase` on `engine`, which must use the asyncpg driver (`postgresql+asyncpg://`)."""
+
+    def __init__(self, engine: AsyncEngine, schema: Schema | None = None) -> None:
+        super().__init__(SQLAlchemyConnection(engine), schema)

zero_server/server/crud.py

@@ -0,0 +1,134 @@
+"""`tx.mutate.<table>.insert / upsert / update / delete` on the server, as SQL.
+
+Ported from rocicorp/mono `packages/zero-server/src/custom.ts` (`makeServerTableCRUD`),
+`packages/zql/src/mutate/crud.ts` and the column conversions of `packages/z2s/src/sql.ts` at zero/v1.10.0
+(905d08516ba0caaf314cd28e93a5a47e8acdd482). Apache-2.0, Copyright Rocicorp.
+
+Values are bound as `zero_server.z2s.sql` binds them.
+"""
+
+from collections.abc import Mapping
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from zero_server.schema import Schema, TableSchema
+from zero_server.server.server_schema import ServerSchema, ServerTableSchema
+from zero_server.server.transaction import DBTransaction
+from zero_server.shared.asserts import check
+from zero_server.shared.js import js_keys
+from zero_server.z2s.sql import Params, ident
+
+
+def _as_row(value: object) -> dict[str, Any]:
+    """The row a value stands for, by `Object.entries`: upstream reads every row that way first."""
+    match value:
+        case None:
+            raise TypeError("Cannot convert undefined or null to object")
+        case Mapping():
+            return dict(value)
+        case str() | list() | tuple():
+            return {str(i): item for i, item in enumerate(value)}
+        case _:
+            return {}
+
+
+def _server_name(table: TableSchema) -> str:
+    return table.server_name if table.server_name is not None else table.name
+
+
+def _server_column(table: TableSchema, column: str) -> str:
+    schema = table.columns.get(column)
+    check(schema, f"Column {column} was not found in the Zero schema for the table {table.name}")
+    assert schema is not None
+    return schema.server_name if schema.server_name is not None else column
+
+
+I = TypeVar("I", default=Mapping[str, Any])  # noqa: E741 - the insert row type
+U = TypeVar("U", default=Mapping[str, Any])
+K = TypeVar("K", default=Mapping[str, Any])
+
+
+class TableCRUD(Generic[I, U, K]):
+    """Writes to one table. Generated schema types narrow the row types: `I` to insert or upsert, `U` to
+    update (the key and any other columns), `K` to delete (the key)."""
+
+    def __init__(self, table: TableSchema, tx: DBTransaction[Any], server_table: ServerTableSchema) -> None:
+        self._table = table
+        self._tx = tx
+        self._server_table = server_table
+
+    def _pk_clause(self, params: Params, row: Mapping[str, Any]) -> str:
+        return " AND ".join(
+            f"{ident(server)} = {params.column(self._server_table[server], row.get(name), comparison=True)}"
+            for name, server in ((n, _server_column(self._table, n)) for n in self._table.primary_key)
+        )
+
+    def _non_pk(self, value: dict[str, Any]) -> list[str]:
+        return [k for k in js_keys(value) if k not in self._table.primary_key]
+
+    async def insert(self, value: I) -> None:
+        await self._insert(_as_row(value), upsert=False)
+
+    async def upsert(self, value: I) -> None:
+        await self._insert(_as_row(value), upsert=True)
+
+    async def _insert(self, value: dict[str, Any], *, upsert: bool) -> None:
+        keys = js_keys(value)
+        targeted = [_server_column(self._table, k) for k in keys]
+        pk = [_server_column(self._table, k) for k in self._table.primary_key]
+        params = Params()
+        values = ", ".join(
+            params.column(self._server_table[server], value[k], comparison=False)
+            for k, server in zip(keys, targeted, strict=True)
+        )
+        action = "DO NOTHING"
+        updated = self._non_pk(value)
+        if upsert and updated:
+            sets = ", ".join(
+                f"{ident(server)} = {params.column(self._server_table[server], value[k], comparison=False)}"
+                for k, server in ((k, _server_column(self._table, k)) for k in updated)
+            )
+            action = f"DO UPDATE SET {sets}"
+        sql = (
+            f"INSERT INTO {ident(_server_name(self._table))} ({','.join(ident(c) for c in targeted)}) "
+            f"VALUES ({values}) ON CONFLICT ({', '.join(ident(c) for c in pk)}) {action}"
+        )
+        await self._tx.query(sql, params.values)
+
+    async def update(self, value: U) -> None:
+        row = _as_row(value)
+        targeted = [(k, _server_column(self._table, k)) for k in self._non_pk(row)]
+        if not targeted:
+            return
+        params = Params()
+        sets = ", ".join(
+            f"{ident(server)} = {params.column(self._server_table[server], row[k], comparison=False)}"
+            for k, server in targeted
+        )
+        where = self._pk_clause(params, row)
+        await self._tx.query(f"UPDATE {ident(_server_name(self._table))} SET {sets} WHERE {where}", params.values)
+
+    async def delete(self, value: K) -> None:
+        params = Params()
+        where = self._pk_clause(params, _as_row(value))
+        await self._tx.query(f"DELETE FROM {ident(_server_name(self._table))} WHERE {where}", params.values)
+
+
+class Mutate:
+    """`tx.mutate.issue` (or `tx.mutate["issue"]`) is the CRUD for the `issue` table, in client names."""
+
+    def __init__(self, schema: Schema, tx: DBTransaction[Any], server_schema: ServerSchema) -> None:
+        self._schema = schema
+        self._tx = tx
+        self._server_schema = server_schema
+
+    def __getitem__(self, table: str) -> TableCRUD[Any, Any, Any]:
+        table_schema = self._schema.tables[table]
+        return TableCRUD(table_schema, self._tx, self._server_schema[_server_name(table_schema)])
+
+    def __getattr__(self, table: str) -> TableCRUD[Any, Any, Any]:
+        try:
+            return self[table]
+        except KeyError:
+            raise AttributeError(table) from None

zero_server/server/pg_query_executor.py

@@ -0,0 +1,70 @@
+"""Run a ZQL query against Postgres and return what the client-side query would have.
+
+Ported from rocicorp/mono `packages/zero-server/src/pg-query-executor.ts` and `extractZqlResult` in
+`packages/z2s/src/compiler.ts` at zero/v1.10.0 (905d08516ba0caaf314cd28e93a5a47e8acdd482).
+Apache-2.0, Copyright Rocicorp.
+"""
+
+import json
+from typing import Any
+
+from zero_server.protocol.ast import AST
+from zero_server.query.builder import Format
+from zero_server.schema import Schema
+from zero_server.server.server_schema import ServerSchema
+from zero_server.server.transaction import DBTransaction, Row
+from zero_server.shared.js import js_keys
+from zero_server.z2s.compiler import ZQL_RESULT_KEY, compile_query
+
+_MAX_SAFE = 2**53 - 1
+
+
+class _Unsafe(int):
+    """An integer JavaScript cannot hold exactly. Upstream parses it as a bigint and refuses it."""
+
+
+def _parse_int(text: str) -> int:
+    value = int(text)
+    return _Unsafe(value) if abs(value) > _MAX_SAFE else value
+
+
+def _parse_float(text: str) -> int | float:
+    """A whole number written with a fraction, as `numeric` epoch milliseconds are, comes back an `int`.
+
+    JavaScript has one number type, so upstream cannot tell `1.0` from `1`; Python callers can.
+    """
+    value = float(text)
+    return int(value) if value.is_integer() and abs(value) <= _MAX_SAFE else value
+
+
+def _path_to_unsafe(value: Any) -> str | None:
+    match value:
+        case _Unsafe():
+            return f" = {int(value)}"
+        case list():
+            for i, item in enumerate(value):
+                if (path := _path_to_unsafe(item)) is not None:
+                    return f"[{i}]{path}"
+        case dict():
+            for key in js_keys(value):
+                if (path := _path_to_unsafe(value[key])) is not None:
+                    return f"['{key}']{path}"
+    return None
+
+
+def extract_zql_result(rows: list[Row]) -> Any:
+    result = json.loads(rows[0][ZQL_RESULT_KEY], parse_int=_parse_int, parse_float=_parse_float)
+    if (path := _path_to_unsafe(result)) is not None:
+        raise Exception(f"Value exceeds safe Number range. {path}")
+    return result
+
+
+async def execute_postgres_query(
+    tx: DBTransaction[Any], ast: AST, format: Format, schema: Schema, server_schema: ServerSchema
+) -> Any:
+    """The query's rows, as lists and dicts in client names. A singular query with no row returns `None`."""
+    text, values = compile_query(server_schema, schema, ast, format)
+    rows = await tx.query(text, values)
+    if not rows and format.singular:
+        return None
+    return extract_zql_result(rows)