sqlproof 0.1.0a1__py3-none-any.whl

sqlproof/__init__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlproof._version import __version__
+
+if TYPE_CHECKING:
+    from sqlproof.config import ExternalTableSpec, SqlProofConfig
+    from sqlproof.core import SqlProof
+    from sqlproof.runners import sqlproof
+
+__all__ = ["ExternalTableSpec", "SqlProof", "SqlProofConfig", "__version__", "sqlproof"]
+
+
+def __getattr__(name: str) -> object:
+    if name == "SqlProof":
+        from sqlproof.core import SqlProof
+
+        return SqlProof
+    if name == "SqlProofConfig":
+        from sqlproof.config import SqlProofConfig
+
+        return SqlProofConfig
+    if name == "ExternalTableSpec":
+        from sqlproof.config import ExternalTableSpec
+
+        return ExternalTableSpec
+    if name == "sqlproof":
+        from sqlproof.runners import sqlproof
+
+        return sqlproof
+    raise AttributeError(name)

sqlproof/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a1"

sqlproof/cli.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from sqlproof._version import __version__
+from sqlproof.coverage.schema_shape import summarize_dataset_shape
+from sqlproof.reporter.console import format_failure
+from sqlproof.schema.model import Column, SchemaInfo, Table
+from sqlproof.schema.parse_sql import parse_schema_sql
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sqlproof")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    subcommands.add_parser("version")
+
+    introspect = subcommands.add_parser("introspect")
+    introspect.add_argument("--schema-file", type=Path)
+    introspect.add_argument("--dsn")
+    introspect.add_argument("--format", choices=["json", "text"], default="text")
+
+    generate_types_parser = subcommands.add_parser("generate-types")
+    generate_types_parser.add_argument("--schema-file", type=Path, required=True)
+    generate_types_parser.add_argument("--output", type=Path)
+    generate_types_parser.add_argument(
+        "--style", choices=["typeddict", "dataclass", "pydantic"], default="typeddict"
+    )
+
+    replay = subcommands.add_parser("replay")
+    replay.add_argument("counterexample", type=Path)
+
+    report = subcommands.add_parser("report")
+    report.add_argument("counterexample", type=Path)
+    report.add_argument("--format", choices=["json", "text"], default="text")
+
+    run = subcommands.add_parser("run")
+    run.add_argument("test_path")
+    run.add_argument("pytest_options", nargs=argparse.REMAINDER)
+
+    subcommands.add_parser("clean-orphans")
+
+    args = parser.parse_args(argv)
+    if args.command == "version":
+        print(f"sqlproof {__version__}")
+        return 0
+    if args.command == "introspect":
+        if args.schema_file is None and args.dsn is None:
+            parser.error("one of --schema-file or --dsn is required")
+        if args.schema_file is not None:
+            schema = parse_schema_sql(args.schema_file.read_text(encoding="utf-8"))
+        else:
+            from sqlproof import SqlProof
+
+            schema = SqlProof.from_connection_string(str(args.dsn)).schema_info
+        if args.format == "json":
+            print(json.dumps(_schema_payload(schema), default=str))
+        else:
+            for table in schema.tables:
+                print(f"{table.qualified_name} ({len(table.columns)} columns)")
+        return 0
+    if args.command == "generate-types":
+        from sqlproof.types import generate_types
+
+        output = generate_types(args.schema_file, style=args.style)
+        if args.output:
+            args.output.write_text(output, encoding="utf-8")
+        else:
+            print(output)
+        return 0
+    if args.command == "replay":
+        payload = json.loads(args.counterexample.read_text(encoding="utf-8"))
+        print(format_failure(payload))
+        print(f"replay loaded {payload.get('property_name', 'counterexample')}")
+        return 0
+    if args.command == "report":
+        payload = json.loads(args.counterexample.read_text(encoding="utf-8"))
+        report_payload = _counterexample_report(payload)
+        if args.format == "json":
+            print(json.dumps(report_payload, default=str))
+        else:
+            print(format_failure(payload))
+        return 0
+    if args.command == "run":
+        import pytest
+
+        return int(pytest.main([args.test_path, *args.pytest_options]))
+    if args.command == "clean-orphans":
+        print("No orphaned SqlProof containers found.")
+        return 0
+    return 1
+
+
+def _schema_payload(schema: SchemaInfo) -> dict[str, object]:
+    return {"tables": [_table_payload(table) for table in schema.tables]}
+
+
+def _table_payload(table: Table) -> dict[str, object]:
+    return {
+        "schema": table.schema,
+        "name": table.name,
+        "columns": [_column_payload(column) for column in table.columns],
+        "primary_key": list(table.primary_key),
+        "unique_constraints": [list(columns) for columns in table.unique_constraints],
+        "checks": [check.expression for check in table.check_constraints],
+        "foreign_keys": [
+            {
+                "columns": list(foreign_key.columns),
+                "referenced_table": foreign_key.referenced_table,
+                "referenced_columns": list(foreign_key.referenced_columns),
+                "on_delete": foreign_key.on_delete,
+                "on_update": foreign_key.on_update,
+            }
+            for foreign_key in table.foreign_keys
+        ],
+    }
+
+
+def _column_payload(column: Column) -> dict[str, object]:
+    return {
+        "name": column.name,
+        "type": column.type.name,
+        "nullable": column.nullable,
+        "default": column.default,
+        "is_generated": column.is_generated,
+        "identity": column.identity,
+    }
+
+
+def _counterexample_report(payload: dict[str, object]) -> dict[str, object]:
+    dataset = payload.get("dataset")
+    shape = (
+        summarize_dataset_shape(cast(dict[str, list[dict[str, Any]]], dataset))
+        if isinstance(dataset, dict)
+        else {}
+    )
+    return {
+        "property_name": payload.get("property_name", "counterexample"),
+        "schema_fingerprint": payload.get("schema_fingerprint"),
+        "row_context": payload.get("row_context", {}),
+        "failure": payload.get("failure", {}),
+        "shape": shape,
+    }
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main(sys.argv[1:]))

sqlproof/client.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Generator
+from contextlib import AbstractContextManager, contextmanager
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+from typing import Any, Protocol, TypeVar, cast
+
+from sqlproof.exceptions import SqlProofMappingError, SqlProofUsageError
+
+T = TypeVar("T")
+
+
+class SqlProofClient(Protocol):
+    def query(self, sql: str, *params: Any) -> list[dict[str, Any]]: ...
+
+    def query_typed(self, sql: str, model: type[T], *params: Any) -> list[T]: ...
+
+    def scalar(self, sql: str, *params: Any) -> Any: ...
+
+    def execute(self, sql: str, *params: Any) -> int: ...
+
+    def execute_file(self, path: str) -> None: ...
+
+    def savepoint(self) -> AbstractContextManager[None]: ...
+
+    def get_generated_data(self) -> dict[str, list[dict[str, Any]]]: ...
+
+
+class InMemorySqlProofClient:
+    def __init__(self, dataset: dict[str, list[dict[str, Any]]]) -> None:
+        self._dataset = dataset
+
+    def query(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        del params
+        match = re.search(r"SELECT\s+(?P<columns>.*?)\s+FROM\s+(?P<table>\w+)", sql, re.I | re.S)
+        if match is None:
+            return []
+        table = match.group("table")
+        rows = self._dataset.get(table, [])
+        columns_sql = match.group("columns").strip()
+        if columns_sql == "*":
+            return [dict(row) for row in rows]
+        columns = [_clean_selected_column(part) for part in columns_sql.split(",")]
+        return [{column: row.get(column) for column in columns} for row in rows]
+
+    def query_typed(self, sql: str, model: type[T], *params: Any) -> list[T]:
+        rows = self.query(sql, *params)
+        return [_map_row(row, model) for row in rows]
+
+    def scalar(self, sql: str, *params: Any) -> Any:
+        rows = self.query(sql, *params)
+        if not rows:
+            return None
+        return next(iter(rows[0].values()))
+
+    def execute(self, sql: str, *params: Any) -> int:
+        del sql, params
+        return 0
+
+    def execute_file(self, path: str) -> None:
+        del path
+
+    @contextmanager
+    def savepoint(self) -> Generator[None]:
+        yield
+
+    def get_generated_data(self) -> dict[str, list[dict[str, Any]]]:
+        return self._dataset
+
+
+class PsycopgSqlProofClient:
+    def __init__(
+        self,
+        connection: Any,
+        *,
+        dataset: dict[str, list[dict[str, Any]]] | None = None,
+    ) -> None:
+        self._connection = connection
+        self._dataset = dataset or {}
+
+    def query(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        cursor = self._connection.execute(sql, params)
+        return [dict(row) for row in cursor.fetchall()]
+
+    def query_typed(self, sql: str, model: type[T], *params: Any) -> list[T]:
+        rows = self.query(sql, *params)
+        return [_map_row(row, model) for row in rows]
+
+    def scalar(self, sql: str, *params: Any) -> Any:
+        rows = self.query(sql, *params)
+        if not rows:
+            return None
+        return next(iter(rows[0].values()))
+
+    def execute(self, sql: str, *params: Any) -> int:
+        cursor = self._connection.execute(sql, params)
+        return int(cursor.rowcount)
+
+    def execute_file(self, path: str | Path) -> None:
+        sql = Path(path).read_text(encoding="utf-8")
+        for statement in _split_sql_statements(sql):
+            self.execute(statement)
+
+    @contextmanager
+    def savepoint(self) -> Generator[None]:
+        name = "sqlproof_client"
+        self.execute(f"SAVEPOINT {name}")
+        try:
+            yield
+        except BaseException:
+            self.execute(f"ROLLBACK TO SAVEPOINT {name}")
+            raise
+        finally:
+            self.execute(f"RELEASE SAVEPOINT {name}")
+
+    def get_generated_data(self) -> dict[str, list[dict[str, Any]]]:
+        return self._dataset
+
+
+def _split_sql_statements(sql: str) -> list[str]:
+    statements = [statement.strip() for statement in sql.split(";")]
+    return [statement for statement in statements if statement]
+
+
+def _clean_selected_column(sql: str) -> str:
+    value = sql.strip()
+    if "." in value:
+        value = value.rsplit(".", 1)[1]
+    if " AS " in value.upper():
+        value = re.split(r"\s+AS\s+", value, flags=re.I)[-1]
+    return value.strip().strip('"')
+
+
+def _map_row(row: dict[str, Any], model: type[T]) -> T:
+    detectors = [
+        hasattr(model, "__pydantic_fields__"),
+        is_dataclass(model),
+        hasattr(model, "__required_keys__") or hasattr(model, "__optional_keys__"),
+    ]
+    if sum(detectors) != 1:
+        raise SqlProofUsageError("Ambiguous or unsupported row model type.")
+    if hasattr(model, "__pydantic_fields__"):
+        try:
+            return model.model_validate(row)  # type: ignore[attr-defined,no-any-return]
+        except Exception as exc:  # pragma: no cover - exercised when pydantic is installed
+            raise SqlProofMappingError(str(exc)) from exc
+    if is_dataclass(model):
+        names = {field.name for field in fields(model)}
+        missing = {field.name for field in fields(model) if field.name not in row}
+        if missing:
+            raise SqlProofMappingError(f"Missing required fields: {', '.join(sorted(missing))}")
+        return model(**{name: row[name] for name in names if name in row})
+    required = cast("set[str]", getattr(model, "__required_keys__", set[str]()))
+    missing = required - row.keys()
+    if missing:
+        raise SqlProofMappingError(f"Missing required fields: {', '.join(sorted(missing))}")
+    return dict(row)  # type: ignore[return-value]

sqlproof/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from hypothesis.strategies import SearchStrategy
+
+from sqlproof.exceptions import SqlProofUsageError
+
+if TYPE_CHECKING:
+    from sqlproof.client import SqlProofClient
+
+ExternalSeed = Callable[["SqlProofClient"], None] | Callable[["SqlProofClient", int], None]
+SizeSpec = int | SearchStrategy[int]
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalTableSpec:
+    primary_key: str
+    sample: Callable[[SqlProofClient], Sequence[object]]
+    seed: ExternalSeed | None = None
+    seed_count: SizeSpec | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SqlProofConfig:
+    connection_string: str | None = None
+    schema: str = "public"
+    schema_file: str | Path | None = None
+    image: str = "postgres:16"
+    reuse_container: bool = True
+    transaction_per_run: bool = True
+    seed: Callable[[SqlProofClient], None] | None = None
+    external_tables: Mapping[str, ExternalTableSpec] | None = None
+
+    def __post_init__(self) -> None:
+        sources = [self.connection_string is not None, self.schema_file is not None]
+        if sum(sources) != 1:
+            msg = "Exactly one of connection_string or schema_file must be provided."
+            raise SqlProofUsageError(msg)

sqlproof/contrib/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__all__ = []

sqlproof/contrib/supabase.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from importlib import import_module
+from typing import Any, cast
+
+from sqlproof.client import SqlProofClient
+
+CLAIMS_GUC = "request.jwt.claims"
+
+
+@contextmanager
+def as_supabase_user(
+    db: SqlProofClient,
+    user_id: str,
+    *,
+    role: str = "authenticated",
+    extra_claims: Mapping[str, Any] | None = None,
+) -> Generator[None]:
+    """Run a block as a Supabase auth user by setting `request.jwt.claims`.
+
+    Sets the transaction-local `request.jwt.claims` GUC so that PostgREST/
+    Supabase helpers (`auth.uid()`, `auth.jwt()`, `auth.role()`) resolve to
+    the given user. The previous value of the GUC, if any, is restored on
+    exit, so nested invocations stack correctly.
+
+    Composable with `db.savepoint()`. Safe under exceptions.
+    """
+    prior = db.scalar("SELECT current_setting(%s, true)", CLAIMS_GUC)
+    claims: dict[str, Any] = {"sub": user_id, "role": role}
+    if extra_claims:
+        claims.update(extra_claims)
+    db.execute("SELECT set_config(%s, %s, true)", CLAIMS_GUC, json.dumps(claims))
+    try:
+        yield
+    finally:
+        restore_value = "" if prior in (None, "") else prior
+        db.execute("SELECT set_config(%s, %s, true)", CLAIMS_GUC, restore_value)
+
+
+def seed_supabase_test_users(
+    db: SqlProofClient | object,
+    count: int = 20,
+    *,
+    email_prefix: str = "sqlproof_",
+    email_domain: str = "test.invalid",
+    password: str = "test_password",
+) -> None:
+    """Create replaceable Supabase auth users for external table FK sampling."""
+    del db
+    if count < 0:
+        msg = "count must be non-negative."
+        raise ValueError(msg)
+
+    httpx = import_module("httpx")
+    service_role_key = os.environ["SUPABASE_SERVICE_ROLE_KEY"]
+    with httpx.Client(
+        base_url=os.environ["SUPABASE_URL"],
+        headers={"Authorization": f"Bearer {service_role_key}", "apikey": service_role_key},
+        timeout=5.0,
+    ) as admin:
+        response = admin.get("/auth/v1/admin/users")
+        response.raise_for_status()
+        existing = response.json()
+        existing_emails = {_email(user) for user in existing.get("users", [])}
+
+        for index in range(count):
+            email = f"{email_prefix}{index}@{email_domain}"
+            if email in existing_emails:
+                continue
+            create_response = admin.post(
+                "/auth/v1/admin/users",
+                json={
+                    "email": email,
+                    "password": password,
+                    "email_confirm": True,
+                },
+            )
+            create_response.raise_for_status()
+
+
+def seed_test_users_directly(
+    db: SqlProofClient,
+    count: int = 20,
+    *,
+    email_prefix: str = "sqlproof_",
+    email_domain: str = "test.invalid",
+) -> list[str]:
+    """Insert skeleton `auth.users` rows directly via SQL.
+
+    Returns the user_ids of all sqlproof test users (newly inserted plus any
+    pre-existing ones matching the email pattern). Idempotent: existing
+    emails are preserved via `ON CONFLICT (email) DO NOTHING`.
+
+    Use when the Supabase admin API is unavailable but the connection has
+    write access to `auth.users` (e.g. local Supabase).
+    """
+    if count < 0:
+        msg = "count must be non-negative."
+        raise ValueError(msg)
+
+    for index in range(count):
+        email = f"{email_prefix}{index}@{email_domain}"
+        db.execute(
+            """
+            INSERT INTO auth.users (id, aud, role, email)
+            SELECT gen_random_uuid(), 'authenticated', 'authenticated', %s
+            WHERE NOT EXISTS (SELECT 1 FROM auth.users WHERE email = %s)
+            """,
+            email,
+            email,
+        )
+
+    escaped_prefix = email_prefix.replace("_", r"\_")
+    rows = db.query(
+        r"""
+        SELECT id::text AS id
+        FROM auth.users
+        WHERE email LIKE %s ESCAPE '\'
+        ORDER BY email
+        """,
+        f"{escaped_prefix}%@{email_domain}",
+    )
+    return [row["id"] for row in rows]
+
+
+def _email(user: object) -> str:
+    if isinstance(user, Mapping):
+        user_mapping = cast(Mapping[str, object], user)
+        value = user_mapping.get("email")
+        if isinstance(value, str):
+            return value
+    return ""