prashna 0.2.0__py3-none-any.whl

prashna/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m prashna` runs the `prashna` command."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

prashna/auth.py

@@ -0,0 +1,198 @@
+"""Admin auth: password hashing + signed session cookie.
+
+Single-admin model for now (local self-host). Multi-user/multi-org is a
+future expansion; keep this module the seam where that change lands.
+"""
+from __future__ import annotations
+
+import os
+import secrets as pysecrets
+from pathlib import Path
+from typing import Annotated
+
+import bcrypt
+from fastapi import Cookie, Depends, HTTPException, Response
+from itsdangerous import BadSignature, SignatureExpired, TimestampSigner
+from sqlalchemy import select
+from sqlalchemy.orm import Session as DbSession
+
+from . import models as m
+from .db import DB_PATH, get_db
+
+COOKIE_NAME = "prashna_admin"
+SESSION_MAX_AGE = 60 * 60 * 24 * 30  # 30 days
+# bcrypt silently truncates inputs beyond 72 bytes; reject longer to avoid
+# users believing a long passphrase is fully protecting them.
+MAX_PASSWORD_BYTES = 72
+
+# Operator-free state lives beside the database, so a backup of the data
+# folder carries it: the signing key (UC-X-07) and, until an admin exists,
+# the one-time setup token (UC-A-01).
+DATA_DIR = DB_PATH.parent
+SECRET_KEY_FILE = DATA_DIR / "secret-key"
+SETUP_TOKEN_FILE = DATA_DIR / "setup-token"
+# Generated values carry a fixed prefix so a scanner (scripts/check_pii.py)
+# recognises a leaked key or token in any file, whatever it is called.
+SECRET_KEY_PREFIX = "prashna_sk_"  # pragma: allowlist secret
+SETUP_TOKEN_PREFIX = "prashna_st_"
+
+
+def _write_private(path: Path, value: str) -> None:
+    """Create `path` readable only by this user; fail if it already exists."""
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(value + "\n")
+
+
+def _read_or_create(path: Path, make) -> str:
+    try:
+        value = path.read_text().strip()
+        if value:
+            return value
+    except FileNotFoundError:
+        pass
+    value = make()
+    try:
+        _write_private(path, value)
+    except FileExistsError:  # another start won the race; use its value
+        return path.read_text().strip()
+    return value
+
+
+def _resolve_secret(env_value: str | None, key_file: Path) -> tuple[str, bool]:
+    """Return (signing_key, is_ephemeral) (UC-X-07).
+
+    PRASHNA_SECRET_KEY wins. Otherwise the key is read from, or created in,
+    `key_file`, so sessions survive restarts with no operator step. Only if
+    that file can't be used do we fall back to a process-lifetime key
+    (ephemeral), which startup warns about.
+    """
+    if env_value:
+        return env_value, False
+    try:
+        return _read_or_create(key_file, lambda: SECRET_KEY_PREFIX + pysecrets.token_urlsafe(48)), False
+    except OSError:
+        return SECRET_KEY_PREFIX + pysecrets.token_urlsafe(32), True
+
+
+_secret, SECRET_KEY_IS_EPHEMERAL = _resolve_secret(os.environ.get("PRASHNA_SECRET_KEY"), SECRET_KEY_FILE)
+_signer = TimestampSigner(_secret)
+
+
+def new_signer() -> TimestampSigner:
+    """A signer over the same app secret — for one-off signed tokens like
+    the GitHub OAuth `state` (CSRF) that aren't session cookies."""
+    return TimestampSigner(_secret)
+
+
+def hash_password(pw: str) -> str:
+    pw_bytes = pw.encode("utf-8")
+    if len(pw_bytes) > MAX_PASSWORD_BYTES:
+        raise HTTPException(400, f"password must be at most {MAX_PASSWORD_BYTES} bytes")
+    return bcrypt.hashpw(pw_bytes, bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(pw: str, hashed: str) -> bool:
+    try:
+        return bcrypt.checkpw(pw.encode("utf-8"), hashed.encode("utf-8"))
+    except (ValueError, TypeError):
+        return False
+
+
+def issue_session(response: Response, user_id: int, session_version: int, *, secure: bool) -> None:
+    # Cookie value is "user_id:session_version". The session_version comes
+    # from the User row; bumping it on password change invalidates older
+    # cookies even though they remain validly signed.
+    token = _signer.sign(f"{user_id}:{session_version}").decode()
+    response.set_cookie(
+        COOKIE_NAME,
+        token,
+        max_age=SESSION_MAX_AGE,
+        httponly=True,
+        samesite="lax",
+        secure=secure,
+    )
+
+
+def clear_session(response: Response) -> None:
+    response.delete_cookie(COOKIE_NAME)
+
+
+def _parse_cookie(cookie: str | None) -> tuple[int, int] | None:
+    """Return (user_id, session_version) from a signed cookie, or None."""
+    if not cookie:
+        return None
+    try:
+        raw = _signer.unsign(cookie, max_age=SESSION_MAX_AGE).decode()
+    except (BadSignature, SignatureExpired):
+        return None
+    # Backwards-compat for older cookies (no session_version field).
+    if ":" in raw:
+        try:
+            uid_str, ver_str = raw.split(":", 1)
+            return int(uid_str), int(ver_str)
+        except ValueError:
+            return None
+    try:
+        return int(raw), 1
+    except ValueError:
+        return None
+
+
+def current_admin(
+    prashna_admin: Annotated[str | None, Cookie()] = None,
+    db: DbSession = Depends(get_db),
+) -> m.User:
+    parsed = _parse_cookie(prashna_admin)
+    if parsed is None:
+        raise HTTPException(401, "Not authenticated")
+    uid, ver = parsed
+    u = db.get(m.User, uid)
+    if u is None or u.session_version != ver:
+        raise HTTPException(401, "Not authenticated")
+    return u
+
+
+def optional_admin(
+    prashna_admin: Annotated[str | None, Cookie()] = None,
+    db: DbSession = Depends(get_db),
+) -> m.User | None:
+    parsed = _parse_cookie(prashna_admin)
+    if parsed is None:
+        return None
+    uid, ver = parsed
+    u = db.get(m.User, uid)
+    if u is None or u.session_version != ver:
+        return None
+    return u
+
+
+def admin_exists(db: DbSession) -> bool:
+    return db.scalar(select(m.User.id).limit(1)) is not None
+
+
+# ---------- one-time first-admin setup token (UC-A-01) ----------
+
+def setup_token(db: DbSession) -> str | None:
+    """The token that authorizes creating the first admin, or None once an
+    admin exists. PRASHNA_SETUP_TOKEN wins; otherwise a random token is kept
+    in SETUP_TOKEN_FILE and reused across restarts until setup completes."""
+    if admin_exists(db):
+        retire_setup_token()
+        return None
+    env_token = os.environ.get("PRASHNA_SETUP_TOKEN", "").strip()
+    if env_token:
+        return env_token
+    return _read_or_create(SETUP_TOKEN_FILE, lambda: SETUP_TOKEN_PREFIX + pysecrets.token_urlsafe(24))
+
+
+def setup_token_matches(db: DbSession, supplied: object) -> bool:
+    expected = setup_token(db)
+    return bool(expected) and isinstance(supplied, str) and pysecrets.compare_digest(supplied, expected)
+
+
+def retire_setup_token() -> None:
+    try:
+        SETUP_TOKEN_FILE.unlink()
+    except FileNotFoundError:
+        pass

prashna/backup.py

@@ -0,0 +1,194 @@
+"""Create and restore portable Prashna data archives.
+
+This module is intentionally runnable inside the published container so a
+Docker-only installation does not need Python or sqlite tooling on the host.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import shutil
+import sqlite3
+import tarfile
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
+
+ARCHIVE_FORMAT = 1
+
+
+def _db_path() -> Path:
+    return Path(os.environ.get("PRASHNA_DB_PATH", "/data/prashna.db"))
+
+
+def _uploads_path() -> Path:
+    return Path(os.environ.get("PRASHNA_UPLOADS_DIR", "/app/uploads"))
+
+
+def _add_bytes(archive: tarfile.TarFile, name: str, payload: bytes) -> None:
+    info = tarfile.TarInfo(name)
+    info.size = len(payload)
+    info.mode = 0o600
+    info.mtime = 0
+    archive.addfile(info, io.BytesIO(payload))
+
+
+def create_archive(destination: Path) -> Path:
+    """Create a consistent SQLite + uploads archive at *destination*."""
+    source_db = _db_path()
+    uploads = _uploads_path()
+    if not source_db.is_file():
+        raise RuntimeError(f"database not found: {source_db}")
+    destination = destination.resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="prashna-backup-") as temp:
+        snapshot = Path(temp) / "prashna.db"
+        with sqlite3.connect(source_db) as source, sqlite3.connect(snapshot) as target:
+            source.backup(target)
+
+        manifest = {
+            "format": ARCHIVE_FORMAT,
+            "created_at": datetime.now(UTC).isoformat(),
+            "database": "prashna.db",
+            "uploads": "uploads/",
+        }
+        with tarfile.open(destination, "w:gz", format=tarfile.PAX_FORMAT) as archive:
+            _add_bytes(
+                archive,
+                "manifest.json",
+                (json.dumps(manifest, sort_keys=True) + "\n").encode(),
+            )
+            archive.add(snapshot, arcname="prashna.db", recursive=False)
+            if uploads.is_dir():
+                for path in sorted(uploads.rglob("*")):
+                    if path.is_symlink() or not path.is_file():
+                        continue
+                    relative = path.relative_to(uploads).as_posix()
+                    archive.add(path, arcname=f"uploads/{relative}", recursive=False)
+    return destination
+
+
+def _extract_checked(archive_path: Path, destination: Path) -> None:
+    seen: set[str] = set()
+    with tarfile.open(archive_path, "r:gz") as archive:
+        for member in archive.getmembers():
+            name = PurePosixPath(member.name)
+            if (
+                member.name in seen
+                or name.is_absolute()
+                or ".." in name.parts
+                or member.issym()
+                or member.islnk()
+                or not (
+                    member.name in {"manifest.json", "prashna.db"}
+                    or (name.parts and name.parts[0] == "uploads")
+                )
+            ):
+                raise RuntimeError(f"unsafe backup member: {member.name}")
+            seen.add(member.name)
+            if member.isdir():
+                (destination / Path(*name.parts)).mkdir(parents=True, exist_ok=True)
+                continue
+            if not member.isfile():
+                raise RuntimeError(f"unsupported backup member: {member.name}")
+            source = archive.extractfile(member)
+            if source is None:
+                raise RuntimeError(f"cannot read backup member: {member.name}")
+            target = destination / Path(*name.parts)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with target.open("wb") as output:
+                shutil.copyfileobj(source, output)
+
+    required = {"manifest.json", "prashna.db"}
+    if not required.issubset(seen):
+        raise RuntimeError("backup is missing manifest.json or prashna.db")
+
+
+def _validate_snapshot(snapshot: Path, manifest_path: Path) -> None:
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if manifest.get("format") != ARCHIVE_FORMAT:
+        raise RuntimeError(f"unsupported backup format: {manifest.get('format')!r}")
+    with sqlite3.connect(f"file:{snapshot}?mode=ro", uri=True) as connection:
+        result = connection.execute("PRAGMA quick_check").fetchone()
+        if not result or result[0] != "ok":
+            raise RuntimeError(f"backup database failed quick_check: {result!r}")
+        tables = {
+            row[0]
+            for row in connection.execute(
+                "SELECT name FROM sqlite_master WHERE type = 'table'"
+            ).fetchall()
+        }
+    if "users" not in tables or "sessions" not in tables:
+        raise RuntimeError("backup database is not a Prashna database")
+
+
+def restore_archive(archive_path: Path, *, confirmed: bool = False) -> Path:
+    """Restore an archive after creating a sibling pre-restore backup."""
+    if not confirmed:
+        raise RuntimeError("restore requires --confirm and a stopped Prashna service")
+    archive_path = archive_path.resolve()
+    if not archive_path.is_file():
+        raise RuntimeError(f"backup not found: {archive_path}")
+
+    with tempfile.TemporaryDirectory(prefix="prashna-restore-") as temp:
+        extracted = Path(temp)
+        _extract_checked(archive_path, extracted)
+        snapshot = extracted / "prashna.db"
+        _validate_snapshot(snapshot, extracted / "manifest.json")
+
+        stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+        pre_restore = archive_path.with_name(f"prashna-pre-restore-{stamp}.tar.gz")
+        create_archive(pre_restore)
+
+        target_db = _db_path()
+        target_db.parent.mkdir(parents=True, exist_ok=True)
+        staged_db = target_db.with_name(f".{target_db.name}.restore")
+        shutil.copy2(snapshot, staged_db)
+        os.replace(staged_db, target_db)
+        for suffix in ("-wal", "-shm", "-journal"):
+            target_db.with_name(target_db.name + suffix).unlink(missing_ok=True)
+
+        uploads = _uploads_path()
+        uploads.mkdir(parents=True, exist_ok=True)
+        for current in uploads.iterdir():
+            if current.is_dir() and not current.is_symlink():
+                shutil.rmtree(current)
+            else:
+                current.unlink()
+        restored_uploads = extracted / "uploads"
+        if restored_uploads.is_dir():
+            for source in restored_uploads.rglob("*"):
+                relative = source.relative_to(restored_uploads)
+                target = uploads / relative
+                if source.is_dir():
+                    target.mkdir(parents=True, exist_ok=True)
+                elif source.is_file():
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(source, target)
+    return pre_restore
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    create = commands.add_parser("create", help="create a SQLite + uploads archive")
+    create.add_argument("archive", type=Path)
+    restore = commands.add_parser("restore", help="restore an archive while the app is stopped")
+    restore.add_argument("archive", type=Path)
+    restore.add_argument("--confirm", action="store_true")
+    args = parser.parse_args(argv)
+
+    if args.command == "create":
+        print(create_archive(args.archive))
+        return 0
+    pre_restore = restore_archive(args.archive, confirmed=args.confirm)
+    print(f"restored {args.archive}; previous state: {pre_restore}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

prashna/cli.py

@@ -0,0 +1,134 @@
+"""The `prashna` command: run Prashna on this computer (UC-X-15).
+
+    prashna                    start on http://127.0.0.1:8000 and open the browser
+    prashna --port 8080        use another port
+    prashna --data-dir DIR     keep the database and uploads in DIR
+    prashna backup create F    archive the data folder (see `prashna backup --help`)
+
+Data lives in the per-user app-data folder unless --data-dir or
+PRASHNA_DATA_DIR says otherwise. On the first run the browser opens the
+one-time setup page, so creating the admin needs no copy-and-paste.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import socket
+import subprocess
+import sys
+import threading
+import time
+import webbrowser
+from importlib import metadata
+from pathlib import Path
+
+
+def _version() -> str:
+    try:
+        return metadata.version("prashna")
+    except metadata.PackageNotFoundError:
+        return "0+unknown"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prashna", description="Live Q&A and quizzes for any session with an audience.")
+    parser.add_argument("--host", default="127.0.0.1",
+                        help="address to listen on (default 127.0.0.1; 0.0.0.0 to allow other devices)")
+    parser.add_argument("--port", type=int, default=8000, help="port to listen on (default 8000)")
+    parser.add_argument("--data-dir", help="folder for the database and uploads "
+                        "(default: PRASHNA_DATA_DIR or your app-data folder)")
+    parser.add_argument("--no-browser", action="store_true", help="don't open the browser")
+    parser.add_argument("--version", action="version", version=f"prashna {_version()}")
+    commands = parser.add_subparsers(dest="command")
+    backup = commands.add_parser("backup", add_help=False, help="create or restore a backup of the data folder")
+    backup.add_argument("args", nargs=argparse.REMAINDER)
+    return parser
+
+
+def _data_dir(arg: str | None) -> Path:
+    chosen = arg or os.environ.get("PRASHNA_DATA_DIR")
+    if chosen:
+        return Path(chosen).expanduser().resolve()
+    from .db import default_data_dir
+    return default_data_dir()
+
+
+def _port_free(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET6 if ":" in host else socket.AF_INET) as sock:
+        try:
+            sock.bind((host, port))
+        except OSError:
+            return False
+    return True
+
+
+def _launch_browser(url: str) -> None:
+    """Open `url`. A BROWSER setting (the usual way to choose a browser) is
+    launched directly: webbrowser's discovery of every installed browser can
+    take several seconds on Linux desktops before it tries BROWSER."""
+    for entry in filter(None, os.environ.get("BROWSER", "").split(os.pathsep)):
+        command = entry.replace("%s", url) if "%s" in entry else f"{entry} {shlex.quote(url)}"
+        try:
+            subprocess.Popen(shlex.split(command))
+            return
+        except OSError:
+            continue
+    webbrowser.open(url)
+
+
+def _open_when_ready(host: str, port: int, url: str) -> None:
+    deadline = time.monotonic() + 30
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=0.5):
+                break
+        except OSError:
+            time.sleep(0.2)
+    _launch_browser(url)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    data_dir = _data_dir(args.data_dir)
+    data_dir.mkdir(parents=True, exist_ok=True)
+    # Set before the server modules are imported; they read these at import.
+    os.environ.setdefault("PRASHNA_DB_PATH", str(data_dir / "prashna.db"))
+    os.environ.setdefault("PRASHNA_UPLOADS_DIR", str(data_dir / "uploads"))
+
+    if args.command == "backup":
+        from .backup import main as backup_main
+        return backup_main(args.args)
+
+    if not _port_free(args.host, args.port):
+        print(f"Port {args.port} is already in use. Start on another port, "
+              f"for example: prashna --port {args.port + 1}", file=sys.stderr)
+        return 1
+
+    from . import auth, db
+    db.init_db()
+    with db.SessionLocal() as session:
+        token = auth.setup_token(session)
+    shown_host = "127.0.0.1" if args.host in ("0.0.0.0", "::") else args.host
+    address = f"http://{shown_host}:{args.port}"
+    url = f"{address}/#setup={token}" if token else f"{address}/"
+
+    print(f"\nPrashna is running at {address}")
+    print(f"Data folder: {data_dir}")
+    if token:
+        if args.no_browser:
+            print(f"Create your admin account here (one-time link): {url}")
+        else:
+            print("Opening the one-time setup page in your browser to create your admin account.")
+    print("Press Ctrl+C to stop.\n", flush=True)
+    if not args.no_browser:
+        threading.Thread(target=_open_when_ready, args=(shown_host, args.port, url), daemon=True).start()
+
+    import uvicorn
+    uvicorn.run("prashna.main:app", host=args.host, port=args.port, log_level="warning")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

prashna/db.py

@@ -0,0 +1,155 @@
+import os
+import sys
+from pathlib import Path
+
+from sqlalchemy import create_engine, event
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+
+from .diagnostics import log_diagnostic as _log_diagnostic
+
+
+def default_data_dir() -> Path:
+    """Where data lives when PRASHNA_DB_PATH / PRASHNA_UPLOADS_DIR are unset:
+    the platform's per-user app-data folder, for a source checkout too, so
+    the database and the generated secrets never land in a repository."""
+    if sys.platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local") / "prashna"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "prashna"
+    return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share") / "prashna"
+
+
+# Allow the DB location to be overridden via env (Docker volume in prod).
+DB_PATH = Path(os.environ.get("PRASHNA_DB_PATH") or default_data_dir() / "prashna.db")
+DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+engine = create_engine(
+    f"sqlite:///{DB_PATH}",
+    connect_args={"check_same_thread": False},
+    future=True,
+)
+
+# Per-connection SQLite pragmas:
+# - foreign_keys=ON: SQLite ignores ON DELETE CASCADE / FK constraints unless
+#   set per connection; without it orphaned rows are possible.
+# - journal_mode=WAL: readers don't block the single writer (and vice versa),
+#   which matters under a live quiz where many participants submit at once.
+# - busy_timeout=5000: a writer waits up to 5s for the lock instead of
+#   erroring immediately with "database is locked".
+# - synchronous=NORMAL: safe with WAL, much less fsync stalling under load.
+@event.listens_for(Engine, "connect")
+def _set_sqlite_pragmas(dbapi_conn, _conn_record):
+    try:
+        cursor = dbapi_conn.cursor()
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA busy_timeout=5000")
+        cursor.execute("PRAGMA synchronous=NORMAL")
+        cursor.close()
+    except Exception:
+        # Other dialects (Postgres etc.) don't need this; ignore quietly.
+        pass
+
+
+SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, future=True)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def init_db():
+    from . import models  # noqa: F401
+    Base.metadata.create_all(bind=engine)
+    _apply_additive_migrations()
+
+
+def _apply_additive_migrations(*, bind: Engine | None = None):
+    """Bridge gap between `create_all()` and additive column changes.
+
+    Prashna intentionally has no Alembic. `create_all` only creates
+    missing tables, not missing columns or indexes on existing tables. For
+    each supported additive change we introduce post-launch, add it here so
+    operators don't have to delete `prashna.db` on every model addition.
+    """
+    target = bind or engine
+    additive = [
+        # (table, column, ddl-snippet)
+        ("users", "session_version", "INTEGER NOT NULL DEFAULT 1"),
+        ("users", "github_id", "INTEGER"),
+        ("sessions", "participant_base_url", "VARCHAR(500)"),
+        ("sessions", "feedback_enabled", "BOOLEAN NOT NULL DEFAULT 0"),
+        ("participants", "email", "VARCHAR(254)"),
+        ("participants", "contact_number", "VARCHAR(40)"),
+        ("participants", "organization", "VARCHAR(120)"),
+        ("participants", "role", "VARCHAR(120)"),
+        ("participants", "linkedin_url", "VARCHAR(500)"),
+        ("participants", "photo_url", "VARCHAR(500)"),
+        ("participants", "current_work", "TEXT"),
+        ("participants", "learning_goal", "TEXT"),
+        ("quiz_questions", "graded", "BOOLEAN NOT NULL DEFAULT 1"),
+        ("quiz_version_questions", "graded", "BOOLEAN NOT NULL DEFAULT 1"),
+        ("quiz_runs", "show_live_counts", "BOOLEAN NOT NULL DEFAULT 0"),
+    ]
+    # Indexes to (re)create on existing DBs. `ALTER TABLE ADD COLUMN` can't
+    # carry UNIQUE/partial-index constraints; create those separately.
+    indexes = [
+        ("ix_users_github_id", "users", ["github_id"], True, None),
+        (
+            "uq_session_live_run",
+            "quiz_runs",
+            ["session_id"],
+            True,
+            "status = 'live'",
+        ),
+        ("ix_qsub_run_question", "quiz_submissions", ["quiz_run_id", "question_id"], False, None),
+    ]
+    with target.begin() as conn:
+        tables = {
+            row[0]
+            for row in conn.exec_driver_sql(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+        }
+        for table, column, ddl in additive:
+            if table not in tables:
+                continue
+            cols = {row[1] for row in conn.exec_driver_sql(
+                f"PRAGMA table_info({table})").fetchall()}
+            if column not in cols:
+                conn.exec_driver_sql(
+                    f"ALTER TABLE {table} ADD COLUMN {column} {ddl}")
+                _log_diagnostic(
+                    "db.migration",
+                    action="add_column",
+                    outcome="success",
+                    table=table,
+                    column=column,
+                )
+        for name, table, columns, unique, where in indexes:
+            if table not in tables:
+                continue
+            existing_cols = {
+                row[1] for row in conn.exec_driver_sql(f"PRAGMA table_info({table})")
+            }
+            if not set(columns).issubset(existing_cols):
+                continue
+            uniq = "UNIQUE " if unique else ""
+            where_sql = f" WHERE {where}" if where else ""
+            conn.exec_driver_sql(
+                f"CREATE {uniq}INDEX IF NOT EXISTS {name} ON {table} ({', '.join(columns)}){where_sql}")
+            _log_diagnostic(
+                "db.migration",
+                action="create_index",
+                outcome="success",
+                table=table,
+                index=name,
+            )