pillarz 0.1.0.dev1__py3-none-any.whl

pillarz/_db/clock.py

@@ -0,0 +1,67 @@
+"""Zentrale Uhr für alle Zeitstempel von pillarz (`pillarz.db.now()` & Co.).
+
+Tests frieren sie über `pillarz.testing.clock.freeze(at)` ein (Ablauf von Sitzungen, Tokens,
+Aufbewahrung des Protokolls), statt `datetime` zu patchen. Im Betrieb liefert sie einfach die
+aktuelle UTC-Zeit. Der eingefrorene Zustand gilt je Prozess (nicht für Unterprozesse).
+"""
+import threading
+from contextlib import contextmanager
+from datetime import datetime, timedelta, timezone
+
+
+def _utc(at: datetime | str) -> datetime:
+    if isinstance(at, str):
+        at = datetime.fromisoformat(at)
+    if not isinstance(at, datetime):
+        raise TypeError("Zeitpunkt muss datetime oder ISO-Text sein")
+    if at.tzinfo is None:            # naive Angaben gelten als UTC
+        return at.replace(tzinfo=timezone.utc)
+    return at.astimezone(timezone.utc)
+
+
+class Clock:
+    def __init__(self):
+        self._frozen: datetime | None = None
+        self._lock = threading.Lock()
+
+    def now(self) -> datetime:
+        """Aktuelle Zeit (UTC, mit Zeitzone) – oder der eingefrorene Zeitpunkt."""
+        frozen = self._frozen
+        return frozen if frozen is not None else datetime.now(timezone.utc)
+
+    @property
+    def frozen(self) -> bool:
+        return self._frozen is not None
+
+    def set(self, at: datetime | str) -> None:
+        """Uhr auf einen festen Zeitpunkt stellen (bis `unfreeze()`)."""
+        with self._lock:
+            self._frozen = _utc(at)
+
+    def advance(self, delta: timedelta | None = None, **kwargs) -> datetime:
+        """Eingefrorene Uhr vorstellen, z. B. `advance(minutes=16)`. Ohne Einfrieren: Fehler."""
+        delta = delta if delta is not None else timedelta(**kwargs)
+        with self._lock:
+            if self._frozen is None:
+                raise RuntimeError("Die Uhr ist nicht eingefroren – erst freeze() aufrufen.")
+            self._frozen = self._frozen + delta
+            return self._frozen
+
+    def unfreeze(self) -> None:
+        with self._lock:
+            self._frozen = None
+
+    @contextmanager
+    def freeze(self, at: datetime | str | None = None):
+        """Zeit für die Dauer des Blocks festhalten (Standard: jetzt). Liefert die Uhr selbst,
+        damit der Block mit `advance()` weiterstellen kann."""
+        previous = self._frozen
+        self.set(at if at is not None else datetime.now(timezone.utc))
+        try:
+            yield self
+        finally:
+            with self._lock:
+                self._frozen = previous
+
+
+clock = Clock()

pillarz/_db/connection.py

@@ -0,0 +1,241 @@
+"""Verbindung und Transaktion – SQLite (Standard) oder PostgreSQL (wenn POSTGRES_DB gesetzt ist).
+
+Portiert aus labelz `app/db.py` (`Conn`, `connect`, `_statements`, `reset`, `ping`), angepasst an ADR 0003:
+- Konfiguration kommt aus der einen `Pillarz`-Instanz (`_runtime`), nicht aus Modul-Globals.
+- SQLite: Verbindung im Autocommit-Modus des Treibers, die Transaktion beginnt ausdrücklich mit
+  `BEGIN` (bzw. `BEGIN IMMEDIATE` für den Migrations-Runner). So laufen auch `CREATE`/`ALTER` in der
+  Transaktion und werden bei einem Fehler mit zurückgerollt. `busy_timeout` für mehrere Prozesse auf
+  einer Datei, im Prozess weiterhin global serialisiert (RLock wie labelz).
+- PostgreSQL: Verbindungspool je Prozess (`psycopg_pool`, `PG_POOL_SIZE`, Standard 5, `0` = eine
+  Verbindung je `connect()` wie labelz). Der Pool wird beim ersten `connect()` angelegt und nach einem
+  Fork nie geerbt (PID-Prüfung). Ist eine frisch geholte Verbindung tot (PG-Neustart), wird das erste
+  Statement **einmal** mit einer neuen Verbindung wiederholt – nie mitten in einer Transaktion.
+"""
+import os
+import re
+import sqlite3
+import threading
+from contextlib import contextmanager
+
+import psycopg
+from psycopg.rows import dict_row
+
+from .. import _runtime
+
+# labelz app/db.py: IntegrityError-Tupel – Aufrufer fangen `except IntegrityError:` auf beiden Systemen
+IntegrityError: tuple = (sqlite3.IntegrityError, psycopg.IntegrityError)
+
+_lock = threading.RLock()
+
+# {pk} (Primärschlüssel), {blob} (Binärspalte), {bigint} (64-Bit-Ganzzahl) sind die einzigen Stellen,
+# an denen sich die Systeme im DDL unterscheiden (labelz PK/BLOB)
+_PLACEHOLDERS = {
+    "{pk}": {"sqlite": "INTEGER PRIMARY KEY AUTOINCREMENT",
+             "postgres": "BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY"},
+    "{blob}": {"sqlite": "BLOB", "postgres": "BYTEA"},
+    "{bigint}": {"sqlite": "INTEGER", "postgres": "BIGINT"},
+}
+
+SQLITE_BUSY_MS = 5000
+POOL_MAX_IDLE = 300
+POOL_TIMEOUT = 10
+CONNECT_TIMEOUT = 10
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,62}$")
+
+
+def ident(name: str) -> str:
+    """Bezeichner (Tabelle/Spalte) prüfen, bevor er in SQL eingesetzt wird – Werte gehen immer als
+    Parameter, Bezeichner können das nicht."""
+    if not isinstance(name, str) or not _IDENT.fullmatch(name):
+        raise ValueError(f"Ungültiger SQL-Bezeichner: {name!r}")
+    return name
+
+
+class Conn:
+    """Dünne Hülle: „?“-Platzhalter und dict-Zeilen auf beiden Systemen (labelz `Conn`)."""
+
+    def __init__(self, raw, postgres: bool, renew=None):
+        self.raw, self.postgres = raw, postgres
+        # Nur bis zum ersten Statement gesetzt: tauscht eine tote, frisch geholte Verbindung aus
+        self._renew = renew
+
+    def execute(self, sql: str, args: tuple | list = ()):
+        if self.postgres:
+            # Unser SQL enthält keine wörtlichen ? oder % – Werte gehen nur als Parameter
+            sql = sql.replace("%", "%%").replace("?", "%s")
+        args = tuple(args)
+        if self._renew is not None:
+            renew, self._renew = self._renew, None
+            try:
+                return self.raw.execute(sql, args)
+            except psycopg.OperationalError:
+                if not (self.raw.closed or self.raw.broken):
+                    raise                     # echter Fehler, keine tote Verbindung
+                dead, self.raw = self.raw, None
+                self.raw = renew(dead)        # einmal mit neuer Verbindung, noch nichts ausgeführt
+        return self.raw.execute(sql, args)
+
+    def rows(self, sql: str, args: tuple | list = ()) -> list[dict]:
+        return [dict(r) for r in self.execute(sql, args).fetchall()]
+
+    def row(self, sql: str, args: tuple | list = ()) -> dict | None:
+        r = self.execute(sql, args).fetchone()
+        return dict(r) if r else None
+
+    def scalar(self, sql: str, args: tuple | list = ()):
+        r = self.execute(sql, args).fetchone()
+        return None if r is None else list(dict(r).values())[0]
+
+    def insert(self, table: str, **fields) -> int:
+        """INSERT mit `id`-Spalte; liefert die neue ID (PostgreSQL über `RETURNING id`)."""
+        cols = ", ".join(ident(c) for c in fields)
+        marks = ", ".join("?" for _ in fields)
+        sql = f"INSERT INTO {ident(table)} ({cols}) VALUES ({marks})"
+        if self.postgres:
+            return self.execute(sql + " RETURNING id", tuple(fields.values())).fetchone()["id"]
+        return self.execute(sql, tuple(fields.values())).lastrowid
+
+    def insert_plain(self, table: str, **fields) -> None:
+        """INSERT für Tabellen ohne id-Spalte (zusammengesetzter Schlüssel)."""
+        cols = ", ".join(ident(c) for c in fields)
+        marks = ", ".join("?" for _ in fields)
+        self.execute(f"INSERT INTO {ident(table)} ({cols}) VALUES ({marks})", tuple(fields.values()))
+
+
+# ------------------------------------------------------------------ PostgreSQL-Pool
+_pool = None
+_pool_pid: int | None = None
+_pool_lock = threading.Lock()
+
+
+def _pg_kwargs(cfg) -> dict:
+    return dict(dbname=cfg.postgres_db, user=cfg.postgres_user, password=cfg.postgres_password,
+                host=cfg.postgres_host, port=cfg.postgres_port, connect_timeout=CONNECT_TIMEOUT)
+
+
+def _get_pool(cfg):
+    global _pool, _pool_pid
+    with _pool_lock:
+        if _pool is not None and _pool_pid != os.getpid():
+            # Nach einem Fork: Verbindungen gehören dem Elternprozess – nie anfassen, neu anlegen
+            _pool = None
+        if _pool is None:
+            from psycopg_pool import ConnectionPool
+            _pool = ConnectionPool(kwargs={**_pg_kwargs(cfg), "row_factory": dict_row},
+                                   min_size=1, max_size=cfg.pg_pool_size, max_idle=POOL_MAX_IDLE,
+                                   timeout=POOL_TIMEOUT, name=f"pillarz-{cfg.name}", open=True)
+            _pool_pid = os.getpid()
+        return _pool
+
+
+def close_pool() -> None:
+    """Pool schließen (Lifespan-Ende, Worker-Befehl, Tests). Der nächste `connect()` legt neu an."""
+    global _pool, _pool_pid
+    with _pool_lock:
+        pool, _pool = _pool, None
+        mine = _pool_pid == os.getpid()
+        _pool_pid = None
+    if pool is not None and mine:
+        pool.close()
+
+
+def pool_stats() -> dict | None:
+    """Kennzahlen des Pools (für Tests/Diagnose), `None` ohne Pool."""
+    pool = _pool
+    return pool.get_stats() if pool is not None and _pool_pid == os.getpid() else None
+
+
+@contextmanager
+def _pg_transaction(cfg):
+    if cfg.pg_pool_size <= 0:
+        # Rückfall wie labelz: eine kurze eigene Verbindung je Aufruf
+        raw = psycopg.connect(**_pg_kwargs(cfg), row_factory=dict_row)
+        try:
+            yield Conn(raw, True)
+            raw.commit()
+        except BaseException:
+            raw.rollback()
+            raise
+        finally:
+            raw.close()
+        return
+
+    pool = _get_pool(cfg)
+
+    def renew(dead):
+        # Die tote Verbindung ist zurückgegeben, bevor getconn() es erneut versucht: schlägt das fehl
+        # (PoolTimeout), ist conn.raw None und der finally-Block gibt nichts doppelt zurück (C-M1)
+        pool.putconn(dead)     # der Pool verwirft geschlossene/kaputte Verbindungen
+        pool.check()           # übrige Ruheverbindungen prüfen (nach PG-Neustart alle tot)
+        return pool.getconn()
+
+    conn = Conn(pool.getconn(), True, renew=renew)
+    try:
+        yield conn
+        conn.raw.commit()
+    except BaseException:
+        if conn.raw is not None:
+            try:
+                conn.raw.rollback()
+            except psycopg.Error:
+                pass           # tote Verbindung: der Pool verwirft sie beim Zurückgeben
+        raise
+    finally:
+        # Zurück nur im Ruhezustand – der Pool rollt Offenes zurück bzw. verwirft Kaputtes
+        if conn.raw is not None:
+            pool.putconn(conn.raw)
+
+
+# ------------------------------------------------------------------ SQLite
+def sqlite_raw(path, *, busy_ms: int = SQLITE_BUSY_MS, foreign_keys: bool = True, uri: bool = False) -> sqlite3.Connection:
+    raw = sqlite3.connect(path, isolation_level=None, timeout=busy_ms / 1000, uri=uri)
+    raw.row_factory = sqlite3.Row
+    raw.execute(f"PRAGMA busy_timeout = {int(busy_ms)}")
+    # vor BEGIN – in einer Transaktion wirkungslos; OFF nur für Tabellenumbauten in Migrationen (ADR 0003)
+    raw.execute("PRAGMA foreign_keys = ON" if foreign_keys else "PRAGMA foreign_keys = OFF")
+    return raw
+
+
+@contextmanager
+def _sqlite_transaction(cfg, *, immediate: bool, busy_ms: int, foreign_keys: bool = True):
+    with _lock:
+        raw = sqlite_raw(cfg.db_path, busy_ms=busy_ms, foreign_keys=foreign_keys)
+        try:
+            raw.execute("BEGIN IMMEDIATE" if immediate else "BEGIN")
+            yield Conn(raw, False)
+            raw.execute("COMMIT")
+        except BaseException:
+            if raw.in_transaction:
+                raw.execute("ROLLBACK")
+            raise
+        finally:
+            raw.close()
+
+
+@contextmanager
+def transaction(*, immediate: bool = False, busy_ms: int = SQLITE_BUSY_MS, foreign_keys: bool = True):
+    """Eine Transaktion: Commit am Ende, Rollback bei Fehler. `immediate` (nur SQLite) nimmt die
+    Schreibsperre der Datei sofort – für den Migrations-Runner; `foreign_keys=False` (nur SQLite)
+    schaltet die Fremdschlüssel für Tabellenumbauten ab (Migrationsschritte mit `requires_fk_off`)."""
+    cfg = _runtime.config()
+    if cfg.postgres:
+        with _pg_transaction(cfg) as conn:
+            yield conn
+    else:
+        with _sqlite_transaction(cfg, immediate=immediate, busy_ms=busy_ms, foreign_keys=foreign_keys) as conn:
+            yield conn
+
+
+def is_postgres() -> bool:
+    return _runtime.config().postgres
+
+
+def statements(sql: str, postgres: bool | None = None) -> list[str]:
+    """DDL mit Platzhaltern in einzelne Statements für das jeweilige System (labelz `_statements`).
+    `--`-Kommentare werden entfernt, getrennt wird an `;` – also keine `;` oder `--` in Literalen."""
+    system = "postgres" if (is_postgres() if postgres is None else postgres) else "sqlite"
+    for key, values in _PLACEHOLDERS.items():
+        sql = sql.replace(key, values[system])
+    lines = [line.split("--", 1)[0] for line in sql.splitlines()]
+    return [s.strip() for s in "\n".join(lines).split(";") if s.strip()]

pillarz/_db/m0001_initial.py

@@ -0,0 +1,194 @@
+"""pillarz-Migration 0001: Konten (`users`) und die privaten `pz_*`-Tabellen von 0.1.
+
+`users` übernimmt Spalten- und Indexnamen von labelz (`app/db.py`, Tabelle `users`), damit eine
+bestehende labelz-Tabelle passt (ADR 0003 „Übernahme bestehender Datenbanken“): Ist die Tabelle schon
+da, ergänzt der Schritt fehlende pillarz-Spalten per `add_column` – generisch, nicht
+labelz-spezifisch. Datenumbau (z. B. `is_admin` → `role`) schreibt das App-Team als eigene
+App-Migration (Architektur §5.4).
+
+Alle `pz_*`-Tabellen mit `user_id` löschen per `ON DELETE CASCADE` mit (Konto löschen in einer
+Transaktion, ADR 0006). Spalten der `pz_*`-Tabellen sind privat und dürfen sich additiv ändern.
+"""
+from ..db import add_column, create_index, ddl, has_column, has_table, now
+from ..i18n import _
+from .connection import Conn
+
+USERS = """
+CREATE TABLE IF NOT EXISTS users (
+    id               {pk},
+    username         TEXT NOT NULL,              -- eindeutig ohne Groß-/Kleinschreibung (Index unten)
+    name             TEXT NOT NULL,
+    email            TEXT UNIQUE,                -- klein geschrieben; gehört pillarz, nicht authentik (F-4)
+    email_confirmed  INTEGER NOT NULL DEFAULT 0, -- 1 = vom Admin/aus authentik/per Mail bestätigt (ADR 0008 §5)
+    password_hash    TEXT,                       -- NULL = kein Passwort
+    role             TEXT NOT NULL DEFAULT 'user',  -- admin | user | guest
+    active           INTEGER NOT NULL DEFAULT 1,
+    session_epoch    INTEGER NOT NULL DEFAULT 0, -- +1 bei „alle Sitzungen beenden“
+    oidc_sub         TEXT,
+    oidc_name        TEXT,
+    oidc_email       TEXT,
+    oidc_unlinked_at TEXT,
+    theme            TEXT,                       -- NULL = Standard-Theme aus den Einstellungen
+    mode             TEXT NOT NULL DEFAULT 'auto',  -- auto | light | dark
+    locale           TEXT,                       -- NULL = Standard
+    region           TEXT,
+    seen_version     TEXT,
+    created_at       TEXT NOT NULL,
+    updated_at       TEXT,
+    last_login       TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS users_username ON users (lower(username));
+CREATE UNIQUE INDEX IF NOT EXISTS users_oidc_sub ON users (oidc_sub) WHERE oidc_sub IS NOT NULL;
+"""
+
+# Spalten, die einer übernommenen Tabelle fehlen dürfen (Typ wie oben, auf beiden Systemen gültig)
+_ADOPTABLE = {
+    "email_confirmed": "INTEGER NOT NULL DEFAULT 0",
+    "password_hash": "TEXT",
+    "role": "TEXT NOT NULL DEFAULT 'user'",
+    "active": "INTEGER NOT NULL DEFAULT 1",
+    "session_epoch": "INTEGER NOT NULL DEFAULT 0",
+    "oidc_sub": "TEXT",
+    "oidc_name": "TEXT",
+    "oidc_email": "TEXT",
+    "oidc_unlinked_at": "TEXT",
+    "theme": "TEXT",
+    "mode": "TEXT NOT NULL DEFAULT 'auto'",
+    "locale": "TEXT",
+    "region": "TEXT",
+    "seen_version": "TEXT",
+    "updated_at": "TEXT",
+    "last_login": "TEXT",
+}
+# Ohne diese Spalten ist es keine Kontentabelle, die pillarz übernehmen kann
+_REQUIRED = ("id", "username", "name", "created_at")
+
+PZ_TABLES = """
+-- Serverseitige Sitzungen (ADR 0005). id = SHA-256 (hex) des Cookie-Tokens, nie das Token selbst.
+CREATE TABLE IF NOT EXISTS pz_sessions (
+    id             TEXT PRIMARY KEY,
+    user_id        BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    method         TEXT NOT NULL,                -- password | oidc | magic_link | passkey | invitation
+    created_at     TEXT NOT NULL,
+    last_seen_at   TEXT NOT NULL,
+    expires_at     TEXT NOT NULL,                -- absolut (SESSION_DAYS)
+    ip             TEXT,
+    user_agent     TEXT,
+    device_label   TEXT,
+    elevated_until TEXT,                         -- Admin über authentik-Gruppe, befristet
+    reauth_at      TEXT,                         -- letzte frische Anmeldung (Schritt-hoch)
+    oidc_sid       TEXT,
+    oidc_id_token  TEXT,                         -- für RP-initiated Logout (ADR 0008)
+    data           TEXT NOT NULL DEFAULT '{}'    -- JSON: Flash, kleine Merker
+);
+CREATE INDEX IF NOT EXISTS pz_sessions_user ON pz_sessions (user_id, last_seen_at);
+CREATE INDEX IF NOT EXISTS pz_sessions_expires ON pz_sessions (expires_at);
+
+-- Vorab-Zustand einer Anmeldung (OIDC state/nonce/PKCE, Verknüpfung, Challenges, MFA-Schritt);
+-- einmalig, kurzlebig (ADR 0005). id = SHA-256 des Flow-Tokens.
+CREATE TABLE IF NOT EXISTS pz_flows (
+    id          TEXT PRIMARY KEY,
+    kind        TEXT NOT NULL,
+    data        TEXT NOT NULL DEFAULT '{}',
+    created_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS pz_flows_expires ON pz_flows (expires_at);
+
+-- Anmeldebremse: eine Zeile je Fehlversuch (ADR 0005)
+CREATE TABLE IF NOT EXISTS pz_throttle (
+    key  TEXT NOT NULL,
+    ts   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS pz_throttle_key ON pz_throttle (key, ts);
+CREATE INDEX IF NOT EXISTS pz_throttle_ts ON pz_throttle (ts);
+
+-- Einmal-Tokens (ADR 0007): nur der SHA-256-Hash steht in der Datenbank. user_id NULL bei Einladungen.
+CREATE TABLE IF NOT EXISTS pz_tokens (
+    id          {pk},
+    kind        TEXT NOT NULL,                   -- oidc_link | magic_link | invitation | password_reset | email_change
+    user_id     BIGINT REFERENCES users(id) ON DELETE CASCADE,
+    token_hash  TEXT NOT NULL UNIQUE,
+    data        TEXT NOT NULL DEFAULT '{}',      -- JSON, z. B. expected_username
+    created_by  BIGINT REFERENCES users(id) ON DELETE SET NULL,
+    created_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL,
+    used_at     TEXT,
+    revoked_at  TEXT
+);
+-- höchstens ein offener Token je Konto und Art; ein neuer zieht den alten zurück (labelz F-19)
+CREATE UNIQUE INDEX IF NOT EXISTS pz_tokens_open ON pz_tokens (user_id, kind)
+    WHERE user_id IS NOT NULL AND used_at IS NULL AND revoked_at IS NULL;
+CREATE INDEX IF NOT EXISTS pz_tokens_user ON pz_tokens (user_id, created_at);
+CREATE INDEX IF NOT EXISTS pz_tokens_kind ON pz_tokens (kind, expires_at);
+
+-- Einstellungen: Schlüssel → JSON (pillarz + registrierte App-Einstellungen, Architektur §14.11)
+CREATE TABLE IF NOT EXISTS pz_settings (
+    key         TEXT PRIMARY KEY,
+    value       TEXT NOT NULL,
+    updated_at  TEXT
+);
+
+-- Eigene Themes (labelz Tabelle themes)
+CREATE TABLE IF NOT EXISTS pz_themes (
+    id      TEXT PRIMARY KEY,
+    name    TEXT NOT NULL,
+    colors  TEXT NOT NULL                        -- JSON: {light: {...}, dark: {...}}
+);
+
+-- Protokoll (labelz Tabelle events) + request_id, actor_id, ip (K-13). actor_id ohne FK, damit der
+-- Eintrag ein Löschen des Kontos überlebt.
+CREATE TABLE IF NOT EXISTS pz_log (
+    id          {pk},
+    ts          TEXT NOT NULL,
+    level       TEXT NOT NULL,
+    source      TEXT NOT NULL,
+    message     TEXT NOT NULL,
+    request_id  TEXT,
+    actor_id    BIGINT,
+    ip          TEXT
+);
+CREATE INDEX IF NOT EXISTS pz_log_ts ON pz_log (ts);
+CREATE INDEX IF NOT EXISTS pz_log_source ON pz_log (source, ts);
+CREATE INDEX IF NOT EXISTS pz_log_actor ON pz_log (actor_id, ts);
+
+-- Interne Merker (setup_done – ADR 0015, Update-Check-Ergebnis, Start-Hinweise)
+CREATE TABLE IF NOT EXISTS pz_meta (
+    key    TEXT PRIMARY KEY,
+    value  TEXT
+);
+"""
+
+
+def _users(conn: Conn) -> None:
+    existed = has_table(conn, "users")
+    for statement in ddl(USERS, conn.postgres)[:1]:     # nur CREATE TABLE; Indizes nach dem Ergänzen
+        conn.execute(statement)
+    if existed:
+        missing = [c for c in _REQUIRED if not has_column(conn, "users", c)]
+        if missing:
+            raise RuntimeError(_("Die vorhandene Tabelle users passt nicht (es fehlen %(cols)s) – "
+                                 "pillarz kann sie nicht übernehmen.") % {"cols": ", ".join(missing)})
+        if add_column(conn, "users", "email", "TEXT"):
+            create_index(conn, "CREATE UNIQUE INDEX IF NOT EXISTS users_email ON users (email)")
+        added = {col for col, typ in _ADOPTABLE.items() if add_column(conn, "users", col, typ)}
+        if "email_confirmed" in added:
+            # Bestandskonten stammen vom Admin – ihre Adressen gelten als bestätigt (ADR 0008 §5)
+            conn.execute("UPDATE users SET email_confirmed = 1 WHERE email IS NOT NULL")
+    for statement in ddl(USERS, conn.postgres)[1:]:
+        create_index(conn, statement)
+
+
+def initial(conn: Conn) -> None:
+    _users(conn)
+    for statement in ddl(PZ_TABLES, conn.postgres):
+        conn.execute(statement)
+    # Übernommene Datenbank mit Konten: die Einrichtungsseite bleibt zu (ADR 0015 §5)
+    if conn.scalar("SELECT COUNT(*) FROM users"):
+        conn.execute("INSERT INTO pz_meta (key, value) VALUES ('setup_done', ?) ON CONFLICT (key) DO NOTHING",
+                     (now(),))
+
+
+STEPS = (
+    ("0001_initial", initial),
+)