"""The tables, and how a database file gets from an old shape to this one. `SCHEMA` is the current shape. A new file is created from it and stamped with `LATEST`, so it never runs a migration. `MIGRATIONS` is how an existing file catches up: ordered, numbered, applied once each, tracked in SQLite's own `PRAGMA user_version`. Adding a column means editing both: the DDL in `SCHEMA` for new files, and an appended migration for old ones. Never renumber or edit a migration that has shipped. """ from __future__ import annotations import logging import sqlite3 from collections.abc import Callable log = logging.getLogger(__name__) SCHEMA = """ -- The string map a desk plugin is handed as `self.state`. One namespace shared -- by every plugin, so a plugin prefixes its keys. CREATE TABLE IF NOT EXISTS state ( key TEXT PRIMARY KEY, value TEXT NOT NULL ); """ #: Applied after `SCHEMA` or the migrations, every open. An index may name a #: column only a migration adds, which is why these are kept apart. INDEXES = """ """ #: The table whose absence marks a file that has never been a roledesk #: database, and is therefore created from `SCHEMA` rather than migrated. MARKER = "state" Step = str | Callable[[sqlite3.Connection], None] MIGRATIONS: tuple[tuple[int, str, Step], ...] = ( # Never run as a migration: a file without the marker table is created # from `SCHEMA` and stamped. It exists so the first real migration is 2. (1, "the first schema", ""), ) #: What a file created from `SCHEMA` today is already at. LATEST = MIGRATIONS[-1][0] def user_version(conn: sqlite3.Connection) -> int: return int(conn.execute("PRAGMA user_version").fetchone()[0]) def _stamp(conn: sqlite3.Connection, version: int) -> None: # PRAGMA takes no bound parameters; the value is an int from MIGRATIONS. conn.execute(f"PRAGMA user_version = {int(version)}") def _statements(script: str) -> list[str]: """A script split into statements, cut where `sqlite3.complete_statement` says one ends. Not `executescript`, which commits before it starts and autocommits each statement, so a failing migration would be half applied.""" statements, buffer = [], "" for line in script.splitlines(keepends=True): buffer += line if sqlite3.complete_statement(buffer): statements.append(buffer.strip()) buffer = "" if buffer.strip(): statements.append(buffer.strip()) return statements def migrate(conn: sqlite3.Connection) -> list[int]: """Bring an existing database up to `LATEST`. Returns what it applied.""" current = user_version(conn) if current > LATEST: raise RuntimeError( f"this database is at schema v{current}, but this roledesk only knows " f"up to v{LATEST}. Upgrade roledesk rather than let older code write to it.") applied = [] for version, description, step in MIGRATIONS: if version <= current: continue log.info("migrating database to v%d: %s", version, description) _apply(conn, version, step) applied.append(version) return applied def _apply(conn: sqlite3.Connection, version: int, step: Step) -> None: """One migration and its version stamp, in one explicit transaction. Explicit because sqlite3 only opens a transaction implicitly before DML: an `ALTER` would otherwise be durable at once while the stamp stayed behind, and the next open would replay it into a "duplicate column" forever. """ started = not conn.in_transaction if started: conn.execute("BEGIN") try: if callable(step): step(conn) else: for statement in _statements(step): conn.execute(statement) _stamp(conn, version) except Exception: if started: conn.execute("ROLLBACK") raise if started: conn.execute("COMMIT") def initialise(conn: sqlite3.Connection) -> list[int]: """Create or upgrade, whichever this file needs. Returns migrations applied.""" fresh = conn.execute( "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (MARKER,) ).fetchone() is None applied: list[int] = [] if fresh: # Atomic like a migration: a file half created would otherwise carry # the marker table and be taken for one to migrate. _apply(conn, LATEST, SCHEMA) else: applied = migrate(conn) for statement in _statements(INDEXES): conn.execute(statement) return applied