hayate-sql 0.1.0__tar.gz

hayate_sql-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Hayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hayate_sql-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: hayate-sql
+Version: 0.1.0
+Summary: SQL-first query contracts for Python, PostgreSQL, SQLite, and Cloudflare D1
+Keywords: hayate,sql,postgresql,sqlite,cloudflare-d1
+Author: Yusuke Hayashi
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Dist: asyncpg>=0.30 ; extra == 'postgres'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/hayatepy/hayate-sql
+Project-URL: Documentation, https://github.com/hayatepy/hayate-sql#readme
+Project-URL: Changelog, https://github.com/hayatepy/hayate-sql/blob/main/CHANGELOG.md
+Provides-Extra: postgres
+Description-Content-Type: text/markdown
+
+# hayate-sql
+
+Native SQL with a checked, typed execution boundary — not an ORM and not a
+query builder.
+
+`hayate-sql` keeps each database's SQL, placeholders, plans, and transaction
+semantics intact. A small contract above each statement adds named application
+arguments, result cardinality, result shape, timeout, and parameter-free
+telemetry.
+
+> **Status: alpha (0.1.x), typed.** SQLite, Cloudflare D1, and
+> asyncpg-compatible PostgreSQL execution are implemented. SQLite/D1 contracts
+> can be compiled against an in-memory schema; PostgreSQL contracts can be
+> prepared against an ephemeral PostgreSQL transaction. The design memo
+> (Japanese, per project convention) is in [DESIGN.md](DESIGN.md).
+
+## Install
+
+```sh
+uv add hayate-sql
+
+# Include asyncpg when PostgreSQL is the target.
+uv add "hayate-sql[postgres]"
+```
+
+## Write SQL
+
+One `.sql` file contains one database-native statement:
+
+```sql
+-- name: get_document :one?
+-- param: workspace_id str
+-- param: document_id UUID
+-- column: id UUID
+-- column: title str
+-- column: body str
+-- timeout: 50ms
+SELECT id, title, body
+FROM documents
+WHERE workspace_id = ?1
+  AND id = ?2
+```
+
+The placeholder syntax belongs to the target database. Use `?1` for
+SQLite/D1 and `$1` for PostgreSQL. The declared parameter order maps named
+Python arguments to those native positions.
+
+Cardinality is explicit:
+
+- `:one` — exactly one row
+- `:one?` — zero or one row
+- `:many` — zero or more rows
+- `:exec` — no result rows; returns `CommandResult`
+
+Supported contract types are `str`, `int`, `float`, `bool`, `bytes`, `object`,
+`Any`, `datetime`, `date`, `Decimal`, and `UUID`. Append `?` for a nullable
+value. Types generate Python annotations; runtime enforcement intentionally
+checks the result's column shape rather than pretending that SQLite and
+PostgreSQL use identical value representations. Declarations must therefore
+describe the target driver's returned Python values (for example, a raw
+SQLite boolean column is normally declared as `int` unless the SQL converts it).
+
+## Compile and generate
+
+Compile D1/SQLite SQL against the real schema without executing queries:
+
+```sh
+hayate-sql check queries/ --dialect d1 --schema schema.sql
+```
+
+For PostgreSQL, `prepare` every query inside a transaction that is always
+rolled back:
+
+```sh
+HAYATE_SQL_DATABASE_URL=postgresql://localhost/app_test \
+  hayate-sql check queries/postgres/ \
+  --dialect postgres \
+  --schema schema.sql
+```
+
+Generate a typed facade:
+
+```sh
+hayate-sql generate queries/ -o app/queries.py
+```
+
+The generated module intentionally uses only Python 3.12+ syntax and does not
+force postponed annotations. Run the project's formatter after generation
+when its style policy is stricter than the standard output.
+
+The generated function has named arguments and a `TypedDict` result:
+
+```python
+document = await queries.get_document(
+    database,
+    workspace_id=workspace_id,
+    document_id=document_id,
+)
+```
+
+Generated code is a build artifact. SQL remains the source of truth.
+
+### Check against migration history
+
+When forward-only SQL migrations are the schema source of truth, replay them
+in order before compiling the queries:
+
+```sh
+hayate-sql check queries/ --dialect d1 --migrations migrations/
+```
+
+Migration files use a fixed-width positive number followed by a lowercase
+description, for example `0001_create_documents.sql`. Gaps are allowed, while
+duplicate versions, mixed widths, malformed names, and empty migrations fail
+the check.
+
+The migrations run only in hayate-sql's disposable check database. Applying
+them to development, staging, or production remains the responsibility of the
+database-native tool, such as `wrangler d1 migrations apply` or Alembic.
+
+## Execute
+
+### SQLite
+
+```python
+from hayate_sql.adapters import SQLiteDatabase
+
+async with SQLiteDatabase("app.db") as database:
+    async with database.transaction(mode="immediate"):
+        await queries.create_document(
+            database,
+            document_id=document_id,
+            title=title,
+        )
+```
+
+### Cloudflare D1
+
+```python
+from hayate_sql.adapters import D1Database
+
+database = D1Database(context.env.DB)
+
+# D1 consistency is explicit rather than hidden behind a generic transaction.
+session = database.with_session("first-primary")
+document = await queries.get_document(
+    session,
+    workspace_id=workspace_id,
+    document_id=document_id,
+)
+bookmark = session.bookmark()
+```
+
+The repository's reproducible workerd probe builds the 0.1.0 wheel, injects
+that wheel into the Python Workers bundle, applies a real local D1 migration,
+and executes `:one`, `:one?`, `:many`, and `:exec`:
+
+```sh
+bash scripts/check_workers_d1.sh
+```
+
+The same probe asserts that telemetry contains neither SQL text nor a sentinel
+bound value.
+
+### PostgreSQL
+
+```python
+import asyncpg
+
+from hayate_sql.adapters import AsyncpgDatabase
+
+connection = await asyncpg.connect(dsn)
+database = AsyncpgDatabase(connection)
+
+# Delegates to asyncpg's native transaction context.
+async with database.transaction(isolation="serializable"):
+    await queries.update_document(database, document_id=document_id, title=title)
+```
+
+## Observe without leaking parameters
+
+An observer receives only the query name, contract fingerprint, duration,
+success, row count, and error type. SQL text and bound values are deliberately
+absent.
+
+```python
+def observe(event):
+    metrics.histogram("db.query.duration", event.duration_ms, query=event.name)
+
+
+database = SQLiteDatabase("app.db", observer=observe)
+```
+
+## Non-goals
+
+- ORM models, identity maps, lazy relations, or repositories
+- a database-independent SQL DSL or query builder
+- SQL dialect translation
+- a universal transaction abstraction
+- production migration application, implicit schema migration, or write retries
+
+## License
+
+MIT

hayate_sql-0.1.0/README.md

@@ -0,0 +1,204 @@
+# hayate-sql
+
+Native SQL with a checked, typed execution boundary — not an ORM and not a
+query builder.
+
+`hayate-sql` keeps each database's SQL, placeholders, plans, and transaction
+semantics intact. A small contract above each statement adds named application
+arguments, result cardinality, result shape, timeout, and parameter-free
+telemetry.
+
+> **Status: alpha (0.1.x), typed.** SQLite, Cloudflare D1, and
+> asyncpg-compatible PostgreSQL execution are implemented. SQLite/D1 contracts
+> can be compiled against an in-memory schema; PostgreSQL contracts can be
+> prepared against an ephemeral PostgreSQL transaction. The design memo
+> (Japanese, per project convention) is in [DESIGN.md](DESIGN.md).
+
+## Install
+
+```sh
+uv add hayate-sql
+
+# Include asyncpg when PostgreSQL is the target.
+uv add "hayate-sql[postgres]"
+```
+
+## Write SQL
+
+One `.sql` file contains one database-native statement:
+
+```sql
+-- name: get_document :one?
+-- param: workspace_id str
+-- param: document_id UUID
+-- column: id UUID
+-- column: title str
+-- column: body str
+-- timeout: 50ms
+SELECT id, title, body
+FROM documents
+WHERE workspace_id = ?1
+  AND id = ?2
+```
+
+The placeholder syntax belongs to the target database. Use `?1` for
+SQLite/D1 and `$1` for PostgreSQL. The declared parameter order maps named
+Python arguments to those native positions.
+
+Cardinality is explicit:
+
+- `:one` — exactly one row
+- `:one?` — zero or one row
+- `:many` — zero or more rows
+- `:exec` — no result rows; returns `CommandResult`
+
+Supported contract types are `str`, `int`, `float`, `bool`, `bytes`, `object`,
+`Any`, `datetime`, `date`, `Decimal`, and `UUID`. Append `?` for a nullable
+value. Types generate Python annotations; runtime enforcement intentionally
+checks the result's column shape rather than pretending that SQLite and
+PostgreSQL use identical value representations. Declarations must therefore
+describe the target driver's returned Python values (for example, a raw
+SQLite boolean column is normally declared as `int` unless the SQL converts it).
+
+## Compile and generate
+
+Compile D1/SQLite SQL against the real schema without executing queries:
+
+```sh
+hayate-sql check queries/ --dialect d1 --schema schema.sql
+```
+
+For PostgreSQL, `prepare` every query inside a transaction that is always
+rolled back:
+
+```sh
+HAYATE_SQL_DATABASE_URL=postgresql://localhost/app_test \
+  hayate-sql check queries/postgres/ \
+  --dialect postgres \
+  --schema schema.sql
+```
+
+Generate a typed facade:
+
+```sh
+hayate-sql generate queries/ -o app/queries.py
+```
+
+The generated module intentionally uses only Python 3.12+ syntax and does not
+force postponed annotations. Run the project's formatter after generation
+when its style policy is stricter than the standard output.
+
+The generated function has named arguments and a `TypedDict` result:
+
+```python
+document = await queries.get_document(
+    database,
+    workspace_id=workspace_id,
+    document_id=document_id,
+)
+```
+
+Generated code is a build artifact. SQL remains the source of truth.
+
+### Check against migration history
+
+When forward-only SQL migrations are the schema source of truth, replay them
+in order before compiling the queries:
+
+```sh
+hayate-sql check queries/ --dialect d1 --migrations migrations/
+```
+
+Migration files use a fixed-width positive number followed by a lowercase
+description, for example `0001_create_documents.sql`. Gaps are allowed, while
+duplicate versions, mixed widths, malformed names, and empty migrations fail
+the check.
+
+The migrations run only in hayate-sql's disposable check database. Applying
+them to development, staging, or production remains the responsibility of the
+database-native tool, such as `wrangler d1 migrations apply` or Alembic.
+
+## Execute
+
+### SQLite
+
+```python
+from hayate_sql.adapters import SQLiteDatabase
+
+async with SQLiteDatabase("app.db") as database:
+    async with database.transaction(mode="immediate"):
+        await queries.create_document(
+            database,
+            document_id=document_id,
+            title=title,
+        )
+```
+
+### Cloudflare D1
+
+```python
+from hayate_sql.adapters import D1Database
+
+database = D1Database(context.env.DB)
+
+# D1 consistency is explicit rather than hidden behind a generic transaction.
+session = database.with_session("first-primary")
+document = await queries.get_document(
+    session,
+    workspace_id=workspace_id,
+    document_id=document_id,
+)
+bookmark = session.bookmark()
+```
+
+The repository's reproducible workerd probe builds the 0.1.0 wheel, injects
+that wheel into the Python Workers bundle, applies a real local D1 migration,
+and executes `:one`, `:one?`, `:many`, and `:exec`:
+
+```sh
+bash scripts/check_workers_d1.sh
+```
+
+The same probe asserts that telemetry contains neither SQL text nor a sentinel
+bound value.
+
+### PostgreSQL
+
+```python
+import asyncpg
+
+from hayate_sql.adapters import AsyncpgDatabase
+
+connection = await asyncpg.connect(dsn)
+database = AsyncpgDatabase(connection)
+
+# Delegates to asyncpg's native transaction context.
+async with database.transaction(isolation="serializable"):
+    await queries.update_document(database, document_id=document_id, title=title)
+```
+
+## Observe without leaking parameters
+
+An observer receives only the query name, contract fingerprint, duration,
+success, row count, and error type. SQL text and bound values are deliberately
+absent.
+
+```python
+def observe(event):
+    metrics.histogram("db.query.duration", event.duration_ms, query=event.name)
+
+
+database = SQLiteDatabase("app.db", observer=observe)
+```
+
+## Non-goals
+
+- ORM models, identity maps, lazy relations, or repositories
+- a database-independent SQL DSL or query builder
+- SQL dialect translation
+- a universal transaction abstraction
+- production migration application, implicit schema migration, or write retries
+
+## License
+
+MIT

hayate_sql-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["uv_build>=0.9,<1"]
+build-backend = "uv_build"
+
+[project]
+name = "hayate-sql"
+version = "0.1.0"
+description = "SQL-first query contracts for Python, PostgreSQL, SQLite, and Cloudflare D1"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yusuke Hayashi" }]
+keywords = ["hayate", "sql", "postgresql", "sqlite", "cloudflare-d1"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.30"]
+
+[project.scripts]
+hayate-sql = "hayate_sql.__main__:entrypoint"
+
+[project.urls]
+Repository = "https://github.com/hayatepy/hayate-sql"
+Documentation = "https://github.com/hayatepy/hayate-sql#readme"
+Changelog = "https://github.com/hayatepy/hayate-sql/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.18",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.25",
+  "ruff>=0.9",
+  "workers-py==1.15.0",
+  "workers-runtime-sdk==1.6.3",
+]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]

hayate_sql-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"]