jigkit 0.1.0__tar.gz

jigkit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Test and coverage output
+.coverage
+.coverage.*
+coverage.json
+coverage.xml
+htmlcov/
+junit/
+.pytest_cache/
+.ruff_cache/
+# Staging directory the coverage publish step assembles (CI only)
+coverage-upload/
+# Shared coverage tooling, fetched on demand by `make coverage`
+.coverage-report.py
+
+# Editor and OS
+.idea/
+*.iml
+*.swp
+.DS_Store
+
+# Claude Code local settings
+.claude/settings.local.json

jigkit-0.1.0/LICENSE

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

jigkit-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: jigkit
+Version: 0.1.0
+Summary: The shared foundations of small self-hosted web apps: settings, database, migrations, logging, health checks and test fixtures
+Project-URL: Homepage, https://github.com/jmerhar/jigkit
+Project-URL: Changelog, https://github.com/jmerhar/jigkit/blob/main/CHANGELOG.md
+Author: Jure Merhar
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: pydantic-settings>=2.15
+Requires-Dist: pydantic>=2.13
+Requires-Dist: tzdata>=2026.5
+Provides-Extra: db
+Requires-Dist: aiosqlite>=0.22; extra == 'db'
+Requires-Dist: alembic>=1.19; extra == 'db'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.22; extra == 'dev'
+Requires-Dist: alembic>=1.19; extra == 'dev'
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1; extra == 'dev'
+Requires-Dist: pytest>=9.1; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: aiosqlite>=0.22; extra == 'postgres'
+Requires-Dist: alembic>=1.19; extra == 'postgres'
+Requires-Dist: asyncpg>=0.30; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52; extra == 'postgres'
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio>=1.4; extra == 'testing'
+Requires-Dist: pytest>=9.1; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# jigkit
+
+The shared foundations of small self-hosted web apps built on FastAPI, async SQLAlchemy and
+Svelte: settings, database, migrations, logging, health checks and test fixtures, each hardened
+once instead of copied between applications.
+
+```bash
+pip install "jigkit[db]"
+```
+
+| Module | Extra | What it gives an application |
+|---|---|---|
+| `jigkit.settings` | — | `AppSettings`: blank environment values mean unset, `X` or `X_FILE` for secrets (never both), a validated `TZ`, a data directory |
+| `jigkit.db` | `db` | an async engine with SQLite's pragmas (foreign keys, WAL, busy timeout), a session factory, a commit-or-roll-back `session_scope` |
+| `jigkit.models` | `db` | a declarative `Base` with deterministic constraint names, `UtcDateTime`, `TimestampMixin` |
+| `jigkit.migrations` | `db` | the whole of an Alembic `env.py`, with foreign keys off during SQLite table rebuilds and checked afterwards |
+| `jigkit.logging` | — | stream and rotating file handlers, a level that changes at runtime, credential-carrying HTTP client loggers kept quiet |
+| `jigkit.healthcheck` | — | `python -m jigkit.healthcheck URL --expect database=connected`, a container health probe |
+| `jigkit.secrets` | — | `load_or_create_secret`, a generated secret kept owner-only in the data directory |
+| `jigkit.testing` | `testing` | a pytest plugin (`data_dir`, `no_network`) and migration checks run through the application's own `env.py` |
+
+PostgreSQL is supported through the `postgres` extra. Python 3.14 or newer.
+
+See the [repository](https://github.com/jmerhar/jigkit) for the changelog and documentation.

jigkit-0.1.0/README.md

@@ -0,0 +1,24 @@
+# jigkit
+
+The shared foundations of small self-hosted web apps built on FastAPI, async SQLAlchemy and
+Svelte: settings, database, migrations, logging, health checks and test fixtures, each hardened
+once instead of copied between applications.
+
+```bash
+pip install "jigkit[db]"
+```
+
+| Module | Extra | What it gives an application |
+|---|---|---|
+| `jigkit.settings` | — | `AppSettings`: blank environment values mean unset, `X` or `X_FILE` for secrets (never both), a validated `TZ`, a data directory |
+| `jigkit.db` | `db` | an async engine with SQLite's pragmas (foreign keys, WAL, busy timeout), a session factory, a commit-or-roll-back `session_scope` |
+| `jigkit.models` | `db` | a declarative `Base` with deterministic constraint names, `UtcDateTime`, `TimestampMixin` |
+| `jigkit.migrations` | `db` | the whole of an Alembic `env.py`, with foreign keys off during SQLite table rebuilds and checked afterwards |
+| `jigkit.logging` | — | stream and rotating file handlers, a level that changes at runtime, credential-carrying HTTP client loggers kept quiet |
+| `jigkit.healthcheck` | — | `python -m jigkit.healthcheck URL --expect database=connected`, a container health probe |
+| `jigkit.secrets` | — | `load_or_create_secret`, a generated secret kept owner-only in the data directory |
+| `jigkit.testing` | `testing` | a pytest plugin (`data_dir`, `no_network`) and migration checks run through the application's own `env.py` |
+
+PostgreSQL is supported through the `postgres` extra. Python 3.14 or newer.
+
+See the [repository](https://github.com/jmerhar/jigkit) for the changelog and documentation.

jigkit-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jigkit"
+version = "0.1.0"
+description = "The shared foundations of small self-hosted web apps: settings, database, migrations, logging, health checks and test fixtures"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jure Merhar" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.13",
+    "pydantic-settings>=2.15",
+    # Time zone data for validating TZ, which a slim container image need not carry.
+    "tzdata>=2026.5",
+]
+
+[project.optional-dependencies]
+# An async SQLAlchemy database, SQLite by default, with Alembic migrations.
+db = [
+    "sqlalchemy[asyncio]>=2.0.52",
+    "aiosqlite>=0.22",
+    "alembic>=1.19",
+]
+# PostgreSQL through asyncpg, on top of `db`.
+postgres = [
+    "jigkit[db]",
+    "asyncpg>=0.30",
+]
+# The pytest plugin: fixtures and migration checks for applications built on jigkit.
+testing = [
+    "pytest>=9.1",
+    "pytest-asyncio>=1.4",
+]
+# Everything this repository's own checks need.
+dev = [
+    "jigkit[db,testing]",
+    "pytest-cov>=7.1",
+    "ruff>=0.16",
+    "build>=1.3",
+    "twine>=6.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmerhar/jigkit"
+Changelog = "https://github.com/jmerhar/jigkit/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jigkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/jigkit", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["jigkit"]
+# Async throughout. Coverage's sys.monitoring core (COVERAGE_CORE=sysmon, set in bin/test.sh and
+# CI) traces lines after `await`, which the legacy C core under-reports.
+branch = true
+# The migration tests run Alembic in a subprocess; this lets their coverage be measured too.
+patch = ["subprocess"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "if __name__ == .__main__.:",
+]

jigkit-0.1.0/src/jigkit/__init__.py

@@ -0,0 +1,9 @@
+"""The shared foundations of small self-hosted web apps.
+
+Each module is imported on its own (``jigkit.settings``, ``jigkit.db``, ...); importing the
+package pulls in nothing beyond the version.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("jigkit")

jigkit-0.1.0/src/jigkit/db.py

@@ -0,0 +1,84 @@
+"""The async database engine, its sessions, and the transaction boundary.
+
+SQLite is the default backend and gets the pragmas its schema assumptions depend on; PostgreSQL
+(the ``postgres`` extra) gets a pre-ping, so a connection the server dropped is replaced instead
+of failing the next request.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from sqlalchemy import event
+from sqlalchemy.engine.interfaces import DBAPIConnection
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.pool import ConnectionPoolEntry
+
+#: Milliseconds a SQLite connection waits for a lock before giving up.
+SQLITE_BUSY_TIMEOUT_MS = 5000
+
+
+def is_sqlite(url: str) -> bool:
+    """Whether ``url`` names a SQLite database, whose pragmas another backend would reject."""
+    return url.startswith("sqlite")
+
+
+def apply_sqlite_pragmas(dbapi_connection: DBAPIConnection, _record: ConnectionPoolEntry) -> None:
+    """Turn on the SQLite behaviour a schema with foreign keys assumes.
+
+    ``foreign_keys`` is off by default in SQLite, which silently makes every ``ON DELETE`` rule a
+    no-op. WAL lets background work write while a request reads, instead of the two blocking each
+    other, and the busy timeout makes a writer wait for a lock rather than fail at once.
+    """
+    cursor = dbapi_connection.cursor()
+    try:
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute(f"PRAGMA busy_timeout={SQLITE_BUSY_TIMEOUT_MS}")
+    finally:
+        cursor.close()
+
+
+def create_engine(url: str, **kwargs: Any) -> AsyncEngine:
+    """Build an async engine for ``url``, with the backend's connection setup wired in.
+
+    Keyword arguments go to SQLAlchemy's ``create_async_engine``.
+    """
+    if is_sqlite(url):
+        engine = create_async_engine(url, **kwargs)
+        event.listen(engine.sync_engine, "connect", apply_sqlite_pragmas)
+        return engine
+    kwargs.setdefault("pool_pre_ping", True)
+    return create_async_engine(url, **kwargs)
+
+
+def create_sessionmaker(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    """A session factory that leaves loaded objects usable after a commit.
+
+    ``expire_on_commit=False`` so a handler can read the object it just saved without a second
+    round trip, which under async would be implicit IO hidden behind attribute access.
+    """
+    return async_sessionmaker(engine, expire_on_commit=False, autoflush=False)
+
+
+@asynccontextmanager
+async def session_scope(factory: async_sessionmaker[AsyncSession]) -> AsyncIterator[AsyncSession]:
+    """A transaction that commits on success and rolls back on any exception.
+
+    Read-only blocks commit too. On PostgreSQL that ends them as a no-op COMMIT instead of a
+    ROLLBACK, which keeps the server's rollback ratio meaningful.
+    """
+    async with factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except BaseException:
+            await session.rollback()
+            raise

jigkit-0.1.0/src/jigkit/healthcheck.py

@@ -0,0 +1,92 @@
+"""A container health probe: ``python -m jigkit.healthcheck URL [--expect KEY=VALUE ...]``.
+
+Exits 0 only when the URL answers 200 with a JSON object holding every expected value. A probe
+that only checked the port would call a container healthy while every request it served failed,
+so an application reports what it depends on (``{"database": "connected"}``) and the probe
+checks it::
+
+    HEALTHCHECK CMD ["python", "-m", "jigkit.healthcheck",
+                     "http://127.0.0.1:8000/api/health", "--expect", "database=connected"]
+
+Only the standard library is used, so the probe starts quickly and needs no extra.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+from collections.abc import Mapping, Sequence
+
+TIMEOUT_SECONDS = 5.0
+
+
+def probe(
+    url: str, expect: Mapping[str, object] | None = None, timeout: float = TIMEOUT_SECONDS
+) -> int:
+    """Report whether the application at ``url`` is healthy, as an exit status.
+
+    Each reason for an unhealthy result is printed to stderr, where Docker keeps it in the
+    container's health log.
+    """
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:  # noqa: S310
+            # urlopen raises for 4xx and 5xx, so this catches a 2xx that is not 200, which is not
+            # an answer to a health question either.
+            if response.status != 200:
+                return _unhealthy(f"HTTP {response.status}")
+            body = json.load(response)
+    except urllib.error.HTTPError as error:
+        # Closed explicitly: an HTTPError carries the response it was raised from.
+        with error:
+            return _unhealthy(f"HTTP {error.code}")
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as error:
+        return _unhealthy(str(error))
+
+    if not isinstance(body, dict):
+        return _unhealthy(f"expected a JSON object, got {type(body).__name__}")
+    for key, wanted in (expect or {}).items():
+        if body.get(key) != wanted:
+            return _unhealthy(f"{key} is {body.get(key)!r}, expected {wanted!r}")
+    return 0
+
+
+def _unhealthy(reason: str) -> int:
+    """Print why the probe failed, and return the failing exit status."""
+    print(f"unhealthy: {reason}", file=sys.stderr)
+    return 1
+
+
+def _expectation(text: str) -> tuple[str, object]:
+    """Parse ``KEY=VALUE``, VALUE as JSON if it parses (``true``, ``3``) and as text if not."""
+    key, separator, raw = text.partition("=")
+    if not separator or not key:
+        raise argparse.ArgumentTypeError(f"expected KEY=VALUE, got {text!r}")
+    try:
+        value: object = json.loads(raw)
+    except json.JSONDecodeError:
+        value = raw
+    return key, value
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the probe from the command line."""
+    parser = argparse.ArgumentParser(prog="python -m jigkit.healthcheck", description=__doc__)
+    parser.add_argument("url", help="the health endpoint to query")
+    parser.add_argument(
+        "--expect",
+        action="append",
+        type=_expectation,
+        default=[],
+        metavar="KEY=VALUE",
+        help="a value the JSON body must hold; repeatable",
+    )
+    parser.add_argument("--timeout", type=float, default=TIMEOUT_SECONDS)
+    arguments = parser.parse_args(argv)
+    return probe(arguments.url, dict(arguments.expect), arguments.timeout)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jigkit-0.1.0/src/jigkit/logging.py

@@ -0,0 +1,105 @@
+"""Where an application's log goes, and how its level changes while it runs.
+
+Two destinations. The stream is what ``docker logs`` shows. The file survives the container
+being recreated; it belongs in the mounted data directory, so it can be read from the host, and
+it rotates, because nothing else rotates a file inside a container.
+
+The level can change at runtime, because the moment DEBUG is needed is the moment something is
+failing, and restarting to get it loses whatever state was interesting.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+FORMAT = "%(asctime)s %(levelname)-7s %(name)s %(message)s"
+
+#: The levels an application offers to choose from.
+LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
+
+#: Five files of five megabytes.
+MAX_BYTES = 5 * 1024 * 1024
+BACKUP_COUNT = 5
+
+#: Loggers that hold a level of their own and so are set alongside the root; uvicorn gives its
+#: access and error loggers one, and raising the root alone would leave them where they were.
+FOLLOW_ROOT = ("uvicorn", "uvicorn.access", "uvicorn.error")
+
+#: Loggers held at WARNING however low the application goes. httpx logs every request's URL at
+#: INFO and httpcore logs headers at DEBUG, and URLs and headers carry credentials: push-monitor
+#: tokens, bot tokens, session cookies.
+QUIET = ("httpx", "httpcore")
+
+# Marks the handlers this module installed, so a repeated call replaces them rather than stacking
+# a second copy that logs every line twice.
+_MARKER = "_jigkit_handler"
+
+
+def configure_logging(
+    level: str = "INFO",
+    *,
+    log_file: Path | None = None,
+    quiet: Iterable[str] = QUIET,
+    max_bytes: int = MAX_BYTES,
+    backup_count: int = BACKUP_COUNT,
+) -> Path | None:
+    """Install the stream handler, and the rotating file handler when ``log_file`` is given.
+
+    Idempotent: calling it again replaces the handlers it installed rather than adding more.
+    Returns the file's path, or None when there is no file or it could not be opened. An
+    unwritable data directory does not stop the application, since the stream still carries
+    everything.
+    """
+    quiet = tuple(quiet)
+    apply_level(level, quiet=quiet)
+
+    root = logging.getLogger()
+    for handler in [h for h in root.handlers if getattr(h, _MARKER, False)]:
+        root.removeHandler(handler)
+        handler.close()
+
+    formatter = logging.Formatter(FORMAT)
+    stream = logging.StreamHandler()
+    stream.setFormatter(formatter)
+    setattr(stream, _MARKER, True)
+    root.addHandler(stream)
+
+    if log_file is None:
+        return None
+    try:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = RotatingFileHandler(
+            log_file, maxBytes=max_bytes, backupCount=backup_count, encoding="utf-8"
+        )
+    except OSError:
+        logging.getLogger(__name__).warning(
+            "could not open %s for writing; logging to the stream only", log_file, exc_info=True
+        )
+        return None
+    file_handler.setFormatter(formatter)
+    setattr(file_handler, _MARKER, True)
+    root.addHandler(file_handler)
+    return log_file
+
+
+def apply_level(level: str, *, quiet: Iterable[str] = QUIET) -> int:
+    """Set the level of the root logger and of the loggers that follow it, and return it.
+
+    The ``quiet`` loggers never go below WARNING.
+    """
+    resolved = resolve_level(level)
+    logging.getLogger().setLevel(resolved)
+    for name in FOLLOW_ROOT:
+        logging.getLogger(name).setLevel(resolved)
+    for name in quiet:
+        logging.getLogger(name).setLevel(max(resolved, logging.WARNING))
+    return resolved
+
+
+def resolve_level(level: str) -> int:
+    """The numeric level for a name, INFO for anything unrecognised."""
+    value = logging.getLevelNamesMapping().get(level.strip().upper())
+    return value if value is not None else logging.INFO

jigkit-0.1.0/src/jigkit/migrations.py

@@ -0,0 +1,131 @@
+"""Alembic's environment, shared: the whole body of an application's ``alembic/env.py``.
+
+An application's env.py becomes::
+
+    from jigkit.migrations import run_migrations
+
+    from myapp.config import get_settings
+    from myapp.models import Base
+
+    run_migrations(get_settings().resolved_database_url, Base.metadata)
+
+Migrations run through jigkit's own engine, so ``alembic upgrade head`` and the running
+application can never disagree about which database is meant or how it is connected to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from logging.config import fileConfig
+from pathlib import Path
+from typing import Any
+
+from alembic import context
+from sqlalchemy import Connection, MetaData, event
+from sqlalchemy.engine import make_url
+
+from .db import create_engine, is_sqlite
+from .models import UtcDateTime
+
+
+def render_item(obj_type: str, obj: object, autogen_context: Any) -> str | bool:  # noqa: ARG001
+    """Render :class:`~jigkit.models.UtcDateTime` as the plain ``DateTime`` it is built on.
+
+    A migration has to keep running years later, and one that imports an application class stops
+    working when that class moves. At the DDL level the type is exactly ``sa.DateTime()``.
+
+    Everything else returns False, Alembic's "use the default rendering"; None would render the
+    item as an empty string.
+    """
+    if obj_type == "type" and isinstance(obj, UtcDateTime):
+        return "sa.DateTime()"
+    return False
+
+
+def run_migrations(url: str, metadata: MetaData) -> None:
+    """Run the migrations Alembic was asked for against the database at ``url``.
+
+    Online, this applies them; offline (``alembic upgrade --sql``), it prints the SQL instead.
+    The logging configuration in alembic.ini is applied first, as Alembic's own template does.
+    """
+    if context.config.config_file_name is not None:
+        fileConfig(context.config.config_file_name)
+    if context.is_offline_mode():
+        _run_offline(url, metadata)
+    else:
+        asyncio.run(_run_online(url, metadata))
+
+
+def _configure_options(metadata: MetaData) -> dict[str, Any]:
+    """The Alembic options both modes share.
+
+    ``render_as_batch`` is required for SQLite, which cannot ALTER a column or a constraint:
+    batch mode copies the table instead. Set unconditionally, it keeps generated migrations
+    portable between backends.
+    """
+    return {
+        "target_metadata": metadata,
+        "render_as_batch": True,
+        "compare_type": True,
+        "render_item": render_item,
+    }
+
+
+def _run_offline(url: str, metadata: MetaData) -> None:
+    """Emit the migrations' SQL to stdout instead of running it."""
+    context.configure(
+        url=url,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        **_configure_options(metadata),
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def _run(connection: Connection, metadata: MetaData) -> None:
+    """Apply migrations on a live connection, then prove they left no dangling references."""
+    context.configure(connection=connection, **_configure_options(metadata))
+    with context.begin_transaction():
+        context.run_migrations()
+    if connection.dialect.name == "sqlite":
+        dangling = connection.exec_driver_sql("PRAGMA foreign_key_check").fetchall()
+        if dangling:
+            raise RuntimeError(f"the migrations left rows pointing at nothing: {dangling}")
+
+
+def _without_foreign_keys(dbapi_connection: Any, _record: object) -> None:
+    """Turn SQLite's foreign keys off for the migrations.
+
+    Batch mode rebuilds a table by copying it, dropping the original and renaming the copy. With
+    foreign keys on, dropping the original runs every ON DELETE rule that points at it, so
+    rebuilding a parent table would delete or orphan every child row. The check after the
+    migrations stands in for the enforcement left off during them.
+    """
+    cursor = dbapi_connection.cursor()
+    try:
+        cursor.execute("PRAGMA foreign_keys=OFF")
+    finally:
+        cursor.close()
+
+
+def _ensure_sqlite_directory(url: str) -> None:
+    """Create the directory a SQLite file lives in, which SQLite will not do itself."""
+    database = make_url(url).database
+    if database and database != ":memory:" and not database.startswith("file:"):
+        Path(database).parent.mkdir(parents=True, exist_ok=True)
+
+
+async def _run_online(url: str, metadata: MetaData) -> None:
+    """Apply migrations against the database at ``url``."""
+    engine = create_engine(url)
+    if is_sqlite(url):
+        _ensure_sqlite_directory(url)
+        # Registered after create_engine's own listener, which turns foreign keys on for every
+        # connection, so this one runs last and wins.
+        event.listen(engine.sync_engine, "connect", _without_foreign_keys)
+    try:
+        async with engine.connect() as connection:
+            await connection.run_sync(_run, metadata)
+    finally:
+        await engine.dispose()