Migrations-Index

Alle Schema-Migrationen liegen als einfache SQL-Dateien in server/migrations/. sqlx wendet sie beim Serverstart in aufsteigender numerischer Versionsreihenfolge an – das ganzzahlige Präfix jedes Dateinamens dient als Migrationsversion. Sobald die Prüfsumme einer Migration gespeichert ist, wird sie nie erneut angewendet.

Dateinamensgebung

NNN_beschreibung.sql

NNN ist eine nullaufgefüllte Dezimalzahl. sqlx liest dieses Präfix als i64-Version und wendet die Migrationen in aufsteigender Reihenfolge dieses Ganzzahlwerts an. Die Null-Auffüllung sorgt nur dafür, dass die Dateien auch auf der Festplatte in derselben Reihenfolge stehen; maßgeblich ist die geparste Ganzzahl, nicht die Zeichenkette.

Die Shared-Namespace-Regel

Migrationsnummern bilden einen gemeinsamen Namespace über alle parallelen Worktrees und Branches hinweg. Fügen zwei PRs jeweils eine Migration 170 hinzu, kollidieren sie beim Merge.

Die höchste sequenzielle Migration auf main ist 226 (Stand 2026-06-15). Eine neue Migration geht zu 227 oder höher.

Wie du eine Migration hinzufügst, beschreibt die Anleitung Datenbankmigrationen hinzufügen.

Die Sequenz lesen

Die Sequenz ist weitgehend lückenlos, kennt aber einige dokumentierte Lücken und zwei Nummerierungsmuster, die du kennen solltest.

Lücken

Einige Nummernbereiche sind reserviert oder absichtlich freigelassen:

Lücke	Grund
76–80	Reserviert/unbenutzt
121, 128–129	Unbenutzte Slots zwischen parallelen Feature-Branches
137–139	Reserviert während der Org-Tenancy-Arbeit
161–163	Reserviert während der Credential-Scope-Konsolidierung

sqlx verfolgt Migrationen anhand des Dateinamens; Lücken sind daher unbedenklich, denn eine lückenlose Sequenz wird nicht vorausgesetzt.

Außersequenzielle Dateien

Zwei Migrationen tragen hinter ihrem numerischen Präfix ein zusätzliches Issue-Nummern-Wort statt einer schlichten Feature-Beschreibung:

Datei	Zweck
`100_issue_207_runs_filter_indexes.sql`	Covering-Indexes für Runs-Filter-Abfragen (Issue #207)
`118_issue224_audit_indexes.sql`	Covering-Indexes für Audit-Abfragen (Issue #224)

Trotz der längeren Namen werden diese Dateien an ihrer normalen numerischen Position einsortiert und angewendet – 100 direkt nach 099 und 118 zwischen 117 und 119. Sie laufen also nicht zuletzt; das zusätzliche Wort ist lediglich eine Namenskonvention, die die ursprüngliche Issue-Nummer zur besseren Nachvollziehbarkeit festhält.

Wichtige Migrations-Meilensteine

Die folgende Tabelle ordnet die wichtigsten Schema-Epochen ihren Migrationsnummern zu. Die genauen SQL-Anweisungen findest du in server/migrations/.

Bereich	Feature-Bereich
001–044	Kern-Schema, Auth, OAuth, Scheduling
045–075	Workflows, Runs, Ressourcen, Apps, Billing
076–119	Marketplace-Katalog, Runner, MCP, Telegram, Agent-Profile
120–134	Auth-Überarbeitung (E-Mail-Verifizierung, Magic Link, BYO-OIDC, TOTP), Chat-Plattform-Accounts, Repo-Sync-Auto-Push
140–153	Organisation Tenancy — Orgs, Seats, Einladungen, Benachrichtigungen, BYO-OIDC-Org-Re-Key
154–160	Marketplace-Connector-Nodes, typbezogene Gebühren, Credential-Org-Scope, Item-Bewertungen/Ratings, Connector-Runner-Dispatch
164–165	Credential-Scope-Konsolidierung (gesperrter + Org-RLS, Tracker-OAuth-Client pro Org)
166–169	Auto-Developer-Backlog-Schema, Agent-Profile-Ausführungsmodus, Tenant-Umbenennung `teams` → `workspaces` (ADR 0040)
170–173	Repo-Sync-Ressourcen-Kind/Sync-Modus, App-Deployment-Subdomain + API-Token (ADR 0041 / Issue #410)
174–187	Marketplace-Ledger-Eindeutigkeit, Credential-Scope-Härtung, Budget-Reservierungen, MCP-Cap-Reservierungen, FinTS/Seafile-Ressourcen-Kinds
188–207	Archivierungsflags, Ressource-Letzter-Test, Performance-Indexes (Audit-Events, Tasks, Runs, Sessions), Task-Outcome-Tokens
208–220	Autonomous Delivery Engine (ADR 0045) — Fundament, Spend-Ledger, Backlog/Ruhezeiten/Automatisierungen, Provider-Quota, Routing-Learning, Task-Tool-Freigaben, Autonomie-Regler, Workstreams Sicherheit/Sitz-Überschreitung/Operability/Governor, Runs-Event-Sequenz-Zähler
221–226	v0.2.2 — Engine-Digest-Konfiguration, Automatisierungs-Workflow-ID pro Arm, Workspace-System-LLM-Credential-Pin, Cutover des Legacy-Auto-Developers, Repo-Sync-Memory-Kind, Backlog-Item-Umfang

Tooling

sqlx führt Migrationen beim Serverstart automatisch aus. Im normalen Entwicklungsablauf gibt es keinen separaten Migrations-CLI-Aufruf: Starte den Server gegen eine leere Datenbank, und alle ausstehenden Migrationen werden angewendet.

Für Test-Datenbanken klont das Test-Harness ein vorab migriertes Template (supacloud_test_template), sodass einzelne Testläufe nicht die vollständige Migrations-Kette erneut durchlaufen müssen. Die Test-Support-Helfer findest du in server/tests/.