Package layers models, config, storage, jobs, web, cli, held by tests/test_architecture.py with desk and pipeline as external trees and plugins/ limited to desk. roles.yaml is the default config, roledesk.db its own file, port 8790. create_app mounts pipeline.web.connect over Jobs(config.database); `roledesk job pull` drains a no-op pull and `roledesk db init` creates the file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
132 lines
4.5 KiB
Python
132 lines
4.5 KiB
Python
"""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
|