hayate-sql 0.1.0__py3-none-any.whl

hayate_sql/__init__.py

@@ -0,0 +1,36 @@
+"""hayate-sql: SQL-first query contracts, not an ORM."""
+
+from .contract import (
+    Cardinality,
+    CardinalityError,
+    Column,
+    Parameter,
+    Query,
+    QueryArgumentError,
+    QueryContractError,
+    RowShapeError,
+)
+from .database import CommandResult, Database, Observer, QueryEvent, Row
+from .parser import QueryParseError, load_queries, parse_query
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cardinality",
+    "CardinalityError",
+    "Column",
+    "CommandResult",
+    "Database",
+    "Observer",
+    "Parameter",
+    "Query",
+    "QueryArgumentError",
+    "QueryContractError",
+    "QueryEvent",
+    "QueryParseError",
+    "Row",
+    "RowShapeError",
+    "__version__",
+    "load_queries",
+    "parse_query",
+]

hayate_sql/__main__.py

@@ -0,0 +1,105 @@
+"""The ``hayate-sql`` command line."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from .check import CheckFailure, check_postgres, check_sqlite
+from .generate import generate_module
+from .migrations import load_migrations
+from .parser import load_queries
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        queries = load_queries([Path(item) for item in args.paths])
+        if args.command == "generate":
+            output = generate_module([query for _, query in queries])
+            Path(args.output).write_text(output)
+            print(f"generated {len(queries)} queries in {args.output}")
+            return 0
+
+        schemas = [Path(path).read_text() for path in args.schema]
+        migrations = load_migrations(Path(args.migrations)) if args.migrations else ()
+        if args.dialect in ("sqlite", "d1"):
+            failures = check_sqlite(
+                queries,
+                schemas=schemas,
+                migrations=migrations,
+                d1=args.dialect == "d1",
+            )
+        else:
+            database_url = args.database_url or os.environ.get("HAYATE_SQL_DATABASE_URL")
+            if database_url is None:
+                parser.error("PostgreSQL checks require --database-url or HAYATE_SQL_DATABASE_URL")
+            failures = asyncio.run(
+                check_postgres(
+                    queries,
+                    database_url=database_url,
+                    schemas=schemas,
+                    migrations=migrations,
+                )
+            )
+        return _report(failures, len(queries))
+    except (OSError, RuntimeError, ValueError) as error:
+        print(f"hayate-sql: {error}", file=sys.stderr)
+        return 1
+
+
+def entrypoint() -> NoReturn:
+    raise SystemExit(main())
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hayate-sql",
+        description="Compile SQL contracts and generate typed Python accessors.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    generate = commands.add_parser("generate", help="generate a typed Python module")
+    generate.add_argument("paths", nargs="+", help=".sql files or directories")
+    generate.add_argument("-o", "--output", required=True, help="generated .py path")
+
+    check = commands.add_parser("check", help="compile queries against a real schema")
+    check.add_argument("paths", nargs="+", help=".sql files or directories")
+    check.add_argument("--dialect", choices=("sqlite", "d1", "postgres"), default="sqlite")
+    schema_source = check.add_mutually_exclusive_group()
+    schema_source.add_argument(
+        "--schema",
+        action="append",
+        default=[],
+        metavar="FILE",
+        help="schema SQL to apply before checking; repeatable",
+    )
+    schema_source.add_argument(
+        "--migrations",
+        metavar="DIRECTORY",
+        help="ordered SQL migrations to replay in a disposable check database",
+    )
+    check.add_argument(
+        "--database-url",
+        help="ephemeral PostgreSQL URL; prefer HAYATE_SQL_DATABASE_URL to avoid shell history",
+    )
+    return parser
+
+
+def _report(failures: list[CheckFailure], total: int) -> int:
+    if not failures:
+        print(f"checked {total} queries")
+        return 0
+    for failure in failures:
+        print(f"{failure.path}: {failure.query_name}: {failure.message}", file=sys.stderr)
+    print(f"{len(failures)} of {total} queries failed", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    entrypoint()

hayate_sql/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Database-native hayate-sql adapters."""
+
+from .d1 import D1Database
+from .postgres import AsyncpgDatabase
+from .sqlite import SQLiteDatabase
+
+__all__ = ["AsyncpgDatabase", "D1Database", "SQLiteDatabase"]

hayate_sql/adapters/d1.py

@@ -0,0 +1,72 @@
+"""Cloudflare D1 adapter using the binding's native prepare/bind API."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from ..database import BaseDatabase, CommandResult, Observer, Row
+
+
+class D1Database(BaseDatabase):
+    """Wrap a D1Database or D1DatabaseSession JS binding.
+
+    Transactions are intentionally absent: D1's Sessions/bookmarks and batch
+    behavior are not equivalent to a PostgreSQL or SQLite transaction.
+    """
+
+    def __init__(self, database: Any, *, observer: Observer | None = None) -> None:
+        super().__init__(observer=observer)
+        self.raw = database
+
+    def with_session(self, constraint_or_bookmark: str | None = None) -> D1Database:
+        session = (
+            self.raw.withSession()
+            if constraint_or_bookmark is None
+            else self.raw.withSession(constraint_or_bookmark)
+        )
+        return D1Database(session, observer=self.observer)
+
+    def bookmark(self) -> str | None:
+        getter = getattr(self.raw, "getBookmark", None)
+        if getter is None:
+            raise RuntimeError("bookmark() requires a D1DatabaseSession")
+        value = getter()
+        return None if value is None else str(value)
+
+    async def _fetch(self, sql: str, values: Sequence[Any]) -> list[Row]:
+        statement = self._statement(sql, values)
+        result = await statement.all()
+        raw_rows = _get(result, "results")
+        if raw_rows is None:
+            return []
+        converted = _to_py(raw_rows)
+        return [dict(_to_py(row)) for row in converted]
+
+    async def _execute(self, sql: str, values: Sequence[Any]) -> CommandResult:
+        statement = self._statement(sql, values)
+        runner = getattr(statement, "run", None)
+        result = await (runner() if runner is not None else statement.all())
+        meta = _to_py(_get(result, "meta"))
+        changes = _get(meta, "changes")
+        return CommandResult(rows_affected=int(changes) if changes is not None else None)
+
+    def _statement(self, sql: str, values: Sequence[Any]) -> Any:
+        statement = self.raw.prepare(sql)
+        return statement.bind(*values) if values else statement
+
+
+def _to_py(value: Any) -> Any:
+    if value is None:
+        return None
+    converter = getattr(value, "to_py", None)
+    return converter() if converter is not None else value
+
+
+def _get(value: Any, name: str) -> Any:
+    if value is None:
+        return None
+    converted = _to_py(value)
+    if isinstance(converted, dict):
+        return converted.get(name)
+    return getattr(converted, name, None)

hayate_sql/adapters/postgres.py

@@ -0,0 +1,36 @@
+"""PostgreSQL adapter for asyncpg Connection/Pool-compatible objects."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from ..database import BaseDatabase, CommandResult, Observer, Row
+
+_AFFECTED_ROWS = re.compile(r"(?:^|\s)(\d+)$")
+
+
+class AsyncpgDatabase(BaseDatabase):
+    """Keep PostgreSQL SQL and asyncpg's native transaction model intact."""
+
+    def __init__(self, connection_or_pool: Any, *, observer: Observer | None = None) -> None:
+        super().__init__(observer=observer)
+        self.raw = connection_or_pool
+
+    def transaction(self, **options: Any) -> Any:
+        """Delegate to an asyncpg Connection's native transaction context."""
+
+        transaction = getattr(self.raw, "transaction", None)
+        if transaction is None:
+            raise RuntimeError("transaction() requires an asyncpg Connection, not a Pool")
+        return transaction(**options)
+
+    async def _fetch(self, sql: str, values: Sequence[Any]) -> list[Row]:
+        rows = await self.raw.fetch(sql, *values)
+        return [dict(row) for row in rows]
+
+    async def _execute(self, sql: str, values: Sequence[Any]) -> CommandResult:
+        status = str(await self.raw.execute(sql, *values))
+        matched = _AFFECTED_ROWS.search(status)
+        return CommandResult(rows_affected=int(matched.group(1)) if matched else None)

hayate_sql/adapters/sqlite.py

@@ -0,0 +1,104 @@
+"""stdlib SQLite adapter with explicit SQLite transaction semantics."""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+import sys
+from collections.abc import AsyncIterator, Callable, Sequence
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Literal
+
+from ..database import BaseDatabase, CommandResult, Observer, Row
+
+
+class SQLiteDatabase(BaseDatabase):
+    def __init__(
+        self,
+        path: str | Path = ":memory:",
+        *,
+        observer: Observer | None = None,
+    ) -> None:
+        super().__init__(observer=observer)
+        self._connection = sqlite3.connect(
+            str(path),
+            check_same_thread=False,
+            isolation_level=None,
+        )
+        self._connection.row_factory = sqlite3.Row
+        self._connection.execute("PRAGMA foreign_keys = ON")
+        self._lock = asyncio.Lock()
+        self._transaction_owner: asyncio.Task[Any] | None = None
+
+    @property
+    def raw(self) -> sqlite3.Connection:
+        return self._connection
+
+    async def executescript(self, sql: str) -> None:
+        await self._serialized(lambda: self._connection.executescript(sql))
+
+    async def close(self) -> None:
+        await self._serialized(self._connection.close)
+
+    async def __aenter__(self) -> SQLiteDatabase:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()
+
+    @asynccontextmanager
+    async def transaction(
+        self,
+        *,
+        mode: Literal["deferred", "immediate", "exclusive"] = "deferred",
+    ) -> AsyncIterator[SQLiteDatabase]:
+        """Run calls through this adapter in one native SQLite transaction."""
+
+        if mode not in ("deferred", "immediate", "exclusive"):
+            raise ValueError("mode must be 'deferred', 'immediate', or 'exclusive'")
+        task = asyncio.current_task()
+        if task is None:
+            raise RuntimeError("SQLite transactions require an asyncio task")
+        if self._transaction_owner is task:
+            raise RuntimeError("nested SQLiteDatabase transactions are not supported")
+
+        await self._lock.acquire()
+        self._transaction_owner = task
+        try:
+            await self._call(lambda: self._connection.execute(f"BEGIN {mode.upper()}"))
+            try:
+                yield self
+            except BaseException:
+                await self._call(self._connection.rollback)
+                raise
+            else:
+                await self._call(self._connection.commit)
+        finally:
+            self._transaction_owner = None
+            self._lock.release()
+
+    async def _fetch(self, sql: str, values: Sequence[Any]) -> list[Row]:
+        def run() -> list[Row]:
+            cursor = self._connection.execute(sql, tuple(values))
+            return [dict(row) for row in cursor.fetchall()]
+
+        return await self._serialized(run)
+
+    async def _execute(self, sql: str, values: Sequence[Any]) -> CommandResult:
+        def run() -> CommandResult:
+            cursor = self._connection.execute(sql, tuple(values))
+            return CommandResult(rows_affected=max(cursor.rowcount, 0))
+
+        return await self._serialized(run)
+
+    async def _serialized[T](self, operation: Callable[[], T]) -> T:
+        if self._transaction_owner is asyncio.current_task():
+            return await self._call(operation)
+        async with self._lock:
+            return await self._call(operation)
+
+    async def _call[T](self, operation: Callable[[], T]) -> T:
+        if sys.platform == "emscripten":
+            return operation()
+        return await asyncio.to_thread(operation)

hayate_sql/check.py

@@ -0,0 +1,149 @@
+"""Database-backed compilation of SQL contracts."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Sequence
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+
+from .contract import Cardinality, Query
+from .migrations import Migration
+
+
+@dataclass(frozen=True, slots=True)
+class CheckFailure:
+    path: Path
+    query_name: str
+    message: str
+
+
+def check_sqlite(
+    queries: list[tuple[Path, Query]],
+    *,
+    schemas: Sequence[str] = (),
+    migrations: Sequence[Migration] = (),
+    d1: bool = False,
+) -> list[CheckFailure]:
+    """Compile queries against an in-memory SQLite/D1 schema without executing them."""
+
+    connection = sqlite3.connect(":memory:")
+    failures: list[CheckFailure] = []
+    try:
+        connection.execute("PRAGMA foreign_keys = ON")
+        for schema in schemas:
+            connection.executescript(schema)
+        for migration in migrations:
+            try:
+                connection.executescript(migration.sql)
+            except sqlite3.Error as error:
+                failures.append(
+                    CheckFailure(
+                        migration.path,
+                        f"migration {migration.version_text}",
+                        str(error),
+                    )
+                )
+                return failures
+        for path, query in queries:
+            if d1 and len(query.parameters) > 100:
+                failures.append(
+                    CheckFailure(
+                        path,
+                        query.name,
+                        f"D1 accepts at most 100 bound parameters, got {len(query.parameters)}",
+                    )
+                )
+                continue
+            values = (None,) * len(query.parameters)
+            try:
+                connection.execute(f"EXPLAIN {query.sql}", values)
+                if query.cardinality is not Cardinality.EXEC:
+                    _check_sqlite_columns(connection, query, values)
+            except (sqlite3.Error, ValueError) as error:
+                failures.append(CheckFailure(path, query.name, str(error)))
+    finally:
+        connection.close()
+    return failures
+
+
+async def check_postgres(
+    queries: list[tuple[Path, Query]],
+    *,
+    database_url: str,
+    schemas: Sequence[str] = (),
+    migrations: Sequence[Migration] = (),
+) -> list[CheckFailure]:
+    """Ask PostgreSQL to parse and describe every query, then roll all DDL back."""
+
+    try:
+        asyncpg = import_module("asyncpg")
+    except ImportError as error:
+        raise RuntimeError(
+            "PostgreSQL checks require the 'postgres' extra: uv add 'hayate-sql[postgres]'"
+        ) from error
+
+    connection = await asyncpg.connect(database_url)
+    failures: list[CheckFailure] = []
+    transaction = connection.transaction()
+    await transaction.start()
+    try:
+        for schema in schemas:
+            await connection.execute(schema)
+        for migration in migrations:
+            try:
+                await connection.execute(migration.sql)
+            except Exception as error:
+                failures.append(
+                    CheckFailure(
+                        migration.path,
+                        f"migration {migration.version_text}",
+                        str(error),
+                    )
+                )
+                return failures
+        for path, query in queries:
+            savepoint = connection.transaction()
+            await savepoint.start()
+            try:
+                prepared = await connection.prepare(query.sql)
+                if query.cardinality is not Cardinality.EXEC:
+                    actual = tuple(attribute.name for attribute in prepared.get_attributes())
+                    _ensure_columns(query, actual)
+            except Exception as error:
+                failures.append(CheckFailure(path, query.name, str(error)))
+            finally:
+                await savepoint.rollback()
+    finally:
+        await transaction.rollback()
+        await connection.close()
+    return failures
+
+
+def _check_sqlite_columns(
+    connection: sqlite3.Connection,
+    query: Query,
+    values: tuple[None, ...],
+) -> None:
+    sql = query.sql.rstrip().removesuffix(";")
+    try:
+        cursor = connection.execute(
+            f"SELECT * FROM ({sql}) AS _hayate_sql_contract LIMIT 0",
+            values,
+        )
+    except sqlite3.Error:
+        # SQLite cannot wrap every valid row-returning statement (for example,
+        # INSERT ... RETURNING). EXPLAIN above still validates those statements;
+        # their row shape remains protected at runtime.
+        return
+    actual = tuple(item[0] for item in cursor.description or ())
+    _ensure_columns(query, actual)
+
+
+def _ensure_columns(query: Query, actual: tuple[str, ...]) -> None:
+    expected = tuple(column.name for column in query.columns)
+    if actual != expected:
+        raise ValueError(
+            f"declared columns {expected!r} do not match database result columns {actual!r}"
+        )

hayate_sql/contract.py

@@ -0,0 +1,111 @@
+"""The immutable query contract.
+
+SQL remains native to its database. This module only describes the boundary
+around it: parameter order, expected result shape, cardinality, and deadline.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class Cardinality(StrEnum):
+    ONE = "one"
+    MAYBE_ONE = "one?"
+    MANY = "many"
+    EXEC = "exec"
+
+
+@dataclass(frozen=True, slots=True)
+class Parameter:
+    name: str
+    annotation: str
+
+
+@dataclass(frozen=True, slots=True)
+class Column:
+    name: str
+    annotation: str
+
+
+@dataclass(frozen=True, slots=True)
+class Query:
+    """A parsed, database-native SQL statement and its execution contract."""
+
+    name: str
+    sql: str
+    cardinality: Cardinality
+    parameters: tuple[Parameter, ...] = ()
+    columns: tuple[Column, ...] = ()
+    timeout_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("query name cannot be empty")
+        if not self.sql.strip():
+            raise ValueError(f"{self.name}: SQL cannot be empty")
+        if self.timeout_ms is not None and self.timeout_ms <= 0:
+            raise ValueError(f"{self.name}: timeout must be positive")
+
+        parameter_names = [parameter.name for parameter in self.parameters]
+        column_names = [column.name for column in self.columns]
+        if len(parameter_names) != len(set(parameter_names)):
+            raise ValueError(f"{self.name}: duplicate parameter name")
+        if len(column_names) != len(set(column_names)):
+            raise ValueError(f"{self.name}: duplicate column name")
+        if self.cardinality is Cardinality.EXEC and self.columns:
+            raise ValueError(f"{self.name}: :exec queries cannot declare columns")
+        if self.cardinality is not Cardinality.EXEC and not self.columns:
+            raise ValueError(f"{self.name}: row-returning queries must declare columns")
+
+    @property
+    def fingerprint(self) -> str:
+        """Stable identifier for telemetry; contains neither argument values nor secrets."""
+
+        contract = {
+            "name": self.name,
+            "sql": self.sql,
+            "cardinality": self.cardinality,
+            "parameters": [(item.name, item.annotation) for item in self.parameters],
+            "columns": [(item.name, item.annotation) for item in self.columns],
+            "timeout_ms": self.timeout_ms,
+        }
+        encoded = json.dumps(contract, separators=(",", ":"), sort_keys=True).encode()
+        return hashlib.sha256(encoded).hexdigest()[:16]
+
+    def bind(self, values: Mapping[str, Any]) -> tuple[Any, ...]:
+        """Turn named application arguments into the SQL file's positional order."""
+
+        expected = {parameter.name for parameter in self.parameters}
+        actual = set(values)
+        missing = expected - actual
+        extra = actual - expected
+        if missing or extra:
+            details: list[str] = []
+            if missing:
+                details.append(f"missing {', '.join(sorted(missing))}")
+            if extra:
+                details.append(f"unexpected {', '.join(sorted(extra))}")
+            raise QueryArgumentError(f"{self.name}: {'; '.join(details)}")
+        return tuple(values[parameter.name] for parameter in self.parameters)
+
+
+class QueryContractError(RuntimeError):
+    """Base class for failures at the SQL contract boundary."""
+
+
+class QueryArgumentError(QueryContractError):
+    """Arguments do not match the declared query parameters."""
+
+
+class CardinalityError(QueryContractError):
+    """The database returned a different number of rows than promised."""
+
+
+class RowShapeError(QueryContractError):
+    """The database returned columns that differ from the declared row."""