# ADR001-WP2-004 – Schema and Migrations **Status:** ~~Accepted~~ Completed **Autor:** ED **Reviewer:** LA **Datum:** 2026-07-20 Verifiziert durch: ✔ Architekturreview (LA) ✔ Regressionstests ✔ OpenRefine-Reconciliation ✔ Manifest-Endpunkt ✔ Migrationstest ✔ Erfolgreicher Erstlauf gegen MariaDB ✔ Erfolgreicher Zweitlauf (Idempotenz) --- # 1. Kontext Mit den bisherigen Workpackages wurde die technische Grundlage für die relationale Persistenz von Reconcilix geschaffen: - WP1 – Domain Integration - WP2-001 – Runtime Architecture - WP2-002 – Composition Root - WP2-003 – Persistence Foundation WP2-003 stellt insbesondere bereit: - zentrale Datenbankkonfiguration, - `DatabaseConnectionFactory`, - PDO-basierte Datenbankverbindung, - `TransactionManager`, - Integration der Persistenzinfrastruktur in den Composition Root. Das fachliche Persistenzmodell ist in **DM002 – Reconcilix Persistence Model** beschrieben. Ein SQL-Entwurf für MySQL 8 und MariaDB 10.4 liegt bereits vor. Bevor relationale Repositorys und Data Mapper implementiert werden, benötigt Reconcilix ein reproduzierbares, versioniertes und überprüfbares Datenbankschema. WP2-004 schafft dafür die Schema- und Migrationsgrundlage. --- # 2. Problemstellung Ein einzelnes, manuell ausgeführtes SQL-Skript reicht für die weitere Entwicklung nicht aus. Reconcilix benötigt eine definierte Vorgehensweise für - die erstmalige Einrichtung einer leeren Datenbank, - die versionierte Weiterentwicklung des Schemas, - die Erkennung bereits ausgeführter Migrationen, - die reproduzierbare Installation in Entwicklung, Test und Produktion, - die Kompatibilität mit MySQL 8 und MariaDB 10.4, - die Prüfung des Schemas vor der Einführung relationaler Repositorys. Dabei darf die Schema-Verwaltung weder in den HTTP-Request-Flow noch in fachliche Application Services gelangen. --- # 3. Entscheidung WP2-004 führt ein explizites, dateibasiertes und vorwärtsgerichtetes Migrationssystem ein. Die Entscheidung umfasst: 1. ein konsolidiertes DM002-Basisschema, 2. fortlaufend nummerierte SQL-Migrationsdateien, 3. eine technische Tabelle zur Protokollierung ausgeführter Migrationen, 4. einen explizit aufrufbaren CLI-Migration-Runner, 5. einen Schema-Bootstrap für eine leere Datenbank, 6. Infrastrukturtests gegen MySQL 8 beziehungsweise MariaDB 10.4. Migrationen werden **nicht automatisch** beim Aufbau des HTTP-Composition-Roots oder beim Aufruf der Reconciliation-API ausgeführt. --- # 4. Ziele WP2-004 verfolgt folgende Ziele: - DM002 als ausführbares relationales Schema bereitstellen, - leere Datenbanken reproduzierbar initialisieren, - Schemaänderungen eindeutig versionieren, - mehrfaches Ausführen bereits angewendeter Migrationen verhindern, - Abweichungen an bereits angewendeten Migrationsdateien erkennen, - MySQL 8 als Referenzplattform unterstützen, - MariaDB 10.4 als Entwicklungsplattform weiterhin unterstützen, - WP2-005 eine stabile relationale Struktur bereitstellen. --- # 5. Schema-Baseline Die erste Migration bildet eine vollständige Baseline des für WP2 benötigten DM002-Schemas. Die Baseline enthält insbesondere die Tabellen: ```text source_value context_item interpretation_graph interpretation_node interpretation_node_property reconciliation_result candidate_item match_decision ``` Optional kann eine rein technische View für Debugging und Evaluation enthalten sein, sofern sie keine fachliche Abhängigkeit für Repositorys erzeugt. Die Baseline wird vor der Implementierung gegen den aktuellen Stand von DM001 und DM002 abgeglichen. Dabei werden mindestens die bereits identifizierten Modellpräzisierungen berücksichtigt: - `candidate_item.rank` entspricht der Domain-Invariante und ist für persistierte Candidate Items verpflichtend, - `reconciliation_result.success` erhält einen technisch eindeutigen Initialwert, bleibt aber bis zur fachlichen Festlegung ohne Steuerungsfunktion, - die Zuordnung von `MatchDecision.selectedCandidateUri` zu `selected_candidate_item_id` wird erst im Data Mapper von WP2-005 umgesetzt, - Tabellen für derzeit noch nicht vollständig integrierte Domain-Anteile wie `context_item` und `interpretation_node_property` dürfen im Schema enthalten bleiben, werden in WP2-004 jedoch nicht fachlich verwendet. WP2-004 verändert keine Domain-Invarianten. --- # 6. Verzeichnis- und Dateistruktur Die Migrationen werden innerhalb des Projekts versioniert abgelegt. Vorgesehene Struktur: ```text database/ ├── migrations/ │ ├── 0001_create_dm002_baseline.sql │ └── ... └── README.md tools/ └── migrate.php ``` Die Dateinamen beginnen mit einer streng monoton steigenden numerischen Versionsnummer. Beispiel: ```text 0001_create_dm002_baseline.sql 0002_add_example_index.sql ``` Eine einmal veröffentlichte und angewendete Migration wird nicht nachträglich verändert. Korrekturen erfolgen durch eine neue Migration. --- # 7. Migration Registry Der Migration-Runner verwaltet eine technische Tabelle, beispielsweise: ```text schema_migration ``` Sie enthält mindestens: - Migrationsversion, - Dateiname oder eindeutige Bezeichnung, - Prüfsumme der Migrationsdatei, - Ausführungszeitpunkt. Ziele der Registry: - bereits angewendete Migrationen erkennen, - erneute Ausführung verhindern, - nachträgliche Änderungen angewendeter Dateien feststellen, - aktuellen Schema-Stand nachvollziehbar machen. Die Migration Registry gehört ausschließlich zur technischen Infrastruktur und ist kein Bestandteil von DM001 oder DM002. --- # 8. Migration Runner Der Migration-Runner wird als explizites CLI-Werkzeug ausgeführt. Beispiel: ```bash php tools/migrate.php ``` Verantwortlichkeiten: - Datenbankkonfiguration über die bestehende `Configuration` laden, - Verbindung über die `DatabaseConnectionFactory` beziehen, - Migration Registry sicherstellen, - Migrationsdateien sortiert ermitteln, - Prüfsummen validieren, - noch nicht angewendete Migrationen ausführen, - erfolgreiche Ausführung registrieren, - Fehler mit einer aussagekräftigen Meldung und einem Fehlercode beenden. Nicht verantwortlich für: - Repository-Aufrufe, - Rehydration, - Domain Objects, - Reconciliation, - fachliche Datenmigrationen außerhalb expliziter SQL-Migrationen. --- # 9. Ausführungsmodell und Transaktionen Migrationen werden sequenziell und exakt in Versionsreihenfolge ausgeführt. Für jede Migration gilt: 1. Prüfen, ob sie bereits registriert ist. 2. Prüfsumme berechnen und gegebenenfalls mit der gespeicherten Prüfsumme vergleichen. 3. SQL ausführen. 4. Migration erst nach erfolgreicher Ausführung registrieren. 5. Bei einem Fehler abbrechen; nachfolgende Migrationen werden nicht ausgeführt. MySQL und MariaDB führen bei verschiedenen DDL-Anweisungen implizite Commits aus. Daher wird keine falsche Garantie vollständig transaktionaler DDL-Migrationen gegeben. Der Runner verwendet Transaktionen nur dort, wo das jeweilige Datenbanksystem und die konkrete Migration dies zuverlässig erlauben. Jede Migration muss deshalb so gestaltet sein, dass ihr Fehlerzustand nachvollziehbar und kontrollierbar bleibt. --- # 10. Vorwärtsstrategie Migrationen sind grundsätzlich **forward-only**. WP2-004 führt keine automatischen Down-Migrationen ein. Begründung: - DDL-Rollbacks sind zwischen MySQL 8 und MariaDB 10.4 nicht einheitlich zuverlässig, - Datenverlust kann durch automatisierte Down-Migrationen nicht generell ausgeschlossen werden, - produktive Rücksetzungen sollen über Backup, Restore und gezielte Korrekturmigrationen erfolgen, - der initiale Scope bleibt klein und überprüfbar. Für Entwicklung und Tests kann eine Datenbank verworfen und aus der Baseline neu aufgebaut werden. --- # 11. Nebenläufigkeit Es darf nicht gleichzeitig mehr als ein Migration-Runner gegen dieselbe Datenbank arbeiten. WP2-004 muss deshalb einen geeigneten technischen Schutz vor paralleler Ausführung vorsehen, beispielsweise über einen datenbankseitigen Lock. Kann der Lock nicht erworben werden, beendet sich der Runner ohne Ausführung weiterer Migrationen. Es werden keine globalen PHP-Singletons eingeführt. --- # 12. Kompatibilität ## Referenzplattform - MySQL 8.x ## Entwicklungsplattform - MariaDB 10.4.x Die Baseline und alle Migrationen müssen auf beiden Plattformen ausführbar sein, solange keine spätere Architekturentscheidung eine abweichende Festlegung trifft. Datenbankspezifische Unterschiede werden explizit dokumentiert und nicht stillschweigend über plattformspezifische SQL-Fragmente verteilt. Für URI-Spalten gelten weiterhin die in DM002 festgelegten Regeln: ```text Reconcilix classification URI: VARCHAR(512) External resource/system URI: VARCHAR(2048) Collation: utf8mb4_bin ``` Tabellen verwenden InnoDB und explizite Fremdschlüssel. --- # 13. Schema-Verantwortung ## DM001 Bleibt das fachliche Referenzmodell. ## DM002 Beschreibt die relationale Persistenzsicht und die fachlich begründeten Tabellenbeziehungen. ## SQL-Migrationen Sind die ausführbare und versionierte technische Repräsentation des Schemas. Die SQL-Migrationen stellen die ausführbare technische Projektion des in DM002 beschriebenen Persistenzmodells dar. Änderungen am fachlichen Persistenzmodell erfolgen zunächst in DM002 und werden anschließend durch Migrationen nachvollzogen. ## Migration Runner Verwaltet ausschließlich die kontrollierte Anwendung dieser SQL-Migrationen. Repositorys und Data Mapper dürfen erst ab WP2-005 auf dieses Schema zugreifen. --- # 14. Einbindung in die bestehende Architektur Der Migration-Runner ist ein eigener technischer Einstiegspunkt: ```text tools/migrate.php │ ▼ Configuration │ ▼ DatabaseConnectionFactory │ ▼ MigrationRunner │ ├── Migration Registry └── SQL Migration Files ``` Der HTTP-Objektgraph bleibt davon getrennt: ```text public/reconcile.php │ ▼ ReconciliationCompositionRoot ``` Der `ReconciliationCompositionRoot` führt keine Migrationen aus und überprüft beim normalen API-Aufruf nicht eigenständig den Schema-Stand. Ein späterer CLI- oder Worker-Composition-Root kann dieselbe Persistence Foundation verwenden, ohne den HTTP-Einstiegspunkt zu verändern. --- # 15. Fehlerbehandlung und Sicherheit Der Migration-Runner - gibt keine Datenbankpasswörter aus, - protokolliert Version und Status einer Migration, - beendet sich bei SQL- oder Prüfsummenfehlern mit einem Fehlercode, - führt nach einem Fehler keine weiteren Migrationen aus, - verändert keine bereits registrierte Migrationshistorie automatisch. Die Datenbankzugangsdaten werden nicht in Migrationsdateien gespeichert. Produktive Migrationen setzen ein vorhandenes Backup beziehungsweise ein betrieblich abgestimmtes Wiederherstellungsverfahren voraus. Das Backup selbst ist nicht Bestandteil von Reconcilix WP2-004. --- # 16. Teststrategie WP2-004 ergänzt Infrastruktur- und Integrationstests für mindestens folgende Fälle: - leere Datenbank wird erfolgreich initialisiert, - Migration Registry wird angelegt, - Baseline wird genau einmal ausgeführt, - erneuter Runner-Aufruf ist idempotent, - Migrationen werden in Versionsreihenfolge ausgeführt, - Prüfsummenabweichung einer bereits angewendeten Migration wird erkannt, - fehlerhafte Migration stoppt die weitere Ausführung, - Schema enthält die erwarteten Tabellen, Fremdschlüssel und zentralen Constraints, - Baseline ist unter MySQL 8 ausführbar, - Baseline ist unter MariaDB 10.4 ausführbar, - der HTTP-Composition-Root löst keine Migration aus, - bestehende Runtime-, Manifest- und Reconciliation-Tests bleiben unverändert erfolgreich. Tests dürfen mit einer eigens dafür vorgesehenen Testdatenbank arbeiten. Produktive Datenbanken dürfen von automatisierten Tests nicht verwendet werden. --- # 17. Nicht Bestandteil dieses Workpackages WP2-004 implementiert ausdrücklich nicht: - relationale Repositorys, - Data Mapper, - Rehydration, - Speicherung oder Laden fachlicher Aggregate, - Übersetzung zwischen Domain-URIs und technischen Fremdschlüsseln, - Transaction Boundary des fachlichen Reconciliation-Ablaufs, - Unit of Work, - Identity Map, - Seed-Daten für fachliche Vokabulare, - automatische Migration beim HTTP-Request, - Deployment-Automatisierung, - Backup- oder Restore-Infrastruktur, - Event Sourcing. Diese Themen bleiben den folgenden Workpackages beziehungsweise dem Betrieb vorbehalten. --- # 18. Auswirkungen Nach Abschluss von WP2-004 verfügt Reconcilix über - ein konsolidiertes DM002-Basisschema, - eine nachvollziehbare Migrationshistorie, - einen reproduzierbaren Datenbank-Bootstrap, - einen expliziten CLI-Migrationsprozess, - eine stabile Schema-Grundlage für relationale Repositorys und Data Mapper. WP2-005 kann anschließend auf einer definierten und getesteten relationalen Struktur aufbauen, ohne Schema-Erzeugung oder Migrationslogik selbst übernehmen zu müssen. --- # 19. Offene Punkte für das LA-Review 1. Ist die Entscheidung für ein dateibasiertes, forward-only Migrationssystem für den aktuellen Projektstand angemessen? 2. Ist die strikte Trennung zwischen CLI-Migration und HTTP-Composition-Root ausreichend klar? 3. Soll die Prüfsumme angewendeter Migrationen bereits in WP2-004 verpflichtend sein? 4. Ist ein datenbankseitiger Lock als Schutz vor parallelen Migrationen bereits im ersten Migrations-Runner erforderlich? 5. Ist die Abgrenzung zwischen DM002 als Persistenzmodell und den SQL-Migrationen als ausführbarer Schema-Repräsentation eindeutig? 6. Soll die DM002-Baseline vor der Implementierung formal als Version 0.3 fortgeschrieben werden? 7. Sind weitere Kompatibilitätsregeln für MySQL 8 und MariaDB 10.4 festzulegen? --- # Review Status **Proposed** Nach erfolgreichem Architekturreview durch LA kann WP2-004 implementiert werden. --- # Review-Ergebnis **Accepted** LA hat die Architekturentscheidung ohne Änderungen angenommen. Die Empfehlung zur technischen Projektion von DM002 wurde ergänzt. WP2-004 kann umgesetzt werden.