hawkapi-sqlalchemy 0.1.0__py3-none-any.whl

hawkapi_sqlalchemy/__init__.py

@@ -0,0 +1,41 @@
+"""hawkapi-sqlalchemy — SQLAlchemy integration for HawkAPI.
+
+Async engines, multi-database routing (primary / replica / shards), per-request
+sessions with auto-commit/rollback, Alembic helpers, and pytest fixtures.
+"""
+
+from __future__ import annotations
+
+from ._alembic import run_migrations
+from ._database import Database, init_database, resolve_database
+from ._engine import DatabaseConfig, Engine, create_engine
+from ._health import all_healthy, database_healthy, session_healthy
+from ._models import Base, DataclassBase, TimestampMixin, UUIDMixin
+from ._session import get_replica_session, get_session, open_session, session_for
+from ._testing import temporary_database, temporary_session
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Base",
+    "DataclassBase",
+    "Database",
+    "DatabaseConfig",
+    "Engine",
+    "TimestampMixin",
+    "UUIDMixin",
+    "__version__",
+    "all_healthy",
+    "create_engine",
+    "database_healthy",
+    "get_replica_session",
+    "get_session",
+    "init_database",
+    "open_session",
+    "resolve_database",
+    "run_migrations",
+    "session_for",
+    "session_healthy",
+    "temporary_database",
+    "temporary_session",
+]

hawkapi_sqlalchemy/_alembic.py

@@ -0,0 +1,99 @@
+"""Alembic env.py helpers.
+
+Drop this into your migrations ``env.py``:
+
+.. code-block:: python
+
+    from hawkapi_sqlalchemy.alembic import run_migrations
+    from myapp.db import Base, settings   # your declarative Base + URL
+
+    run_migrations(target_metadata=Base.metadata, url=settings.database_url)
+
+That single call handles both online (live connection) and offline (`--sql`) modes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import create_async_engine
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqlalchemy import MetaData
+
+
+def run_migrations(
+    *,
+    target_metadata: MetaData,
+    url: str,
+    compare_type: bool = True,
+    render_as_batch: bool | None = None,
+    configure_kwargs: dict[str, Any] | None = None,
+) -> None:
+    """Drive Alembic for the current command context.
+
+    Picks online vs offline mode based on ``context.is_offline_mode()``.
+    """
+    from alembic import context  # imported lazily so this module is import-safe outside Alembic
+
+    if render_as_batch is None:
+        render_as_batch = url.startswith("sqlite")
+
+    if context.is_offline_mode():
+        context.configure(
+            url=url,
+            target_metadata=target_metadata,
+            literal_binds=True,
+            compare_type=compare_type,
+            render_as_batch=render_as_batch,
+            dialect_opts={"paramstyle": "named"},
+            **(configure_kwargs or {}),
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+        return
+
+    asyncio.run(_run_online(target_metadata, url, compare_type, render_as_batch, configure_kwargs))
+
+
+async def _run_online(
+    target_metadata: MetaData,
+    url: str,
+    compare_type: bool,
+    render_as_batch: bool,
+    configure_kwargs: dict[str, Any] | None,
+) -> None:
+    connectable = create_async_engine(url, poolclass=pool.NullPool, future=True)
+    async with connectable.connect() as connection:
+        await connection.run_sync(
+            lambda sync_conn: _apply(
+                sync_conn, target_metadata, compare_type, render_as_batch, configure_kwargs
+            )
+        )
+    await connectable.dispose()
+
+
+def _apply(
+    connection: Connection,
+    target_metadata: MetaData,
+    compare_type: bool,
+    render_as_batch: bool,
+    configure_kwargs: dict[str, Any] | None,
+) -> None:
+    from alembic import context
+
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=compare_type,
+        render_as_batch=render_as_batch,
+        **(configure_kwargs or {}),
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+__all__ = ["run_migrations"]

hawkapi_sqlalchemy/_database.py

@@ -0,0 +1,133 @@
+"""Database registry — multi-engine routing + plugin entry point.
+
+A :class:`Database` owns one or more :class:`Engine` instances keyed by name.
+The convention is:
+
+* ``primary`` — read/write engine (the default).
+* ``replica`` — optional read-only engine; if absent we fall back to ``primary``.
+
+You can register any number of named engines (e.g. ``analytics``, ``shard_1``)
+and ask for them by name via :func:`get_session(name=...)`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ._engine import DatabaseConfig, Engine, create_engine
+
+
+@dataclass
+class Database:
+    engines: dict[str, Engine] = field(default_factory=dict)
+
+    def add(self, name: str, config: DatabaseConfig) -> Engine:
+        engine = create_engine(config)
+        self.engines[name] = engine
+        return engine
+
+    def get(self, name: str = "primary") -> Engine:
+        if name in self.engines:
+            return self.engines[name]
+        if name != "primary" and "primary" in self.engines:
+            # Fall back to primary for replicas / analytics shards that are not configured.
+            return self.engines["primary"]
+        raise KeyError(f"no engine registered under {name!r}")
+
+    @asynccontextmanager
+    async def session(
+        self, name: str = "primary", *, commit: bool = True
+    ) -> AsyncGenerator[AsyncSession, None]:
+        """Open a session bound to ``name``. Commits on clean exit; rolls back on exception."""
+        engine = self.get(name)
+        async with engine.sessionmaker() as sess:
+            try:
+                yield sess
+                if commit:
+                    await sess.commit()
+            except Exception:
+                await sess.rollback()
+                raise
+
+    async def dispose(self) -> None:
+        for engine in self.engines.values():
+            await engine.dispose()
+
+
+# ---------------------------------------------------------------------------
+# Plugin registry
+# ---------------------------------------------------------------------------
+
+
+class _StateNamespace:
+    db: Any
+
+
+_ACTIVE_DATABASES: dict[int, Database] = {}
+_LAST_DATABASE: list[Database | None] = [None]
+
+
+def init_database(
+    app: Any,
+    *,
+    url: str | None = None,
+    config: DatabaseConfig | None = None,
+    databases: dict[str, DatabaseConfig] | None = None,
+    dispose_on_shutdown: bool = True,
+) -> Database:
+    """Attach a :class:`Database` to ``app.state.db`` and register it for DI lookup.
+
+    The three argument shapes (mutually exclusive):
+
+    1. ``url=...`` — convenience, creates a single ``primary`` engine.
+    2. ``config=DatabaseConfig(...)`` — single ``primary`` engine with custom config.
+    3. ``databases={"primary": ..., "replica": ...}`` — register multiple engines.
+    """
+    if sum(x is not None for x in (url, config, databases)) != 1:
+        raise ValueError("init_database requires exactly one of url=, config=, or databases=")
+
+    database = Database()
+    if url is not None:
+        database.add("primary", DatabaseConfig(url=url))
+    elif config is not None:
+        database.add("primary", config)
+    else:
+        assert databases is not None
+        if "primary" not in databases:
+            raise ValueError("databases must include a 'primary' entry")
+        for name, cfg in databases.items():
+            database.add(name, cfg)
+
+    if getattr(app, "state", None) is None:
+        app.state = _StateNamespace()
+    app.state.db = database
+    _ACTIVE_DATABASES[id(app)] = database
+    _LAST_DATABASE[0] = database
+
+    if dispose_on_shutdown and hasattr(app, "on_shutdown"):
+
+        async def _dispose() -> None:
+            await database.dispose()
+
+        app.on_shutdown(_dispose)
+    return database
+
+
+def resolve_database(app: Any) -> Database | None:
+    if app is None:
+        return _LAST_DATABASE[0]
+    db = _ACTIVE_DATABASES.get(id(app))
+    if db is not None:
+        return db
+    state = getattr(app, "state", None)
+    if state is not None and hasattr(state, "db"):
+        return state.db  # type: ignore[no-any-return]
+    return _LAST_DATABASE[0]
+
+
+__all__ = ["Database", "init_database", "resolve_database"]

hawkapi_sqlalchemy/_engine.py

@@ -0,0 +1,67 @@
+"""Engine + sessionmaker creation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+
+@dataclass(slots=True)
+class DatabaseConfig:
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    pool_timeout: float = 30.0
+    pool_recycle: int = 3600
+    pool_pre_ping: bool = True
+    connect_args: dict[str, Any] = field(default_factory=dict)
+    engine_kwargs: dict[str, Any] = field(default_factory=dict)
+    session_kwargs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class Engine:
+    """Engine + sessionmaker pair."""
+
+    engine: AsyncEngine
+    sessionmaker: async_sessionmaker[AsyncSession]
+    config: DatabaseConfig
+
+    async def dispose(self) -> None:
+        await self.engine.dispose()
+
+
+def create_engine(config: DatabaseConfig) -> Engine:
+    kwargs: dict[str, Any] = {
+        "echo": config.echo,
+        "pool_pre_ping": config.pool_pre_ping,
+        "pool_recycle": config.pool_recycle,
+    }
+    # SQLite (aiosqlite) does not accept pool_size / max_overflow / pool_timeout.
+    if not config.url.startswith("sqlite"):
+        kwargs["pool_size"] = config.pool_size
+        kwargs["max_overflow"] = config.max_overflow
+        kwargs["pool_timeout"] = config.pool_timeout
+    if config.connect_args:
+        kwargs["connect_args"] = config.connect_args
+    kwargs.update(config.engine_kwargs)
+
+    engine = create_async_engine(config.url, **kwargs)
+    smaker = async_sessionmaker(
+        bind=engine,
+        expire_on_commit=False,
+        autoflush=False,
+        **config.session_kwargs,
+    )
+    return Engine(engine=engine, sessionmaker=smaker, config=config)
+
+
+__all__ = ["DatabaseConfig", "Engine", "create_engine"]

hawkapi_sqlalchemy/_health.py

@@ -0,0 +1,35 @@
+"""Healthcheck helpers."""
+
+from __future__ import annotations
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ._database import Database
+
+
+async def session_healthy(session: AsyncSession) -> bool:
+    """Run a trivial ``SELECT 1`` against an open session — returns False on any error."""
+    try:
+        result = await session.execute(text("SELECT 1"))
+        row = result.scalar_one()
+        return row == 1
+    except Exception:
+        return False
+
+
+async def database_healthy(database: Database, *, name: str = "primary") -> bool:
+    """Open a fresh session against ``name`` and verify connectivity."""
+    try:
+        async with database.session(name, commit=False) as sess:
+            return await session_healthy(sess)
+    except Exception:
+        return False
+
+
+async def all_healthy(database: Database) -> dict[str, bool]:
+    """Run :func:`database_healthy` against every registered engine."""
+    return {name: await database_healthy(database, name=name) for name in database.engines}
+
+
+__all__ = ["all_healthy", "database_healthy", "session_healthy"]

hawkapi_sqlalchemy/_models.py

@@ -0,0 +1,52 @@
+"""Base declarative class + reusable mixins."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime, String, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, MappedAsDataclass, mapped_column
+
+
+class Base(DeclarativeBase):
+    """Declarative base for hawkapi-sqlalchemy users.
+
+    Subclass this for ordinary ORM models. Use :class:`DataclassBase` if you want
+    SQLAlchemy 2.0's dataclass-style declarative mode.
+    """
+
+
+class DataclassBase(MappedAsDataclass, DeclarativeBase, kw_only=True):
+    """Same as :class:`Base` but with dataclass-style ``__init__`` / ``__repr__``."""
+
+
+class TimestampMixin:
+    """Adds ``created_at`` / ``updated_at`` columns with DB-side defaults."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        server_default=func.current_timestamp(),
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        server_default=func.current_timestamp(),
+        onupdate=lambda: datetime.now(UTC),
+        nullable=False,
+    )
+
+
+class UUIDMixin:
+    """Adds a string ``id`` column with a uuid4 default."""
+
+    id: Mapped[str] = mapped_column(
+        String(36),
+        primary_key=True,
+        default=lambda: str(uuid.uuid4()),
+    )
+
+
+__all__ = ["Base", "DataclassBase", "TimestampMixin", "UUIDMixin"]

hawkapi_sqlalchemy/_session.py

@@ -0,0 +1,64 @@
+"""DI helpers — per-request sessions with auto-commit / rollback."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+
+from hawkapi import HTTPException, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ._database import resolve_database
+
+
+async def get_session(request: Request) -> AsyncIterator[AsyncSession]:
+    """DI dependency — yields a ``primary`` session, commits on success, rolls back on error."""
+    async for sess in _session_iter(request, name="primary"):
+        yield sess
+
+
+async def get_replica_session(request: Request) -> AsyncIterator[AsyncSession]:
+    """DI dependency — yields a ``replica`` session (falls back to ``primary`` if unset).
+
+    Never auto-commits — replicas are read-only by convention.
+    """
+    async for sess in _session_iter(request, name="replica", commit=False):
+        yield sess
+
+
+def session_for(
+    name: str, *, commit: bool = True
+) -> Callable[[Request], AsyncIterator[AsyncSession]]:
+    """Build a DI dependency that opens a session against the engine named ``name``."""
+
+    async def _dep(request: Request) -> AsyncIterator[AsyncSession]:
+        async for sess in _session_iter(request, name=name, commit=commit):
+            yield sess
+
+    return _dep
+
+
+async def _session_iter(
+    request: Request, *, name: str, commit: bool = True
+) -> AsyncIterator[AsyncSession]:
+    db = resolve_database(request.scope.get("app"))
+    if db is None:
+        raise HTTPException(
+            500, detail="Database not configured — call init_database(app, ...) first"
+        )
+    async with db.session(name, commit=commit) as sess:
+        yield sess
+
+
+# Helper for non-handler code — e.g. background workers.
+async def open_session(app: Any, *, name: str = "primary", commit: bool = True) -> AsyncSession:
+    """Open a raw session without going through DI. Caller is responsible for closing it."""
+    db = resolve_database(app)
+    if db is None:
+        raise RuntimeError("Database not configured — call init_database(app, ...) first")
+    engine = db.get(name)
+    _ = commit  # callers manage commit themselves
+    return engine.sessionmaker()
+
+
+__all__ = ["get_replica_session", "get_session", "open_session", "session_for"]

hawkapi_sqlalchemy/_testing.py

@@ -0,0 +1,51 @@
+"""Pytest helpers — build an in-memory engine, manage schema lifecycle."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ._database import Database
+from ._engine import DatabaseConfig
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sqlalchemy import MetaData
+
+
+@asynccontextmanager
+async def temporary_database(
+    metadata: MetaData,
+    *,
+    url: str = "sqlite+aiosqlite:///:memory:",
+) -> AsyncGenerator[Database, None]:
+    """Yields a :class:`Database` whose schema is created up-front and dropped on exit."""
+    db = Database()
+    db.add("primary", DatabaseConfig(url=url))
+    engine = db.get("primary").engine
+    async with engine.begin() as conn:
+        await conn.run_sync(metadata.create_all)
+    try:
+        yield db
+    finally:
+        try:
+            async with engine.begin() as conn:
+                await conn.run_sync(metadata.drop_all)
+        finally:
+            await db.dispose()
+
+
+@asynccontextmanager
+async def temporary_session(
+    metadata: MetaData,
+    *,
+    url: str = "sqlite+aiosqlite:///:memory:",
+) -> AsyncGenerator[AsyncSession, None]:
+    """Convenience — yield a session against a fresh in-memory database."""
+    async with temporary_database(metadata, url=url) as db, db.session() as sess:
+        yield sess
+
+
+__all__ = ["temporary_database", "temporary_session"]

hawkapi_sqlalchemy/alembic.py

@@ -0,0 +1,8 @@
+"""Public alias for the Alembic helper.
+
+Imported from your ``alembic/env.py`` as ``from hawkapi_sqlalchemy.alembic import run_migrations``.
+"""
+
+from ._alembic import run_migrations
+
+__all__ = ["run_migrations"]

hawkapi_sqlalchemy-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: hawkapi-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy integration for HawkAPI — async sessions, multi-database routing, Alembic helpers, pytest fixtures
+Project-URL: Homepage, https://pypi.org/project/hawkapi-sqlalchemy/
+Project-URL: Repository, https://github.com/ashimov/hawkapi-sqlalchemy
+Project-URL: Issues, https://github.com/ashimov/hawkapi-sqlalchemy/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: alembic,async,database,hawkapi,mysql,postgres,sqlalchemy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: alembic>=1.13
+Requires-Dist: hawkapi>=0.1.7
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# hawkapi-sqlalchemy
+
+SQLAlchemy integration for [HawkAPI](https://github.com/ashimov/HawkAPI). Async sessions, multi-database routing (primary/replica/shards), Alembic helpers, and pytest fixtures.
+
+## Install
+
+```bash
+pip install hawkapi-sqlalchemy                     # SQLite included
+pip install 'hawkapi-sqlalchemy[postgres]'         # + asyncpg
+pip install 'hawkapi-sqlalchemy[mysql]'            # + aiomysql
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hawkapi_sqlalchemy import Base, TimestampMixin, get_session, init_database
+
+
+class User(Base, TimestampMixin):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    email: Mapped[str] = mapped_column(unique=True)
+
+
+app = HawkAPI()
+init_database(app, url="postgresql+asyncpg://user:pw@localhost/app")
+
+
+@app.post("/users")
+async def create(email: str, sess: AsyncSession = Depends(get_session)):
+    sess.add(User(email=email))
+    await sess.flush()
+    return {"ok": True}
+```
+
+The `get_session` dependency opens a fresh session per request, **commits on success**, and **rolls back on exception** — no boilerplate.
+
+## Multiple databases
+
+```python
+from hawkapi_sqlalchemy import DatabaseConfig, init_database, session_for
+
+init_database(
+    app,
+    databases={
+        "primary": DatabaseConfig(url="postgresql+asyncpg://…/primary"),
+        "replica": DatabaseConfig(url="postgresql+asyncpg://…/replica"),
+        "analytics": DatabaseConfig(url="postgresql+asyncpg://…/analytics"),
+    },
+)
+
+# DI helpers:
+from hawkapi_sqlalchemy import get_session, get_replica_session
+
+get_analytics = session_for("analytics", commit=False)
+
+
+@app.get("/report")
+async def report(sess: AsyncSession = Depends(get_analytics)):
+    ...
+```
+
+`get_replica_session` falls back to `primary` if no replica is registered, so you can switch on without changing handlers.
+
+## Mixins
+
+```python
+from hawkapi_sqlalchemy import Base, TimestampMixin, UUIDMixin
+
+
+class Doc(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "docs"
+    title: Mapped[str] = mapped_column()
+```
+
+- `TimestampMixin` — `created_at` / `updated_at` with DB-side defaults + Python `onupdate`.
+- `UUIDMixin` — string `id` column with a `uuid4()` default.
+- Prefer `DataclassBase` over `Base` to get SQLAlchemy 2.0's dataclass-style declarative.
+
+## Alembic
+
+In your `alembic/env.py`:
+
+```python
+from hawkapi_sqlalchemy.alembic import run_migrations
+from myapp.db import Base, settings  # your Base + URL
+
+run_migrations(target_metadata=Base.metadata, url=settings.database_url)
+```
+
+That's it — handles both online (live connection) and offline (`--sql`) modes; uses `NullPool` for migrations; enables `render_as_batch=True` automatically for SQLite.
+
+## Healthchecks
+
+```python
+from hawkapi_sqlalchemy import all_healthy
+
+
+@app.get("/healthz")
+async def healthz():
+    return await all_healthy(app.state.db)
+```
+
+Returns `{"primary": True, "replica": True, ...}`.
+
+## Testing
+
+```python
+import pytest
+from hawkapi_sqlalchemy import Base, temporary_database
+
+
+@pytest.fixture
+async def db():
+    async with temporary_database(Base.metadata) as database:
+        yield database
+
+
+async def test_something(db):
+    async with db.session() as sess:
+        ...
+```
+
+`temporary_database` creates an in-memory SQLite engine, calls `Base.metadata.create_all`, yields, then drops the schema and disposes.
+
+## DatabaseConfig
+
+```python
+DatabaseConfig(
+    url="postgresql+asyncpg://…",
+    echo=False,
+    pool_size=5,
+    max_overflow=10,
+    pool_timeout=30.0,
+    pool_recycle=3600,
+    pool_pre_ping=True,
+    connect_args={"server_settings": {"jit": "off"}},
+    engine_kwargs={...},     # forwarded to create_async_engine
+    session_kwargs={...},    # forwarded to async_sessionmaker
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-sqlalchemy.git
+cd hawkapi-sqlalchemy
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_sqlalchemy-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+hawkapi_sqlalchemy/__init__.py,sha256=-nWx7ZV4vk4pXBN_hY6dyisb2T7571yovLAIpEHCwmc,1168
+hawkapi_sqlalchemy/_alembic.py,sha256=c2lffjJ83tQl8qFFgWyXMildUymnjbWBwqnoSPmHvrQ,2807
+hawkapi_sqlalchemy/_database.py,sha256=MEKZhL6VRPYTKI768Qj8lwM7-BF_peJly9YSvdRcPpg,4326
+hawkapi_sqlalchemy/_engine.py,sha256=V8XA5ObxZqklLksFOXMPH_9uuHnLcb8_QqcB0xtqNvc,1879
+hawkapi_sqlalchemy/_health.py,sha256=p-Yww5H4ykZdbN3JkkkmGVVn28KCTJe8m_cM6i_90rk,1109
+hawkapi_sqlalchemy/_models.py,sha256=m3nUvX_KjKkMwQ5fkq0s5WUNTfE9M9eOm4RsaysbZMs,1492
+hawkapi_sqlalchemy/_session.py,sha256=ar58VVkSvYeUZLkOzQTuMp3hKo_aacMFLk5ehE5HTD0,2276
+hawkapi_sqlalchemy/_testing.py,sha256=lvqhtwRXPssovfJnZKJqIDUAYqXXH9c850MTwe2ldFk,1486
+hawkapi_sqlalchemy/alembic.py,sha256=FLLaQmin9xcp3ln73hUDe2vKeKdRrMAU0X5oF12jfbo,213
+hawkapi_sqlalchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hawkapi_sqlalchemy-0.1.0.dist-info/METADATA,sha256=I12xN4tDGOQxEjrFvV3m_2RF7g23Qfd8BOybFrNiXkQ,6913
+hawkapi_sqlalchemy-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hawkapi_sqlalchemy-0.1.0.dist-info/licenses/LICENSE,sha256=_RpjhvsfLqqeG_gv2cRatjIxCTGXTpXhKU9jqLZXYa4,1077
+hawkapi_sqlalchemy-0.1.0.dist-info/RECORD,,

hawkapi_sqlalchemy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hawkapi_sqlalchemy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HawkAPI Contributors
+
+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.