weightsdb 0.2.0__py3-none-any.whl

weightsdb/engine.py

@@ -0,0 +1,229 @@
+"""weightsdb.engine — dialect-correct engine construction.
+
+Database standards §2: SQLite gets ``foreign_keys=ON``, ``journal_mode=WAL``, ``busy_timeout``,
+``synchronous=NORMAL``, applied per connection so a pool reconnect never silently loses them;
+PostgreSQL gets ``statement_timeout``, ``lock_timeout`` and ``application_name``. Only these two
+dialects are supported (§2) — a third requires an ADR, not a code change here.
+
+Moved from FreeWeight's ``infrastructure.db.engine``, which was written "as if it were WeightsDB's
+own" module for exactly this move (ADR-0011). Generalized in one respect the application version
+did not need: SQLite lock contention beyond ``busy_timeout`` now raises the typed
+:class:`~weightsdb.errors.StorageBusy` (spec §13) instead of a raw
+``sqlalchemy.exc.OperationalError`` — FreeWeight had one consumer and no test for that translation;
+WeightsDB's contract requires it.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import create_engine, event
+from sqlalchemy.engine import Engine, make_url
+from sqlalchemy.exc import OperationalError as SAOperationalError
+
+from weightsdb.errors import DatabaseError, StorageBusy
+
+__all__ = ["READ_ONLY_EXECUTION_OPTION", "create_engine_for"]
+
+READ_ONLY_EXECUTION_OPTION = "weightsdb_read_only"
+"""Execution option marking a transaction as read-only.
+
+Set it on a connection (:meth:`Connection.execution_options`) — as
+:func:`~weightsdb.session.transaction` does — to select a deferred ``BEGIN`` instead of
+``BEGIN IMMEDIATE`` on SQLite, enforced with ``PRAGMA query_only``; on PostgreSQL it is inert, since
+ordinary MVCC already lets readers and writers proceed without blocking each other.
+"""
+
+_SUPPORTED_DIALECTS = frozenset({"sqlite", "postgresql"})
+
+
+def create_engine_for(
+    url: str,
+    *,
+    echo: bool = False,
+    pool_size: int | None = None,
+    statement_timeout_ms: int | None = None,
+    sqlite_busy_timeout_ms: int = 5000,
+    application_name: str | None = None,
+) -> Engine:
+    """Build an engine with dialect-correct settings applied to every connection.
+
+    Every setting below is applied by an event listener on the returned engine's connection pool,
+    not once at construction time — the pool can and does open new DBAPI connections after the
+    first (on recycle, after a disposal, after a dropped network connection to PostgreSQL), and a
+    setting that only took effect on the first connection would silently stop applying on the
+    second (the specific failure mode spec §7's "pragmas lost after a pool reconnect" names).
+
+    SQLite additionally gets ``BEGIN IMMEDIATE`` transaction semantics: pysqlite's own implicit
+    transaction handling is disabled (``isolation_level = None`` on the raw connection) and
+    replaced with an explicit ``BEGIN IMMEDIATE`` issued by SQLAlchemy's ``"begin"`` hook, so lock
+    contention under SQLite's single-writer model fails fast — at the start of a transaction,
+    within ``sqlite_busy_timeout_ms`` — rather than silently at commit time, which is when
+    pysqlite's default deferred-transaction behaviour would otherwise surface it.
+
+    That matters because the deferred failure is not merely late, it is **unrecoverable**: a
+    transaction that reads, then tries to write after another connection has committed, gets
+    ``SQLITE_BUSY_SNAPSHOT``, which ``busy_timeout`` does not apply to. It fails instantly, no
+    amount of waiting helps, and the only escape is to roll back and redo work already done.
+    ``BEGIN IMMEDIATE`` converts that into an ordinary retryable wait at the start, before any work
+    exists to lose.
+
+    The cost is that it declares *every* transaction a writer, and WAL's whole point is that
+    readers never contend — so a transaction that only reads must say so, via
+    :data:`READ_ONLY_EXECUTION_OPTION` (:func:`~weightsdb.session.transaction`), and gets a
+    deferred ``BEGIN`` instead. Without that, two concurrent readers would queue behind each other
+    on the single write lock for up to ``sqlite_busy_timeout_ms`` and then fail.
+
+    Args:
+        url: A ``sqlite:///`` or ``postgresql(+driver)://`` URL. Only these two dialects are
+            supported (database standards §2).
+        echo: Log every emitted SQL statement. Development use only.
+        pool_size: PostgreSQL connection pool size. Ignored for SQLite, whose pool classes do not
+            take this argument.
+        statement_timeout_ms: PostgreSQL ``statement_timeout`` (and, identically, ``lock_timeout``,
+            since a statement that cannot even acquire its lock should not wait longer than the
+            statement itself is allowed to run). ``None`` leaves both at the server default.
+            Ignored for SQLite, which has no equivalent server-side setting —
+            ``sqlite_busy_timeout_ms`` is SQLite's analogue.
+        sqlite_busy_timeout_ms: SQLite's ``PRAGMA busy_timeout``. Ignored for PostgreSQL.
+        application_name: PostgreSQL ``application_name``, surfaced in ``pg_stat_activity``.
+            Ignored for SQLite.
+
+    Returns:
+        A configured :class:`~sqlalchemy.Engine`. Construction is cheap — no connection is opened
+        until first use — so this comfortably meets the ≤ 50 ms creation budget (spec §15).
+
+    Raises:
+        DatabaseError: ``url``'s dialect is neither ``sqlite`` nor ``postgresql``.
+    """
+    dialect = make_url(url).get_backend_name()
+    if dialect not in _SUPPORTED_DIALECTS:
+        raise DatabaseError(
+            f"Unsupported dialect {dialect!r}; only sqlite and postgresql are supported "
+            "(database standards §2). Adding a third dialect requires an ADR.",
+            details={"dialect": dialect},
+        )
+
+    engine_kwargs: dict[str, Any] = {"echo": echo}
+    if dialect == "postgresql" and pool_size is not None:
+        engine_kwargs["pool_size"] = pool_size
+
+    engine = create_engine(url, **engine_kwargs)
+
+    if dialect == "sqlite":
+        _ensure_sqlite_directory_exists(url)
+        _configure_sqlite(engine, busy_timeout_ms=sqlite_busy_timeout_ms)
+    else:
+        _configure_postgresql(
+            engine, statement_timeout_ms=statement_timeout_ms, application_name=application_name
+        )
+
+    return engine
+
+
+def _ensure_sqlite_directory_exists(url: str) -> None:
+    """Create the SQLite file's parent directory, so a fresh install has somewhere to write.
+
+    A no-op for ``:memory:`` and for an already-existing directory.
+    """
+    # `URL.database`, not a hand-rolled parse: the sqlite dialect owns the rule for how many
+    # leading slashes separate "sqlite://" from an absolute path, and getting it wrong turns
+    # "sqlite:////tmp/x" into the relative "tmp/x" against whatever the cwd happens to be.
+    database = make_url(url).database
+    if not database or database == ":memory:":
+        return
+    Path(database).parent.mkdir(parents=True, exist_ok=True)
+
+
+def _raise_if_busy(exc: SAOperationalError, *, busy_timeout_ms: int) -> None:
+    """Translate a SQLite busy/snapshot-busy failure into :class:`StorageBusy`.
+
+    Re-raises anything else unchanged, so a genuine schema or syntax error at ``BEGIN`` time — not
+    that one is expected — is never miscast as contention.
+    """
+    orig = exc.orig
+    code = getattr(orig, "sqlite_errorcode", None)
+    if code in (sqlite3.SQLITE_BUSY, getattr(sqlite3, "SQLITE_BUSY_SNAPSHOT", -1)):
+        raise StorageBusy(
+            f"SQLite database is locked (busy_timeout={busy_timeout_ms}ms exceeded).",
+            details={"busy_timeout_ms": busy_timeout_ms},
+        ) from exc
+    raise exc
+
+
+def _configure_sqlite(engine: Engine, *, busy_timeout_ms: int) -> None:
+    """Wire pragmas and ``BEGIN IMMEDIATE`` onto every connection this engine opens."""
+
+    @event.listens_for(engine, "connect")
+    def _on_connect(dbapi_connection: Any, _connection_record: Any) -> None:
+        # Hand transaction control to SQLAlchemy entirely: pysqlite's own implicit-BEGIN behaviour
+        # and our explicit "begin" hook below would otherwise fight over who opens the
+        # transaction, producing "cannot start a transaction within a transaction".
+        dbapi_connection.isolation_level = None
+        cursor = dbapi_connection.cursor()
+        try:
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.execute("PRAGMA journal_mode=WAL")
+            cursor.execute(f"PRAGMA busy_timeout={int(busy_timeout_ms)}")
+            cursor.execute("PRAGMA synchronous=NORMAL")
+        finally:
+            cursor.close()
+
+    @event.listens_for(engine, "begin")
+    def _on_begin(connection: Any) -> None:
+        # A connection explicitly switched to AUTOCOMMIT (e.g. VACUUM, which cannot run inside any
+        # transaction on SQLite) still fires this event — SQLAlchemy's "begin" hook does not know
+        # what AUTOCOMMIT means, only this dialect-specific listener does. Forcing a literal
+        # BEGIN IMMEDIATE onto such a connection is exactly the failure that opts it out here.
+        options = connection.get_execution_options()
+        if options.get("isolation_level") == "AUTOCOMMIT":
+            connection.exec_driver_sql("PRAGMA query_only=OFF")
+            return
+        if options.get(READ_ONLY_EXECUTION_OPTION):
+            # Plain BEGIN — deferred. A transaction that only reads never has to upgrade to the
+            # write lock, so the snapshot hazard IMMEDIATE exists to avoid cannot arise, and
+            # declaring it a writer would throw away WAL's concurrent reads for nothing.
+            connection.exec_driver_sql("PRAGMA query_only=ON")
+            try:
+                connection.exec_driver_sql("BEGIN")
+            except SAOperationalError as exc:
+                _raise_if_busy(exc, busy_timeout_ms=busy_timeout_ms)
+            return
+        # `query_only` is set explicitly on *both* paths, every transaction, rather than being
+        # cleaned up after the read-only one. A reset that only runs on the way out is a reset
+        # that does not run when the way out is an exception, and the failure mode — a pooled
+        # connection stuck read-only, rejecting writes for the rest of its life — is both silent
+        # and very hard to trace back to here.
+        connection.exec_driver_sql("PRAGMA query_only=OFF")
+        try:
+            connection.exec_driver_sql("BEGIN IMMEDIATE")
+        except SAOperationalError as exc:
+            _raise_if_busy(exc, busy_timeout_ms=busy_timeout_ms)
+
+
+def _configure_postgresql(
+    engine: Engine, *, statement_timeout_ms: int | None, application_name: str | None
+) -> None:
+    """Apply ``statement_timeout``/``lock_timeout``/``application_name`` on every connection."""
+
+    @event.listens_for(engine, "connect")
+    def _on_connect(dbapi_connection: Any, _connection_record: Any) -> None:
+        cursor = dbapi_connection.cursor()
+        try:
+            # `set_config(...)`, not `SET ... = %s`. PostgreSQL's SET is a utility statement whose
+            # value is parsed as a literal, so a bind parameter in it is a syntax error at "$1" —
+            # every connection carrying an application_name failed outright. set_config is the
+            # function form and takes ordinary parameters, which also keeps the value off the
+            # statement string entirely.
+            if statement_timeout_ms is not None:
+                timeout = str(int(statement_timeout_ms))
+                cursor.execute("SELECT set_config('statement_timeout', %s, false)", (timeout,))
+                cursor.execute("SELECT set_config('lock_timeout', %s, false)", (timeout,))
+            if application_name is not None:
+                cursor.execute(
+                    "SELECT set_config('application_name', %s, false)", (application_name,)
+                )
+        finally:
+            cursor.close()

weightsdb/errors.py

@@ -0,0 +1,83 @@
+"""weightsdb.errors — the database error hierarchy.
+
+The contract every application in the suite maps its own database-layer failures to
+([spec §13](../../../docs/packages/weightsdb/spec.md)). Extracted from FreeWeight's
+``infrastructure.db.errors``, which was written "as if it were WeightsDB's own error module" for
+exactly this move; the codes below are unchanged by the extraction.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from baseaicore import SuiteError
+
+__all__ = [
+    "DatabaseError",
+    "DatabaseUnavailable",
+    "MigrationFailed",
+    "MigrationRequired",
+    "SchemaAhead",
+    "StorageBusy",
+    "StorageFull",
+]
+
+
+class DatabaseError(SuiteError):
+    """Base for every error raised by this package."""
+
+    code: ClassVar[str] = "DATABASE_ERROR"
+
+
+class MigrationRequired(DatabaseError):
+    """The schema is behind head and this dialect does not auto-migrate.
+
+    ``details`` always carries ``current``, ``head`` and ``command`` so the caller can print the
+    exact upgrade invocation without composing it itself.
+    """
+
+    code: ClassVar[str] = "MIGRATION_REQUIRED"
+
+
+class MigrationFailed(DatabaseError):
+    """A migration raised partway through ``upgrade`` or ``downgrade``.
+
+    On SQLite the pre-migration backup has already been restored by the time this is raised, and
+    ``details["restored"]`` is ``True``. On PostgreSQL no automatic restore is attempted (spec
+    §11.4); ``details`` instead names the revision reached and the backup to restore from.
+    """
+
+    code: ClassVar[str] = "MIGRATION_FAILED"
+
+
+class DatabaseUnavailable(DatabaseError):
+    """The configured database could not be reached or opened.
+
+    ``details["database_url"]`` is always redacted (credentials stripped, see
+    :func:`weightsdb.redaction.redact_url`) before this error is constructed — never pass a raw URL
+    here.
+    """
+
+    code: ClassVar[str] = "DATABASE_UNAVAILABLE"
+
+
+class SchemaAhead(DatabaseError):
+    """The database's revision is newer than any this build knows about.
+
+    Means the database was written by a later application version; running against it would risk
+    misreading rows this build's models do not describe.
+    """
+
+    code: ClassVar[str] = "SCHEMA_AHEAD"
+
+
+class StorageBusy(DatabaseError):
+    """SQLite reported ``SQLITE_BUSY`` beyond the configured ``busy_timeout``."""
+
+    code: ClassVar[str] = "STORAGE_BUSY"
+
+
+class StorageFull(DatabaseError):
+    """The device backing the database or its backup directory is out of space."""
+
+    code: ClassVar[str] = "STORAGE_FULL"

weightsdb/health.py

@@ -0,0 +1,318 @@
+"""weightsdb.health — the ``database`` component every application's health endpoint reports from.
+
+Never raises: a health check that itself crashes takes the whole health endpoint down with it,
+which is exactly the outcome graceful degradation exists to prevent (the same convention FreeWeight
+and LoadCoach already apply at their own health-report layer, moved one level down so both build
+their ``database`` component from a single, shared implementation — spec §17).
+"""
+
+from __future__ import annotations
+
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from sqlalchemy import text
+from sqlalchemy.exc import SQLAlchemyError
+
+from weightsdb.backup import database_size_bytes, integrity_check
+
+if TYPE_CHECKING:
+    from sqlalchemy import Engine
+
+    from weightsdb.migrations import MigrationRunner
+
+__all__ = ["DatabaseHealth", "database_health", "is_network_filesystem"]
+
+type ComponentStatus = Literal["ok", "degraded", "unavailable"]
+
+# No configuration reaches this module (spec §12 — WeightsDB reads no config file or environment
+# variable), so the two judgement calls below are fixed, documented constants rather than tunable
+# parameters. An application that wants a different bar reports raw values itself instead of
+# calling this function — see docs/adoption-checklist.md.
+_LOW_DISK_FLOOR_BYTES = 100 * 1024 * 1024  # 100 MiB
+_STALE_BACKUP_AFTER_SECONDS = 7 * 24 * 3600  # 7 days
+
+_NETWORK_FILESYSTEM_TYPES = frozenset(
+    {
+        "nfs",
+        "nfs4",
+        "cifs",
+        "smb",
+        "smbfs",
+        "smb2",
+        "9p",
+        "afs",
+        "afpfs",
+        "fuse.sshfs",
+        "glusterfs",
+        "ceph",
+        "davfs",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseHealth:
+    """The full ``database`` health snapshot, dialect-portable.
+
+    Attributes:
+        dialect: ``"sqlite"`` or ``"postgresql"``.
+        version: The backend's own version string, or ``None`` if it could not be read.
+        current_revision: The database's current Alembic revision, or ``None`` — either unmigrated,
+            or ``runner`` was not given.
+        head_revision: The revision this build's migrations produce, or ``None`` when ``runner``
+            was not given.
+        is_at_head: Whether ``current_revision == head_revision``, or ``None`` when ``runner`` was
+            not given.
+        journal_mode: SQLite's journal mode (normally ``"wal"``), or ``None`` on PostgreSQL.
+        size_bytes: How much disk the database occupies.
+        free_space_bytes: Free space on the containing device, or ``None`` if it could not be read.
+        last_backup_age_seconds: Age of the newest file under the conventional
+            ``<sqlite file>/../backups`` directory, or ``None`` on PostgreSQL (which has no such
+            convention) or when no backup has ever been taken.
+        integrity_ok: Whether the integrity check passed.
+        integrity_detail: The backend's own integrity report.
+        network_filesystem: Whether the SQLite file appears to live on a network filesystem
+            (spec §16); always ``None`` on PostgreSQL and whenever this cannot be determined
+            (non-Linux, ``/proc/mounts`` unreadable) — ``None`` means "undetermined", not "no".
+        status: The overall verdict.
+        degraded_reasons: Every condition that contributed to a non-``ok`` status, empty when
+            ``status == "ok"``.
+    """
+
+    dialect: str
+    version: str | None
+    current_revision: str | None
+    head_revision: str | None
+    is_at_head: bool | None
+    journal_mode: str | None
+    size_bytes: int
+    free_space_bytes: int | None
+    last_backup_age_seconds: float | None
+    integrity_ok: bool
+    integrity_detail: str
+    network_filesystem: bool | None
+    status: ComponentStatus
+    degraded_reasons: tuple[str, ...]
+
+
+def _read_proc_mounts() -> list[tuple[str, str]] | None:
+    """Return ``(mount_point, fs_type)`` pairs from ``/proc/mounts``, or ``None`` if unreadable."""
+    try:
+        with Path("/proc/mounts").open(encoding="utf-8") as handle:
+            lines = handle.readlines()
+    except OSError:
+        return None
+    entries: list[tuple[str, str]] = []
+    for line in lines:
+        parts = line.split()
+        if len(parts) >= 3:
+            entries.append((parts[1], parts[2]))
+    return entries
+
+
+def is_network_filesystem(
+    path: Path, *, mounts: list[tuple[str, str]] | None = None
+) -> bool | None:
+    """Return whether ``path`` appears to live on a network filesystem (spec §16).
+
+    Best-effort and Linux-only: reads ``/proc/mounts`` (or the ``mounts`` table given, for tests)
+    and finds the longest-prefix mount point containing ``path``, then checks its filesystem type
+    against a list of known network filesystem types (NFS, CIFS/SMB, 9p, and similar).
+
+    Args:
+        path: The file to check. Need not exist yet — only its ancestry is examined.
+        mounts: ``(mount_point, fs_type)`` pairs, as read from ``/proc/mounts``. ``None`` reads the
+            real table; a test supplies one directly rather than mocking the filesystem.
+
+    Returns:
+        ``True``/``False`` when determinable; ``None`` when it cannot be (no ``mounts`` table
+        available, or no entry contains ``path``) — undetermined, not "no".
+    """
+    entries = mounts if mounts is not None else _read_proc_mounts()
+    if not entries:
+        return None
+    resolved = path.absolute()
+    best_match: str | None = None
+    best_depth = -1
+    for mount_point, fs_type in entries:
+        mount_path = Path(mount_point)
+        if mount_path != resolved and mount_path not in resolved.parents:
+            continue
+        depth = len(mount_path.parts)
+        if depth > best_depth:
+            best_depth = depth
+            best_match = fs_type
+    if best_match is None:
+        return None
+    return best_match.lower() in _NETWORK_FILESYSTEM_TYPES
+
+
+def _backend_version(engine: Engine) -> str | None:
+    try:
+        with engine.connect() as connection:
+            if engine.dialect.name == "sqlite":
+                return str(connection.execute(text("SELECT sqlite_version()")).scalar_one())
+            return str(connection.execute(text("SHOW server_version")).scalar_one())
+    except SQLAlchemyError:
+        return None
+
+
+def _journal_mode(engine: Engine) -> str | None:
+    if engine.dialect.name != "sqlite":
+        return None
+    try:
+        with engine.connect() as connection:
+            return str(connection.execute(text("PRAGMA journal_mode")).scalar_one())
+    except SQLAlchemyError:
+        return None
+
+
+def _free_space_bytes(engine: Engine) -> int | None:
+    try:
+        if engine.dialect.name == "sqlite":
+            database = engine.url.database
+            if not database or database == ":memory:":
+                return None
+            target = Path(database).parent
+        else:
+            # No local path for a remote PostgreSQL server; report on the current process's own
+            # filesystem as the best available proxy — an application that needs the *server's*
+            # free space monitors that server directly.
+            target = Path.cwd()
+        while not target.exists():
+            parent = target.parent
+            if parent == target:
+                return None
+            target = parent
+        return shutil.disk_usage(target).free
+    except OSError:
+        return None
+
+
+def _last_backup_age_seconds(engine: Engine, *, now: float) -> float | None:
+    if engine.dialect.name != "sqlite":
+        return None
+    database = engine.url.database
+    if not database or database == ":memory:":
+        return None
+    backups_directory = Path(database).parent / "backups"
+    if not backups_directory.is_dir():
+        return None
+    newest: float | None = None
+    for candidate in backups_directory.iterdir():
+        if not candidate.is_file():
+            continue
+        mtime = candidate.stat().st_mtime
+        if newest is None or mtime > newest:
+            newest = mtime
+    if newest is None:
+        return None
+    return max(0.0, now - newest)
+
+
+def _network_filesystem_for(engine: Engine) -> bool | None:
+    if engine.dialect.name != "sqlite":
+        return None
+    database = engine.url.database
+    if not database or database == ":memory:":
+        return None
+    return is_network_filesystem(Path(database))
+
+
+def database_health(engine: Engine, runner: MigrationRunner | None = None) -> DatabaseHealth:
+    """Build the full ``database`` health snapshot for ``engine``.
+
+    Args:
+        engine: The engine to report on — normally the same one the application is serving from
+            (spec §17: this function supplies the ``database`` component of every application's
+            health endpoint).
+        runner: The application's own :class:`~weightsdb.migrations.MigrationRunner`, for the
+            revision-vs-head comparison. ``None`` skips it — ``current_revision``, ``head_revision``
+            and ``is_at_head`` are reported as ``None`` rather than raising, since a package that
+            owns no schema has no revision history of its own to fall back on.
+
+    Returns:
+        The :class:`DatabaseHealth`. Never raises: a database that cannot be reached at all is
+        reported as ``status="unavailable"``, not an exception.
+    """
+    dialect = engine.dialect.name
+    try:
+        integrity = integrity_check(engine)
+    except Exception as exc:  # noqa: BLE001 — a health check must not itself raise
+        return DatabaseHealth(
+            dialect=dialect,
+            version=None,
+            current_revision=None,
+            head_revision=None,
+            is_at_head=None,
+            journal_mode=None,
+            size_bytes=0,
+            free_space_bytes=None,
+            last_backup_age_seconds=None,
+            integrity_ok=False,
+            integrity_detail="unreachable",
+            network_filesystem=None,
+            status="unavailable",
+            degraded_reasons=(f"database unreachable: {exc}",),
+        )
+
+    version = _backend_version(engine)
+    journal_mode = _journal_mode(engine)
+    size_bytes = database_size_bytes(engine)
+    free_space = _free_space_bytes(engine)
+    backup_age = _last_backup_age_seconds(engine, now=time.time())
+    network_fs = _network_filesystem_for(engine)
+
+    current_revision: str | None = None
+    head_revision: str | None = None
+    is_at_head: bool | None = None
+    is_ahead_of_head = False
+    if runner is not None:
+        current_revision = runner.current()
+        heads = runner.heads()
+        head_revision = heads[0] if heads else None
+        is_at_head = current_revision == head_revision if head_revision is not None else None
+        is_ahead_of_head = (
+            current_revision is not None
+            and not is_at_head
+            and current_revision not in runner.known_revisions()
+        )
+
+    reasons: list[str] = []
+    if is_ahead_of_head:
+        reasons.append(
+            f"database is ahead of this build: at {current_revision!r}, a revision this build's "
+            "migrations do not produce — it was likely written by a newer application version"
+        )
+    elif is_at_head is False:
+        reasons.append(f"pending migration: at {current_revision!r}, head is {head_revision!r}")
+    if not integrity.ok:
+        reasons.append(f"integrity check failed: {integrity.detail}")
+    if free_space is not None and free_space < _LOW_DISK_FLOOR_BYTES:
+        reasons.append(f"low disk space: {free_space} bytes free")
+    if backup_age is not None and backup_age > _STALE_BACKUP_AFTER_SECONDS:
+        reasons.append(f"stale backup: last one is {backup_age / 86400:.1f} days old")
+    if network_fs:
+        reasons.append("database file appears to be on a network filesystem")
+
+    status: ComponentStatus = "degraded" if reasons else "ok"
+    return DatabaseHealth(
+        dialect=dialect,
+        version=version,
+        current_revision=current_revision,
+        head_revision=head_revision,
+        is_at_head=is_at_head,
+        journal_mode=journal_mode,
+        size_bytes=size_bytes,
+        free_space_bytes=free_space,
+        last_backup_age_seconds=backup_age,
+        integrity_ok=integrity.ok,
+        integrity_detail=integrity.detail,
+        network_filesystem=network_fs,
+        status=status,
+        degraded_reasons=tuple(reasons),
+    )