Dieses Kapitel ist der verbindliche Betriebsvertrag für Neuinstallationen, Release-Updates und Datenbankänderungen. Maßgeblich ist immer die lokale Installation. Das Release-Verzeichnis ist eine daraus erzeugte, geprüfte Veröffentlichung und keine zweite Entwicklungsquelle.

Grundsatz: Die DD entscheidet, nicht die Datenbankart

Jede DD besitzt in $table['server'] einen ausgelieferten Standardserver. Eine Installation darf diesen Standard für jede einzelne DD lokal überschreiben. Dadurch sind in derselben Installation gleichzeitig möglich:

DDs in verschiedenen .db3-Dateien;
mehrere DDs in derselben .db3-Datei;
einzelne DDs auf MySQL/MariaDB;
weitere DDs weiterhin auf SQLite;
DDs verschiedener Module auf unterschiedlichen SQL-Servern.

Fachmodule merken davon nichts. Sie verwenden weiterhin ausschließlich eine DD-Referenz und dbxDB:

$db = dbx()->get_system_obj('dbxDB');
$users = $db->select('dbx|dbxUser', array('trash' => 0));
$orders = $db->select('dbxShop|shopOrder', array('trash' => 0));

Direkter PDO-, SQLite- oder MySQL-Code im Modul, Installer oder in einer Migration ist nicht zulässig.

Auflösung einer Serverbindung

Die lokale Konfiguration liegt ausschließlich in:

dbx/modules/dbx/cfg/config.local.php

config.php enthält nur den ausgelieferten Standard:

$config['dd_server_bindings'] = array();

$config

if($resolved !==$expectedBase . 'files/test/') $config

Definition dbxApi_paths_test.php:35

Eine lokale gemischte Installation kann beispielsweise so gebunden sein:

$config['dd_server_bindings'] = array(
    'dbx|dbxUser' => 'dbxInstall',
    'dbx|dbxUser_groups' => 'dbx|dbxUser.db3',
    'dbxShop|shopOrder' => 'dbxInstall',
    'dbxShop|shopProduct' => 'dbxShop|dbxShop.db3',
);

dbxInstall ist dabei der Name eines aktiven Eintrags in $config['db']. Ein Wert wie dbxShop|dbxShop.db3 ist ein DD-/DB3-Serverziel.

Die Auflösung ist eindeutig:

exakte lokale Bindung modul|dd;
kompatible ältere Bindung nur über den nackten DD-Namen;
andernfalls $table['server'] aus der DD.

Eine vorhandene, aber ungültige lokale Bindung fällt bewusst nicht auf den DD-Standard zurück. Sie wird als Konfigurationsfehler abgelehnt. So kann ein Tippfehler niemals unbemerkt auf die falsche Datenbank schreiben.

Der aktuelle Zustand kann ohne Datenmutation geprüft werden:

$info = $db->get_dd_server_binding_info('dbxShop|shopOrder');

Die Rückgabe nennt deklarierten und aufgelösten Server, Quelle und Gültigkeit.

Administration

Unter System → DD-Serverbindungen listet dbxAdmin alle gefundenen DDs. Jede DD kann unabhängig auf:

ihren ausgelieferten DD-Standard;
einen aktiven konfigurierten SQL-Server;
ihr bisheriges explizites DB3-Ziel

gesetzt werden. Gespeichert werden nur Abweichungen. Passwörter und andere lokale Datenbankwerte werden dabei nicht neu geschrieben.

Eine Zieländerung verschiebt keine Daten. Erst ein ausdrücklicher Transfer-/Migrationsprozess darf Tabellen und Datensätze auf ein anderes Ziel übertragen.

Neuinstallation

Eine vollständige Installationsausgabe kann über dbxapp.de bereitgestellt werden. Produktive .db3-Dateien aus der Entwicklungsinstallation gehören nicht in ein öffentliches Quell- oder Updatepaket.

Der Installer arbeitet in dieser Reihenfolge:

Zielmodell wählen: ausgelieferte DB3-Standards, alles auf einen konfigurierten MySQL-Server oder bereits konfigurierte Einzelbindungen.
Alle DDs ermitteln und deren Schema über dbxDD anlegen beziehungsweise sicher ergänzen.
Core-Gruppen idempotent anlegen.
Den ersten Administrator nur dann anlegen, wenn er noch nicht existiert.

Der Installer überschreibt weder bestehende Administratoren noch vorhandene Gruppen. Das Administratorpasswort wird mit password_hash() gespeichert. Wiederholtes Ausführen erzeugt keine doppelten Seed-Datensätze.

Datenbankmigration eines Moduls

Eine Release-Migration liegt unter:

dbx/modules/{modul}/migrations/*.migration.php

Minimales Beispiel:

<?php
 
return array(
    'id' => 'my-module-4.1.0-order-index',
    'version' => '4.1.0',
    'description' => 'Bestellstruktur auf den neuen DD-Stand bringen.',
    'affected_dd' => array(
        'dbxShop|shopOrder',
        'dbxShop|shopOrderItem',
    ),
    'operations' => array(
        array('type' => 'sync_dd', 'dd' => 'dbxShop|shopOrder'),
        array('type' => 'sync_dd', 'dd' => 'dbxShop|shopOrderItem'),
    ),
);

Verbindliche Regeln:

Die ID ist dauerhaft eindeutig und wird nach Veröffentlichung nie geändert.
Die Versionsnummer ist die erste Release-Version, welche die Änderung benötigt.
Jede möglicherweise veränderte DD steht in affected_dd.
Schemaänderungen stammen aus der neuen DD und laufen als sync_dd.
Fachliche Datenänderungen verwenden ausschließlich das an up übergebene dbxDB-/dbxDD-Objekt.
Eine Migration wird niemals durch direkte SQL-Dateien oder PDO ergänzt.
Bereits ausgeführte Migrationen dürfen nicht nachträglich verändert werden; der SHA-256-Abgleich würde das Update absichtlich stoppen.

sync_dd verwendet standardmäßig den sicheren Modus apply: fehlende Felder und Indizes werden ergänzt, ein notwendiger Tabellen-Rebuild stoppt dagegen mit einer Fehlermeldung. Nur wenn der Release-Autor den bereits gesicherten Rebuild bewusst geprüft hat, wird er explizit angefordert:

array(
    'type' => 'sync_dd',
    'dd' => 'myModule|myRecord',
    'mode' => 'rebuild',
),

Ein optionales up erhält die systemweiten Fassaden:

'up' => static function (object $db, object $dd): void {
    $db->update(
        'myModule|myRecord',
        array('status' => 'active'),
        array('status' => '')
    );
},

Für wiederkehrende Seeds ist ein idempotenter Installationsservice zu verwenden. Migrationen dürfen keine lokalen Servernamen voraussetzen.

Update-Ablauf

Release prüfen
  -> Manifest, Version, PHP, SHA-256 und ZIP-Pfade prüfen
  -> Paket in einen abgeschotteten Stagingbereich entpacken
  -> Benutzer kann das vorbereitete Update stoppen
  -> betroffene Dateien und jede betroffene DD-Tabelle sichern
  -> neue Dateien installieren
  -> ausstehende DD-Migrationen auf ihren lokal gebundenen Servern anwenden
  -> neue VERSION bestätigen
  -> Erfolg protokollieren

Bis zum Start der Installation kann der Benutzer das vorbereitete Update vollständig stoppen. Der danach gestartete kritische DB-/Dateischritt ist bewusst nicht teilunterbrechbar. Ein Fehler löst automatisch den gemeinsamen Rollback von Datenbanktabellen und Dateien aus.

Vor einer Migration wird jede betroffene DD erneut aufgelöst. Die Sicherung wird nach dem tatsächlich verwendeten Server gruppiert. Damit bleibt ein Update korrekt, wenn beispielsweise Benutzer und Bestellungen auf MySQL, Content und Sessions aber in verschiedenen DB3-Dateien liegen.

Schutz gegen unbeabsichtigte Serverwechsel

Ändert ein Release den in einer DD ausgelieferten $table['server'], darf das Update eine bestehende Installation nicht stillschweigend auf das neue Ziel umlenken. Ohne explizite lokale Bindung wird der Updatevorgang abgelehnt.

Der Betreiber entscheidet dann bewusst:

bisheriges Ziel als lokale DD-Bindung festschreiben; oder
Daten mit dem vorgesehenen Transferprozess auf das neue Ziel übertragen und erst danach die Bindung ändern.

Das gilt auch für DB3-zu-MySQL- und MySQL-zu-DB3-Wechsel.

Migrations-Ledger und Rollback

Ausgeführte Migrationen werden in dbxAdmin|dbxMigration mit ID, Version, Modul, Checksum, Status, betroffenen Servern und Sicherungsreferenz protokolliert.

Vor dem ersten Schreibschritt werden Schema, Indizes und Daten jeder betroffenen existierenden Tabelle gesichert. Beim Rollback werden:

neu angelegte Tabellen entfernt;
frühere Tabellenstrukturen und Indizes wiederhergestellt;
gesicherte Daten zurückgespielt;
der Migrationsstatus als zurückgerollt markiert;
geänderte Programmdateien aus derselben Updatesicherung wiederhergestellt.

Release-Verantwortung

Die Entwicklung findet in C:\xampp\htdocs\dbxapp statt. Erst ein bewusster Release-Schritt synchronisiert den geprüften Quellstand nach C:\xampp\htdocs\dbxapp-github, erstellt Inventar, ZIP, Prüfsummen und Manifest und veröffentlicht anschließend GitHub.

Installationsdaten und lokale Konfiguration werden nie von GitHub in eine bestehende Installation kopiert. Updates liefern Code, DDs und versionierte Migrationen. Die lokale DD-Serverbindung bleibt die Wahrheit der jeweiligen Installation.

Abnahmematrix

Vor Veröffentlichung eines Releases müssen mindestens bestanden sein:

DD-Auflösung ohne Binding, mit DB3-Binding und mit SQL-Alias;
parallele Auflösung zweier DDs auf unterschiedliche Serverarten;
ungültige Bindung wird abgelehnt;
Neuinstallation und wiederholte Seeds sind idempotent;
Migrationserkennung, Checksum-Ledger und bereits ausgeführte Migration;
Backup und Rollback über mindestens zwei verschieden gebundene Server;
gemeinsamer Datei-/DB-Rollback bei simuliertem Fehler;
Admin-Oberfläche in Deutsch, Englisch und Spanisch;
bestehende dbxDB-, dbxForm-, dbxReport- und Update-Regressionstests.

Installation, Updates und DD-Serverbindungen