dpdpkit-fastapi 0.1.0a1__py3-none-any.whl

dpdpkit/fastapi/__init__.py

@@ -0,0 +1,22 @@
+"""FastAPI adapter for dpdpkit: router, SQLAlchemy repository, migrations, scheduler, admin mount.
+
+dpdpkit helps you implement DPDP obligations; it does not provide legal advice or guarantee compliance.
+"""
+
+from __future__ import annotations
+
+from .app import ActivityMiddleware, DPDPKit, require_consent
+from .http import ConsentRequiredHTTP
+from .repository import SqlAlchemyRepository, make_engine
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "ActivityMiddleware",
+    "ConsentRequiredHTTP",
+    "DPDPKit",
+    "SqlAlchemyRepository",
+    "__version__",
+    "make_engine",
+    "require_consent",
+]

dpdpkit/fastapi/admin_static/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>dpdpkit admin</title>
+<style>
+  body { font: 16px/1.5 system-ui, sans-serif; max-width: 42rem; margin: 3rem auto; padding: 0 1rem; color: #1f2328; }
+  code { background: #f3f4f6; padding: .1rem .3rem; border-radius: 4px; }
+</style>
+</head>
+<body>
+<h1>dpdpkit admin</h1>
+<p>The admin dashboard ships in v0.4. Until then, use the admin API under this mount's parent path:</p>
+<ul>
+  <li><code>GET ../requests</code> — request queue</li>
+  <li><code>GET ../retention/preview</code> — upcoming warnings and erasures</li>
+  <li><code>POST ../ledger/verify</code> — hash-chain check</li>
+  <li><code>GET ../audit/export</code> — evidence pack</li>
+</ul>
+<p>dpdpkit helps you implement DPDP obligations; it does not provide legal advice or guarantee compliance.</p>
+</body>
+</html>

dpdpkit/fastapi/app.py

@@ -0,0 +1,286 @@
+"""``DPDPKit`` — the object a FastAPI developer creates."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import time
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+from starlette.concurrency import run_in_threadpool
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import Response
+
+from dpdpkit import Kit, Registry
+from dpdpkit.config import kit_from_config, load_config, sync_notice
+from dpdpkit.errors import ConfigError, DpdpkitError
+from dpdpkit.kit import ContactResolver
+from dpdpkit.models import Role
+from dpdpkit.notify import Notifier
+from dpdpkit.policy import Policy
+from dpdpkit.repository import Repository
+from dpdpkit.rights import IdentityVerifier
+
+from .http import ConsentRequiredHTTP, Forbidden, Unauthenticated, consent_required_handler, render_dpdpkit_error
+from .repository import SqlAlchemyRepository
+from .router import build_router
+
+log = logging.getLogger("dpdpkit.fastapi")
+
+PrincipalResolver = Callable[[Request], "str | Awaitable[str | None] | None"]
+AdminGuard = Callable[[Request], "Role | str | bool | Awaitable[Role | str | bool | None] | None"]
+
+_default: DPDPKit | None = None
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class DPDPKit:
+    """Wire dpdpkit into a FastAPI app.
+
+    ``principal_resolver(request)`` returns a stable, non-personal reference for the signed-in user
+    (for example the user's primary key), or ``None``. ``admin_guard(request)`` returns a role
+    (``viewer``/``handler``/``admin``), ``True`` for admin, or ``None``/``False`` for no access.
+    """
+
+    def __init__(
+        self,
+        *,
+        principal_resolver: PrincipalResolver,
+        admin_guard: AdminGuard | None = None,
+        db_url: str | None = None,
+        repository: Repository | None = None,
+        config: str | Path | Mapping[str, Any] | None = None,
+        policy: str | Policy | None = None,
+        overlays: Iterable[str] = (),
+        registry: Registry | None = None,
+        notifier: Notifier | None = None,
+        contact: Mapping[str, str] | None = None,
+        contact_resolver: ContactResolver | None = None,
+        identity_verifier: IdentityVerifier | None = None,
+        signing_key: bytes | str | None = None,
+        tenant_id: str = "default",
+        migrate_on_startup: bool = False,
+        create_tables: bool = False,
+        **kit_kwargs: Any,
+    ) -> None:
+        if repository is None:
+            if not db_url:
+                raise ConfigError("pass db_url or repository")
+            repository = SqlAlchemyRepository(db_url)
+        self.repository = repository
+        if migrate_on_startup:
+            self.migrate()
+        elif create_tables and isinstance(repository, SqlAlchemyRepository):
+            repository.create_all()
+
+        common: dict[str, Any] = {
+            "notifier": notifier,
+            "contact_resolver": contact_resolver,
+            "identity_verifier": identity_verifier,
+            "signing_key": signing_key,
+            "tenant_id": tenant_id,
+            **kit_kwargs,
+        }
+        self.config: dict[str, Any] | None = None
+        if config is not None:
+            self.config = load_config(config) if isinstance(config, (str, Path)) else dict(config)
+            self.kit = kit_from_config(self.config, repository, registry=registry, contact=contact, **common)
+            sync_notice(self.kit, self.config)
+        else:
+            if policy is None:
+                raise ConfigError("pass config= (a dpdpkit.yaml) or policy=")
+            self.kit = Kit(repository, policy, overlays=overlays, registry=registry, contact=contact, **common)
+
+        self.principal_resolver = principal_resolver
+        self.admin_guard = admin_guard
+        self.router = build_router(self)
+        self._scheduler: Any = None
+
+        global _default
+        _default = self
+
+    # ------------------------------------------------------------------ identity
+
+    async def resolve_principal(self, request: Request) -> str | None:
+        value = await _maybe_await(self.principal_resolver(request))
+        return str(value) if value else None
+
+    async def require_principal(self, request: Request) -> str:
+        principal = await self.resolve_principal(request)
+        if not principal:
+            raise Unauthenticated("sign in to use this endpoint")
+        return principal
+
+    async def resolve_role(self, request: Request) -> Role | None:
+        if self.admin_guard is None:
+            return None
+        value = await _maybe_await(self.admin_guard(request))
+        if value is True:
+            return Role.ADMIN
+        if not value:
+            return None
+        try:
+            return Role(value)
+        except ValueError:
+            log.warning("admin_guard returned unknown role %r; treating as no access", value)
+            return None
+
+    async def require_role(self, request: Request, needed: Role) -> str:
+        """Check the caller's admin role; returns an actor label for the audit trail."""
+        role = await self.resolve_role(request)
+        if role is None:
+            principal = await self.resolve_principal(request)
+            if principal is None:
+                raise Unauthenticated("sign in to use this endpoint")
+            raise Forbidden("an admin role is required")
+        if not role.allows(needed):
+            raise Forbidden(f"the {needed.value} role is required", role=role.value)
+        principal = await self.resolve_principal(request)
+        return f"{role.value}:{principal}" if principal else role.value
+
+    @staticmethod
+    def request_metadata(request: Request) -> dict[str, Any]:
+        """Evidence stored with consent events. No IP address or personal data by default."""
+        return {"channel": "web", "user_agent_present": "user-agent" in request.headers}
+
+    # ------------------------------------------------------------------ consent dependency
+
+    def require_consent(self, purpose: str) -> Callable[[Request], Awaitable[None]]:
+        async def dependency(request: Request) -> None:
+            principal = await self.require_principal(request)
+            allowed = await run_in_threadpool(self.kit.consent.check, principal, purpose)
+            if not allowed:
+                raise ConsentRequiredHTTP(purpose)
+
+        return dependency
+
+    # ------------------------------------------------------------------ app wiring
+
+    def install(
+        self,
+        app: FastAPI,
+        *,
+        prefix: str = "/dpdp",
+        admin_path: str | None = None,
+        track_activity: bool = True,
+    ) -> None:
+        """Include the router, error handlers, activity middleware and the admin dashboard."""
+        app.include_router(self.router, prefix=prefix)
+        self.install_error_handlers(app)
+        if track_activity:
+            app.add_middleware(ActivityMiddleware, dpdpkit=self)
+        self.mount_admin(app, path=admin_path or f"{prefix}/admin/ui")
+
+    def install_error_handlers(self, app: FastAPI) -> None:
+        app.state.dpdpkit = self
+
+        async def dpdpkit_error(_request: Request, exc: Exception) -> Response:
+            assert isinstance(exc, DpdpkitError)
+            return render_dpdpkit_error(exc)
+
+        app.add_exception_handler(DpdpkitError, dpdpkit_error)
+        app.add_exception_handler(ConsentRequiredHTTP, consent_required_handler)
+
+    def mount_admin(self, app: FastAPI, path: str = "/dpdp/admin/ui") -> None:
+        """Serve the prebuilt admin dashboard bundle. Until it ships (v0.4) a placeholder page is served."""
+        if not any(getattr(r, "path", None) == path for r in app.routes):
+            directory = resources.files("dpdpkit.fastapi") / "admin_static"
+            app.mount(path, StaticFiles(directory=str(directory), html=True), name="dpdpkit-admin")
+        if not hasattr(app.state, "dpdpkit"):
+            self.install_error_handlers(app)
+
+    # ------------------------------------------------------------------ jobs and schema
+
+    def start_scheduler(self, *, retention_minutes: int = 15, verify_hour: int = 2) -> Any:
+        """Run retention every ``retention_minutes`` and ledger verification daily (APScheduler)."""
+        try:
+            from apscheduler.schedulers.background import BackgroundScheduler  # type: ignore[import-untyped]
+        except ImportError as exc:  # pragma: no cover
+            raise ConfigError('install the scheduler extra: pip install "dpdpkit-fastapi[scheduler]"') from exc
+        scheduler = BackgroundScheduler(timezone="UTC")
+        scheduler.add_job(
+            self.kit.retention.run,
+            "interval",
+            minutes=retention_minutes,
+            id="dpdpkit-retention",
+            max_instances=1,
+            coalesce=True,
+        )
+        scheduler.add_job(
+            self.verify_ledger_job, "cron", hour=verify_hour, id="dpdpkit-ledger-verify", max_instances=1, coalesce=True
+        )
+        scheduler.start()
+        self._scheduler = scheduler
+        return scheduler
+
+    def verify_ledger_job(self) -> bool:
+        report = self.kit.ledger.verify_report()
+        if not report.ok:
+            log.error(
+                "dpdpkit ledger verification FAILED at row %s (%s): %s", report.failed_row, report.chain, report.reason
+            )
+            self.kit.events.publish("ledger.tampered", self.kit.tenant_id, report.model_dump(mode="json"))
+        return report.ok
+
+    def migrate(self, revision: str = "head") -> None:
+        from .migrations import upgrade
+
+        if not isinstance(self.repository, SqlAlchemyRepository):
+            raise ConfigError("migrate() needs the SQLAlchemy repository")
+        upgrade(self.repository.engine, revision)
+
+
+def default_kit(request: Request | None = None) -> DPDPKit:
+    if request is not None:
+        found = getattr(request.app.state, "dpdpkit", None)
+        if isinstance(found, DPDPKit):
+            return found
+    if _default is None:
+        raise ConfigError("create a DPDPKit before using require_consent()")
+    return _default
+
+
+def require_consent(purpose: str) -> Callable[[Request], Awaitable[None]]:
+    """FastAPI dependency: 403 ``consent_required`` unless the caller has consented to ``purpose``."""
+
+    async def dependency(request: Request) -> None:
+        await default_kit(request).require_consent(purpose)(request)
+
+    return dependency
+
+
+class ActivityMiddleware(BaseHTTPMiddleware):
+    """Records principal activity (which restarts inactivity clocks and cancels warned erasures).
+    Throttled per principal so busy users do not write on every request."""
+
+    def __init__(self, app: Any, dpdpkit: DPDPKit, min_interval_seconds: float = 300) -> None:
+        super().__init__(app)
+        self.dpdpkit = dpdpkit
+        self.min_interval = min_interval_seconds
+        self._seen: dict[str, float] = {}
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        response = await call_next(request)
+        if response.status_code >= 400:
+            return response
+        try:
+            principal = await self.dpdpkit.resolve_principal(request)
+        except Exception:
+            return response
+        if principal:
+            now = time.monotonic()
+            if now - self._seen.get(principal, -1e12) >= self.min_interval:
+                self._seen[principal] = now
+                try:
+                    await run_in_threadpool(self.dpdpkit.kit.retention.record_activity, principal)
+                except Exception:
+                    log.exception("failed to record activity for a principal")
+        return response

dpdpkit/fastapi/cli.py

@@ -0,0 +1,39 @@
+"""Adds ``dpdpkit migrate`` to the core CLI (entry point group ``dpdpkit.cli``)."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+
+def _migrate(args: argparse.Namespace) -> int:
+    from dpdpkit.cli import load_kit
+
+    from .migrations import alembic_config, upgrade
+    from .repository import SqlAlchemyRepository, make_engine
+
+    if args.sql:
+        from alembic import command
+
+        command.upgrade(alembic_config(url=args.db_url or "postgresql://"), args.revision, sql=True)
+        return 0
+    if args.db_url:
+        engine = make_engine(args.db_url)
+    else:
+        repo = load_kit(args.kit).repository
+        if not isinstance(repo, SqlAlchemyRepository):
+            print("error: the kit does not use the SQLAlchemy repository")
+            return 1
+        engine = repo.engine
+    upgrade(engine, args.revision)
+    print(f"database migrated to {args.revision}")
+    return 0
+
+
+def register(subparsers: Any) -> None:
+    p = subparsers.add_parser("migrate", help="apply dpdpkit-fastapi database migrations")
+    p.add_argument("--db-url", help="SQLAlchemy URL (or use --kit)")
+    p.add_argument("--kit", help="module:attribute of your DPDPKit or Kit")
+    p.add_argument("--revision", default="head")
+    p.add_argument("--sql", action="store_true", help="print SQL instead of running it")
+    p.set_defaults(func=_migrate)

dpdpkit/fastapi/db.py

@@ -0,0 +1,152 @@
+"""SQLAlchemy 2.0 tables. Ledger and audit rows use real columns; mutable aggregates store their
+model as a JSON document next to the indexed columns used for lookups."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any, ClassVar
+
+from sqlalchemy import JSON, BigInteger, Boolean, DateTime, Index, Integer, MetaData, String, UniqueConstraint
+from sqlalchemy.dialects import mysql, postgresql
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+NAMING = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+# Microsecond precision everywhere: ledger hashes include timestamps and must survive a round trip.
+Timestamp = DateTime(timezone=True).with_variant(mysql.DATETIME(fsp=6), "mysql")
+Json = JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING)
+    type_annotation_map: ClassVar[dict[Any, Any]] = {dt.datetime: Timestamp, dict[str, Any]: Json}
+
+
+class ConsentEventRow(Base):
+    __tablename__ = "dpdp_consent_events"
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "seq", name="uq_dpdp_consent_events_tenant_seq"),
+        Index("ix_dpdp_consent_events_lookup", "tenant_id", "principal", "purpose", "seq"),
+    )
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    seq: Mapped[int] = mapped_column(BigInteger)
+    principal: Mapped[str] = mapped_column(String(255))
+    purpose: Mapped[str] = mapped_column(String(128))
+    action: Mapped[str] = mapped_column(String(16))
+    notice_version: Mapped[int | None] = mapped_column(Integer)
+    notice_hash: Mapped[str | None] = mapped_column(String(64))
+    locale: Mapped[str | None] = mapped_column(String(16))
+    source: Mapped[str] = mapped_column(String(64))
+    occurred_at: Mapped[dt.datetime]
+    meta: Mapped[dict[str, Any]]
+    prev_hash: Mapped[str] = mapped_column(String(64))
+    hash: Mapped[str] = mapped_column(String(64))
+
+
+class AuditRow(Base):
+    __tablename__ = "dpdp_audit"
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "seq", name="uq_dpdp_audit_tenant_seq"),
+        Index("ix_dpdp_audit_subject", "tenant_id", "subject_id"),
+    )
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    seq: Mapped[int] = mapped_column(BigInteger)
+    actor: Mapped[str] = mapped_column(String(255))
+    action: Mapped[str] = mapped_column(String(128))
+    subject_type: Mapped[str] = mapped_column(String(64))
+    subject_id: Mapped[str] = mapped_column(String(255))
+    occurred_at: Mapped[dt.datetime]
+    data: Mapped[dict[str, Any]]
+    prev_hash: Mapped[str] = mapped_column(String(64))
+    hash: Mapped[str] = mapped_column(String(64))
+
+
+class NoticeRow(Base):
+    __tablename__ = "dpdp_notices"
+
+    tenant_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    version: Mapped[int] = mapped_column(Integer, primary_key=True)
+    locale: Mapped[str] = mapped_column(String(16), primary_key=True)
+    content_hash: Mapped[str] = mapped_column(String(64))
+    published_at: Mapped[dt.datetime]
+    doc: Mapped[dict[str, Any]]
+
+
+class RequestRow(Base):
+    __tablename__ = "dpdp_requests"
+    __table_args__ = (
+        Index("ix_dpdp_requests_principal", "tenant_id", "principal"),
+        Index("ix_dpdp_requests_status", "tenant_id", "status"),
+    )
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    principal: Mapped[str] = mapped_column(String(255))
+    status: Mapped[str] = mapped_column(String(32))
+    opened_at: Mapped[dt.datetime]
+    doc: Mapped[dict[str, Any]]
+
+
+class NomineeRow(Base):
+    __tablename__ = "dpdp_nominees"
+    __table_args__ = (Index("ix_dpdp_nominees_principal", "tenant_id", "principal"),)
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    principal: Mapped[str] = mapped_column(String(255))
+    doc: Mapped[dict[str, Any]]
+
+
+class ScheduleRow(Base):
+    __tablename__ = "dpdp_erasure_schedules"
+    __table_args__ = (
+        Index("ix_dpdp_schedules_due", "tenant_id", "status", "warn_at"),
+        Index("ix_dpdp_schedules_principal", "tenant_id", "principal"),
+    )
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    principal: Mapped[str] = mapped_column(String(255))
+    purpose: Mapped[str] = mapped_column(String(128))
+    status: Mapped[str] = mapped_column(String(32))
+    warn_at: Mapped[dt.datetime]
+    erase_at: Mapped[dt.datetime]
+    doc: Mapped[dict[str, Any]]
+
+
+class HoldRow(Base):
+    __tablename__ = "dpdp_legal_holds"
+    __table_args__ = (Index("ix_dpdp_holds_principal", "tenant_id", "principal", "active"),)
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    principal: Mapped[str] = mapped_column(String(255))
+    active: Mapped[bool] = mapped_column(Boolean)
+    doc: Mapped[dict[str, Any]]
+
+
+class ActivityRow(Base):
+    __tablename__ = "dpdp_activity"
+
+    tenant_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    principal: Mapped[str] = mapped_column(String(255), primary_key=True)
+    last_at: Mapped[dt.datetime]
+
+
+class DeliveryRow(Base):
+    __tablename__ = "dpdp_deliveries"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(64))
+    created_at: Mapped[dt.datetime]
+    doc: Mapped[dict[str, Any]]

dpdpkit/fastapi/http.py

@@ -0,0 +1,84 @@
+"""Error rendering and the route class that turns dpdpkit errors into the contract's ``Error`` body."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from fastapi import HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+
+from dpdpkit.errors import DpdpkitError
+
+
+class Unauthenticated(DpdpkitError):
+    code = "unauthenticated"
+    http_status = 401
+
+
+class Forbidden(DpdpkitError):
+    code = "forbidden"
+    http_status = 403
+
+
+class NotImplementedYet(DpdpkitError):
+    code = "not_implemented"
+    http_status = 501
+
+
+class ConsentRequiredHTTP(HTTPException):
+    """Raised by :func:`require_consent`. Rendered as the contract's Error body once the kit is installed
+    on the app; otherwise FastAPI renders it as ``{"detail": {...}}`` with the same code."""
+
+    def __init__(self, purpose: str) -> None:
+        super().__init__(
+            status_code=403,
+            detail={
+                "code": "consent_required",
+                "message": f"consent required for purpose {purpose!r}",
+                "details": {"purpose": purpose},
+            },
+        )
+
+
+def error_response(status: int, code: str, message: str, details: dict[str, Any] | None = None) -> JSONResponse:
+    return JSONResponse(
+        status_code=status, content={"error": {"code": code, "message": message, "details": details or {}}}
+    )
+
+
+def render_dpdpkit_error(exc: DpdpkitError) -> JSONResponse:
+    status = exc.http_status if exc.http_status != 500 else 400
+    return error_response(status, exc.code, exc.message, exc.details)
+
+
+def render_validation_error(exc: RequestValidationError) -> JSONResponse:
+    errors = [
+        {"loc": [str(p) for p in e.get("loc", ())], "msg": str(e.get("msg", "")), "type": str(e.get("type", ""))}
+        for e in exc.errors()
+    ]
+    return error_response(422, "invalid_request", "request body or parameters are invalid", {"errors": errors})
+
+
+async def consent_required_handler(_request: Request, exc: Exception) -> Response:
+    assert isinstance(exc, ConsentRequiredHTTP)
+    return JSONResponse(status_code=exc.status_code, content={"error": exc.detail})
+
+
+class DpdpRoute(APIRoute):
+    """Every dpdpkit endpoint answers errors with ``{"error": {code, message, details}}``."""
+
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        handler = super().get_route_handler()
+
+        async def route(request: Request) -> Response:
+            try:
+                return await handler(request)
+            except DpdpkitError as exc:
+                return render_dpdpkit_error(exc)
+            except RequestValidationError as exc:
+                return render_validation_error(exc)
+
+        return route

dpdpkit/fastapi/migrations/__init__.py

@@ -0,0 +1,34 @@
+"""Alembic migrations shipped inside the package. Forward-only; they never drop consent or audit data."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import Engine
+
+HERE = Path(__file__).parent
+VERSION_TABLE = "dpdp_alembic_version"
+
+
+def include_name(name: str | None, type_: str, _parent: object) -> bool:
+    """dpdpkit shares the host app's database: migrations only ever consider its own tables."""
+    if type_ == "table":
+        return bool(name) and str(name).startswith("dpdp_") and name != VERSION_TABLE
+    return True
+
+
+def alembic_config(engine: Engine | None = None, url: str | None = None) -> Config:
+    cfg = Config()
+    cfg.set_main_option("script_location", str(HERE))
+    cfg.set_main_option("version_table", VERSION_TABLE)
+    if url:
+        cfg.set_main_option("sqlalchemy.url", url.replace("%", "%%"))
+    if engine is not None:
+        cfg.attributes["engine"] = engine
+    return cfg
+
+
+def upgrade(engine: Engine, revision: str = "head") -> None:
+    command.upgrade(alembic_config(engine), revision)

dpdpkit/fastapi/migrations/env.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from alembic import context
+from sqlalchemy import create_engine
+
+from dpdpkit.fastapi.db import Base
+from dpdpkit.fastapi.migrations import include_name
+
+config = context.config
+target_metadata = Base.metadata
+version_table = config.get_main_option("version_table") or "dpdp_alembic_version"
+
+
+def run_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        version_table=version_table,
+        include_name=include_name,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_online() -> None:
+    engine = config.attributes.get("engine") or create_engine(str(config.get_main_option("sqlalchemy.url")))
+    with engine.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            version_table=version_table,
+            include_name=include_name,
+            render_as_batch=connection.dialect.name == "sqlite",
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+        connection.commit()
+
+
+if context.is_offline_mode():
+    run_offline()
+else:
+    run_online()