Database Gateway

Datenbanken von CMS- und Shopsystemen sicher und temporär per Tool abfragen.

Manchmal brauchst du Daten aus einer fremden Datenbank — der Live-Shop-DB des Kunden, dem Contao- oder WordPress-Backend, einem alten CRM. Direkter SQL-Zugriff von TaskMonkey aus geht nicht (Netzwerk, Firewall, Sicherheit). Lösung: das Database Gateway.

#Config-Referenz (remote_databases)

Nur diese Schlüssel liest der Code (src/Tooling/DatabaseGatewayTools.php, SshKeyResolver, DatabaseConnector). Keine Schlüssel erfinden: writeTenantConfig lehnt unbekannte ab (z. B. web_url → gemeint ist base_url). Datei: database_connections.php, Key darin: remote_databases.

Ältere Schreibweisen, die noch gelesen werden: host (= hostname), user (= remote_user), webRoot (= web_root), key (= ssh_key), passphrase (= key_passphrase). Neu nicht mehr verwenden.

Die Contao-Version nicht beim Kunden erfragen — ensureGateway/deployGateway erkennt System und Version selbst (cms_detected, version).

#Hoster Mittwald

• SSH läuft in einer chroot. Für SSH/SCP ist das Home /, die Seiten liegen unter /html/<ordner>/… — nicht unter /home/pXXXXXX/… oder /home/www/pXXXXXX/… (das sind die Pfade außerhalb der chroot, z. B. in Symlink-Zielen). web_root also z. B. /html/icon-immobilien.de/web.
• Der Ordnername sagt nichts über die Domain. /html/dev-www.kunde.de kann die Live-Seite sein. Welche Domain auf welchen Ordner zeigt, steht im Mittwald-Kundencenter (Domains → Ziel), nicht im Dateisystem.
• base_url immer setzen = die öffentliche Domain, die den web_root ausliefert (z. B. https://www.kunde.de). Ohne base_url baut das Gateway https://pXXXXXX.mittwaldserver.info/… — das liefert 404.
• Contao 4 (bis 4.13 ohne Umstellung): Web-Root …/web. Contao 5 (oder 4.13 mit public): …/public. Deployer-Setups: …/<ordner>/current/public (current ist ein Symlink auf releases/<n>; das Gateway landet im Release-Ordner und ist nach dem nächsten Deploy des Kunden weg — ensureGateway deployt dann neu).
• Pfade selbst prüfen statt den Kunden fragen: sobald SSH steht, ensureGateway mit dem wahrscheinlichsten Pfad aufrufen; der Fehler (SCP … No such file or directory) zeigt, ob der Pfad existiert.

Ausführliches Beispiel: Rezept Contao-Redakteur.

#Konzept

Statt eine permanente DB-Verbindung zu öffnen, deployt das Gateway-Tool ein kleines PHP-Script über SSH auf den Webserver des Ziels. Das Script erkennt das System (Contao, WordPress, Shopware, …), liest die DB-Zugangsdaten aus dessen Konfiguration, nimmt SQL per POST entgegen, prüft es gegen das System-Profil und gibt JSON zurück. Nach Ablauf löscht es sich selbst.

Kein SSH-Zugang, nur FTP oder Hosting-Panel (typisch bei all-inkl, IONOS, Strato, vielen Gambio-/WooCommerce-Shops)? Dann nimmst du den Connector: dieselbe Datei als Dauerversion, einmal hochgeladen, jeder Aufruf signiert. Siehe Dauerbetrieb ohne SSH (Connector).

Vorteile:

• Kein VPN, kein Tunnel, keine direkte DB-Verbindung
• Token-basiert, zeitlich begrenzt (max. 72 h)
• Read-only oder Read/Write konfigurierbar
• Tabellen-Profil je System, im Gateway selbst erzwungen: Inhalte ja, Benutzer/Passwörter/Sessions/Tokens/Zahlungsdaten/Logs/Konfig nie
• Backups und Rollback beim Kunden (ab Protokoll 5): automatisches Backup vor der ersten Änderung einer Sitzung, jede Schreiboperation einzeln zurücknehmbar — die Daten verlassen den Server nie, siehe Backups und Rollback
• MySQL und MariaDB (was das Ziel-PHP per pdo_mysql erreicht, auch über Unix-Socket)

#Voraussetzungen

Du brauchst SSH-Zugang zum Ziel-Webserver mit einem Key, dessen privater Teil hinterlegt ist. Pro Ziel hinterlegst du in config/tenants/<workspace>/database_connections.php eine Connection-Config unter dem Key remote_databases.<projekt>:

Datei vs. Key. Die Datei heißt database_connections.php, der Config-Key darin heißt remote_databases — das ist der einzige Key, den die Tools lesen. Der Dateiname selbst ist kein Key (der Workspace-Loader nimmt die Keys aus dem return-Array). Ein Top-Level-Key database_connections ist veraltet: der Loader faltet ihn beim Laden in remote_databases um; steht dasselbe Projekt unter beiden Keys, gewinnt remote_databases komplett und es gibt eine Log-Warnung. Neue Configs nur mit remote_databases.

Tabellennamen in tables/extra_tables/deny sind volle Namen (mit Präfix, z. B. tl_news, wp_posts), * ist als Wildcard erlaubt (mind. drei feste Zeichen).

<?php
// config/tenants/<workspace>/database_connections.php
return [
    'remote_databases' => [
        'kunde_web' => [
            'hostname'    => 'kunde.de',
            'remote_user' => 'p123456',
            'ssh_key'     => secret('SSH_KUNDE_KEY'),
            'base_url'    => 'https://kunde.de',
            'web_root'    => '~/html/kunde.de/current/public',
            'profile'     => 'contao',
            'allow_write' => true,   // Obergrenze: ohne das nur lesend
            // nur News pflegen:
            'tables'      => ['read' => ['tl_news*', 'tl_content', 'tl_files'], 'write' => ['tl_news', 'tl_content']],
        ],
    ],
];

#Tools

Alle Tools funktionieren für beide Betriebsarten gleich: ensureGateway → executeQuery/executePreparedQuery/uploadFile. Bei Connector-Projekten deployt ensureGateway nichts, sondern pingt und gleicht die Policy ab.

ensureGateway und deployGateway laufen pro Projekt unter einem Lock. Parallele Chats oder Scheduled Tasks, die ensureGateway nutzen, teilen sich damit ein Gateway, statt sich gegenseitig das Script wegzudeployen.

Schreibrecht hat zwei Stufen: allow_write in der Connection-Config (remote_databases.<projekt>.allow_write) ist die Obergrenze, das Tool-Arg allow_write fordert innerhalb dieser Grenze ein Schreib-Gateway an. Fehlt die Obergrenze, lehnen deployGateway/ensureGateway mit allow_write, uploadFile und executePreparedQuery (mode: write) ab — mit einem Nutzertext in error („Schreiben ist noch nicht freigeschaltet — bitte im Builder freischalten.“), error_code: write_not_enabled und dem Technischen in admin_detail (read-only-Kontext: error_code: read_only). Wird die Obergrenze nachträglich entzogen, verweigert executeQuery das laufende Schreib-Gateway und ensureGateway deployt es lesend neu. Im Read-only-Kontext (API-Key ohne external_api_write, Webhook ohne inbound_hook_write) gibt es kein Schreib-Gateway, auch wenn die Verbindung es erlaubt. min_hours_left ist auf 71 h gedeckelt (ein neues Gateway läuft höchstens 72 h).

#System-Profile

Das Gateway erkennt das System anhand typischer Dateien (vom Gateway-Verzeichnis bis zu vier Ebenen aufwärts). Mit profile in der Connection-Config legst du es fest; das ist für Produktivsysteme empfohlen. Unbekannte Systeme bekommen das Profil generic: nur Tabellen aus tables/extra_tables, alles andere ist gesperrt.

Die vollständigen Listen stehen in resources/database_gateway/profiles.php.

Für alle Profile gilt zusätzlich eine generische Denylist (gegen den Namen mit und ohne Präfix): *user*, *admin*, *customer*, *member*, *employee*, *session*, *token*, *password*, *oauth*, *api_key*, *access_key*, *secret*, *credential*, *auth*, *2fa*, *mfa*, *webauthn*, *remember*, *payment*, *vault*, *creditcard*, *address*, *subscriber*, *config*, Log-Tabellen (log, *_log, *_logs, log_*, *logging*), *cron*, *queue*, *messenger*.

Bestellungen stehen bewusst in keiner Allowlist (sie enthalten Kundendaten), sind aber nicht hart gesperrt. Für Reporting per extra_tables freigeben; Adressen, Kundenkonten und Zahlungsdaten bleiben gesperrt.

Gambio: Die Tabelle orders enthält Kunden-, Liefer- und Rechnungsadresse (und alte cc_*-Spalten) direkt in der Zeile, das Gateway kann nicht spaltenweise filtern. Für Reporting reichen meist orders_products, orders_total und orders_status_history; orders selbst nur freigeben, wenn die Adressen wirklich gebraucht werden. Kundengruppen-Preise (personal_offers_by_customers_status_*) fallen unter die generische Sperre *customer*. Neue Produktbilder gehören nach images/product_images/original_images/; Thumbnails/Info-/Popup-Bilder erzeugt Gambio daraus über die Bildverarbeitung im Admin.

Präfix: Profil-Tabellen gelten nur mit dem Präfix des Systems. Eine Tabelle ohne dieses Präfix (z. B. posts statt wp_posts) ist nicht über das Profil erlaubt, nur über extra_tables.

Config-Regeln: tables kann das Profil nur einschränken. extra_tables gibt explizit zusätzliche Tabellen frei, die Denylist gewinnt aber immer. Die Denylist lässt sich nur mit unsafe_allow_denied_tables (exakte Namen, keine Wildcards) aufheben.

#Sicherheitsmodell

Alles Folgende setzt das Gateway-Script selbst durch (serverseitig), nicht der Prompt und nicht TaskMonkey:

Das Gateway ist trotzdem ein Live-Zugriff auf eine fremde Produktiv-DB. Setze es nur ein, wenn du die Verantwortung hast oder explizit autorisiert wurdest, lass allow_write aus, wo es geht, und schränke mit tables auf das ein, was fachlich nötig ist.

Grenzen:

• Die Prüfung ist tabellenbasiert, nicht zeilenbasiert. Beispiel WooCommerce ohne HPOS: Bestellungen liegen als shop_order in wp_posts/wp_postmeta (inkl. Rechnungsadresse). Wer das nicht will, schränkt mit tables ein oder aktiviert HPOS.
• Vorhandene Stored Functions/Views der Ziel-DB werden nicht analysiert.
• Die Denylist greift pro Tabellenname. Eigene Tabellen mit sensiblen Daten und unauffälligem Namen gehören in deny.

#Parametrisierte Queries für Tools und APIs

Sobald Werte von außen kommen (API-Aufruf, Formular, Webhook), gehört das SQL fest ins Tool und die Werte in params:

$ctx['tool']('executePreparedQuery', [
    'project' => 'kunde_shop',
    'sql'     => 'SELECT id, name, price FROM products WHERE sku = ? LIMIT 1',
    'params'  => [$args['sku']],
]);

Über die API-Keys, öffentliche Tools (public_api) und eingehende Webhooks ist executeQuery (freies SQL) grundsätzlich gesperrt und executePreparedQuery läuft nur lesend, solange das aufgerufene Tool nicht 'external_api_write' => true trägt. Vollständiges Beispiel: Rezept: API für eine Bestandsdatenbank.

#Backups und Rollback

Ab Gateway-Protokoll 5 sichert das Gateway (und der Connector) die Daten, die TaskMonkey ändern darf, beim Kunden — kein Dump und kein Datensatz verlässt den Server. TaskMonkey bekommt nur Metadaten zurück: Dateiname, Größe, Tabellen- und Zeilenzahl.

Ablage. tm-backups/<projekt>/ eine Ebene über dem Web-Root (dem Verzeichnis des Gateways, das base_url zeigt), z. B. bei Contao …/kunde.de/current/tm-backups/kunde_web/ neben public/. Mit backup_dir in remote_databases.<projekt> frei wählbar (relativ zum Gateway-Verzeichnis oder absolut). Das Gateway löst den Pfad vor dem Anlegen per realpath auf und lehnt alles ab, was im Gateway-Verzeichnis, im DOCUMENT_ROOT des Webservers, in einem typischen Web-Verzeichnis des Projekts (public/, web/, pub/, htdocs/, html/, …) oder — wenn das Gateway im Projekt, aber in keinem dieser Verzeichnisse liegt (WordPress, Contao ohne public/) — im Projekt-Root selbst liegt, auch über Symlinks. Dann schlagen Backup und Schreiben fehl (fail-closed, kein Journal ohne sichere Ablage), die Meldung verlangt backup_dir. Verzeichnis 0700, Dateien 0600, dazu eine .htaccess mit „deny all“ als zweite Schicht. Dateinamen enthalten Zeitstempel, SHA-256 des Inhalts und einen Zufallsteil (tm_backup_20260925-143012_3f9c…_8a1e….sql.gz.php), sind also nicht ratbar. Dritte Schicht: Backups und Journale enden auf .php und beginnen mit einem PHP-Guard (<?php http_response_code(404); exit; ?> — im Journal als erste Zeile, im Backup im Kommentarfeld des gzip-Headers, die Datei bleibt normales gzip). Liefert ein falsch konfigurierter Webserver das Verzeichnis doch aus, führt er die Datei aus und sie endet sofort. Ältere Dateien (….sql.gz, journal_<datum>.jsonl) werden weiter gelesen, wiederhergestellt und rotiert.

Bei Systemen, deren Web-Root das Projektverzeichnis selbst ist (WordPress, Gambio, JTL, …), liegt das Default-Verzeichnis im Elternordner. Wird der vom Hoster ebenfalls ausgeliefert (z. B. ~/html als Root einer weiteren Domain), backup_dir auf ein sicher nicht ausgeliefertes Verzeichnis setzen, z. B. /home/p123456/tm-backups/kunde_shop.

Umfang. Genau die Tabellen der Schreib-Allowlist des effektiven Profils — inkl. extra_tables.write, nie Denylist-Tabellen (auch nicht, wenn sie per extra_tables genannt sind), keine nur lesbaren Tabellen. Format: SQL (DROP TABLE IF EXISTS + CREATE TABLE + INSERT, utf8mb4, Binärdaten als Hex), gzip, in einer konsistenten Lese-Transaktion (InnoDB). Der Dump wird gestreamt (ungepufferte Abfrage, INSERT-Blöcke von max. 512 KB) und ist auch von Hand mit mysql einspielbar.

Automatisch. Vor der ersten Schreiboperation einer Sitzung (Projekt + Chat; ohne Chat: Projekt + Einstiegsart wie Scheduled Task) legt executePreparedQuery/executeQuery ein Backup an und meldet es im Tool-Result (auto_backup). Eine neue Sitzung beginnt nach auto_backup_hours (Default 12 h); ein Backup, das jünger als 10 Minuten ist (paralleler Chat), zählt mit. Das gilt für jeden Schreibpfad über das Gateway, also auch für die Contao-Redakteur-Tools. Schlägt das Backup fehl, wird nicht geschrieben (fail-closed) — die Meldung nennt den Grund. Abschalten nur bewusst mit 'auto_backup' => false. Gateways/Connectoren vor Protokoll 5 kennen weder Backup noch Journal: normale Tools schreiben dann weiter und sagen es im Result (auto_backup.unsupported); Tools, die Rückgängig-Machen versprechen (require_journal — alle Contao-Redakteur-Tools über contaoWriteRow), schreiben dann nicht und melden „Connector aktualisieren (Protokoll 5)“ — unabhängig von auto_backup.

Manuell. createDbBackup (höchstens eins pro 30 s), listDbBackups. Rotation nach jedem Backup: backup_keep_days (Default 7) und backup_keep_max (Default 10), das neueste bleibt immer.

Wiederherstellen. restoreDbBackup — nur mit allow_write (Obergrenze der Verbindung und Schreib-Gateway) und nur nach ausdrücklicher Bestätigung im Chat: der erste Aufruf zeigt, welches Backup und was verloren geht, und setzt die Buttons „Ja, wiederherstellen“ / „Nein, abbrechen“; ausgeführt wird erst, wenn danach eine neue Nachricht des Nutzers mit einem klaren Ja im Chat steht (gleicher Baustein confirmChatAction wie contaoSetPublished, Kern App\Tooling\ApprovalGate — das Ja muss die unmittelbar nächste Nachricht sein). Ohne Chat (Scheduled Task, API) nie. Das Gateway prüft zuerst, dass alle Tabellen des Backups heute existieren und in der Schreib-Allowlist sind, legt dann ein frisches Backup des aktuellen Stands an und spielt die Tabellen ein (pro Tabelle DELETE + INSERT, bei InnoDB alles in einer Transaktion, Fremdschlüssel-Prüfung währenddessen aus). Jede Zeile aus der Datei muss exakt ein INSERT INTO <tabelle> (…) VALUES (…) mit reinen Literalen sein — eingeschleuste Statements, Funktionen oder andere Tabellen lassen die Wiederherstellung abbrechen (und zurückrollen). Eine Datei, deren Inhalt nicht mehr zum Hash im Namen passt, wird abgelehnt. Mit tables lassen sich einzelne Tabellen wiederherstellen.

Rollback-Journal. Jede Schreiboperation über das Gateway (executePreparedQuery mit mode: write, executeQuery mit INSERT/UPDATE/DELETE, alle CMS-Tools, die darauf aufsetzen) schreibt im selben Request einen Eintrag nach tm-backups/<projekt>/rollback/journal_<datum>_<zufall>.jsonl.php (JSON-Lines, erste Zeile PHP-Guard):

Einträge sind pro Tool-Aufruf gruppiert (journal_group, z. B. alle Schritte von contaoSetPublished) und tragen einen Hash des Chats. Das Tool-Result nennt die ID (rollback.id). Kann das Journal nicht geschrieben werden, wird die Schreiboperation zurückgerollt (fail-closed). Zurücknehmen: rollbackLastWrite (letzte Änderung dieses Chats) bzw. rollbackWrite mit ID aus listDbWrites — beide mit Vorschau und Ja im Chat; die Contao-Redakteur-Tools nutzen denselben Mechanismus direkt (contaoUndoLastChange). Konflikt-Schutz: Hat sich eine betroffene Zeile seitdem geändert (Hash) oder existiert eine gelöschte Zeile wieder, wird abgebrochen und gemeldet; nur mit force wird trotzdem zurückgenommen (dann nur die Spalten der Änderung). Die Rücknahme selbst läuft in einer Transaktion und wird im Journal vermerkt (keine doppelte Rücknahme; das Journal wird dafür erst gesperrt, dann gelesen). Gelesen werden höchstens die neuesten 400 Journal-Dateien und 16 MB, von hinten; Änderungen am Schnitt (bis 1 h nach dem ältesten geladenen Eintrag) gelten dann als nicht einzeln rücknehmbar — dafür das Backup.

Fremdschlüssel. Wiederherstellen und Zurücknehmen laufen mit SET FOREIGN_KEY_CHECKS = 0 (nur für die eigene DB-Session, danach wieder 1) — sonst scheitern DELETE + INSERT einer Tabelle bzw. das Zurückschreiben gelöschter Zeilen an der Reihenfolge. Folge: MySQL prüft dabei keine Fremdschlüssel. Verweisen Tabellen außerhalb des Backups bzw. der zurückgenommenen Änderung auf wiederhergestellte Zeilen (oder umgekehrt), können danach verwaiste Verweise bleiben, und ON DELETE CASCADE/ON UPDATE lösen nicht aus. Für die CMS-Profile (Contao, WordPress, …) ohne echte Fremdschlüssel ist das ohne Wirkung; bei Shops mit InnoDB-Fremdschlüsseln (Shopware 6, Magento) nach einer Teil-Wiederherstellung (tables) die Verweise prüfen oder das ganze Backup einspielen.

Grenzen (Shared Hosting). Das Gateway setzt set_time_limit wo erlaubt und bricht vor dem Laufzeitlimit des Hosters sauber ab (keine halbe Datei, Meldung mit Tabelle), ebenso bei backup_max_mb oder wenn weniger als 64 MB frei bleiben würden — geprüft vor dem Start und während des Schreibens (spätestens jedes MB), ein Backup füllt also nie die Platte des Kunden. Das Rollback-Journal verlangt 16 MB Reserve; fehlt sie, wird die Schreiboperation zurückgerollt (fail-closed). TaskMonkey wartet bis zu 5 Minuten auf ein Backup. Große Shops: Tabellen per tables einschränken oder Backups beim Hoster einplanen. Eine Wiederherstellung ohne InnoDB (MyISAM) läuft ohne Transaktion — bricht sie ab, meldet das Ergebnis den Teilstand, das Vor-Backup ist dann der Rückweg.

'remote_databases' => [
    'kunde_web' => [
        // … wie oben …
        'backup_dir'        => '../tm-backups/kunde_web', // Default, außerhalb des Web-Roots
        'auto_backup'       => true,                      // Default
        'auto_backup_hours' => 12,
        'backup_keep_days'  => 7,
        'backup_keep_max'   => 10,
    ],
],

#Dauerbetrieb: täglicher Redeploy

Ein Gateway läuft ab. Wenn Tools (z. B. eine API) dauerhaft darauf zugreifen, erneuert ein Scheduled Task es täglich. Jeder Lauf erzeugt einen neuen Token, verlängert die Laufzeit und entfernt das alte Script vom Server. Schlägt ein Projekt fehl, bleibt das bisherige Gateway bis zu seinem Ablauf aktiv und die Admins des Workspaces bekommen eine Mail.

Aufräumen im Web-Root. Beim Redeploy wird das vorherige Script _tm_gateway_<hash>.php samt seiner Rate-Limit-Datei _tm_gateway_<hash>.cache-rate.php (von cache_invalidate) per SSH gelöscht. Danach räumt das neue Gateway sein eigenes Verzeichnis auf (Action sweep, ohne weitere SSH-Befehle): Es löscht nur _tm_gateway_<16 hex>.php, deren eingebetteter Ablauf ($EXPIRES_AT) vorbei ist, und .cache-rate.php-Dateien ohne zugehöriges Script. Nie das eigene Script, nie ein noch gültiges (andere Workspaces/Projekte können denselben Web-Root nutzen), nie Connectoren, keine Unterverzeichnisse oder Symlinks. So verschwinden auch Waisen aus Fehlschlägen oder parallelen Läufen, die kein Datensatz mehr kennt. Die Anzahl steht im Deploy-Ergebnis (orphans_removed, null wenn der Sweep fehlschlug) und im Log. Ein abgelaufenes Gateway, das noch aufgerufen wird, löscht sich zusätzlich selbst (samt Rate-Limit-Datei) und antwortet 404.

// config/tenants/<workspace>/scheduled.php
return [
    'scheduled' => [
        'refresh_db_gateways' => [
            'enabled' => true,
            'tool' => 'refreshDatabaseGateways',
            'interval' => '03:30',
            'description' => 'DB-Gateways täglich neu deployen (Token-Rotation)',
            'args' => [
                'projects' => ['bestand'],   // leer = alle Projekte mit bestehendem Gateway
                'expiry_hours' => 48,        // überbrückt einen ausgefallenen Lauf (max. 72)
                // 'notify' => ['it@firma.de'], // sonst admin_emails des Workspaces
            ],
        ],
    ],
];

Auch ein manueller deployGateway räumt das vorherige Script ab, sobald das neue antwortet. Antwortet das neue nicht, wird es wieder entfernt und das alte bleibt aktiv.

#Dauerbetrieb ohne SSH (Connector)

Für Kunden, die nur FTP oder den Dateimanager ihres Hosters haben. Der Connector ist dasselbe Script wie das Gateway (gleicher SQL-Prüfer, gleiches System-Profil, eingebettete Policy), aber:

• er wird einmal hochgeladen und läuft dauerhaft (kein Ablauf, keine Selbstlöschung),
• jeder Aufruf ist mit einem Secret pro Projekt signiert (HMAC-SHA256) statt mit einem statischen Token,
• Secret-Rotation und Policy-Änderungen laufen über signierte Befehle, ohne neuen Upload.

#Einrichten (Workspace)

In database_connections.php ein Projekt mit 'mode' => 'persistent' anlegen:

'remote_databases' => [
    'kunde_shop' => [
        'mode'        => 'persistent',
        'base_url'    => 'https://www.kunde-shop.de',  // Verzeichnis, in das der Connector kommt
        'profile'     => 'wordpress',                   // für Produktivsysteme festlegen
        'allow_write' => false,
        'tables'      => ['read' => ['wp_posts', 'wp_postmeta']],
        // optional:
        // 'allowed_ips' => ['203.0.113.10'],           // Ausgangs-IP des TaskMonkey-Servers
        // 'state_dir'   => '../tm_state',              // Statusdatei außerhalb des Web-Roots
        // 'sftp' => [                                  // statt FTP-Upload durch den Kunden
        //     'hostname' => 'ssh.kunde.de', 'username' => 'ftp123',
        //     'password' => secret('KUNDE_SFTP_PASS'), 'web_root' => '/html/shop',
        //     'host_key' => 'SHA256:…',                // Pflicht, vorab beim Hoster bestätigen
        // ],
    ],
],

#Schritt für Schritt (Kunde)

Im Manage-Bereich unter Verwaltung → DB-Connectoren (/manage/connectors):

1. Connector herunterladen. Die Datei heißt _tm_connector_<zufall>.php. Jeder Download erzeugt einen neuen Connector mit neuem Start-Secret; ein schon installierter alter entfernt sich dabei selbst.

2. Die Datei unverändert per FTP-Programm (z. B. FileZilla) oder Dateimanager des Hosters (all-inkl KAS, IONOS, Strato …) in den Web-Root laden — das Verzeichnis, das base_url im Browser zeigt:

   System	Web-Root
   Contao 4.13 / 5	public/ (ältere Contao-4: web/)
   WordPress / WooCommerce	Hauptverzeichnis mit wp-config.php
   Shopware 6	public/
   Magento 2	pub/
   TYPO3	public/ (Composer) bzw. Hauptverzeichnis mit fileadmin/
   Gambio, JTL-Shop, PrestaShop	Hauptverzeichnis des Shops
   OXID eShop	source/ (OXID 6/7)
   Joomla	Hauptverzeichnis mit configuration.php
   Drupal	web/ (Composer) bzw. Hauptverzeichnis mit core/

   Der Connector sucht das System vom eigenen Verzeichnis bis vier Ebenen aufwärts.

3. Verbindung testen. Der Connector meldet System, Version, Profil und Datenbank. Beim ersten Kontakt wird das Start-Secret aus der Datei sofort ersetzt — die heruntergeladene Datei ist danach wertlos und kann lokal gelöscht werden.

4. Fertig. Tools, Chats und APIs nutzen den Connector über ensureGateway/executeQuery wie ein Gateway.

Per Builder-Chat geht dasselbe ohne Manage-Bereich: createDatabaseConnector({project}) legt nach der Freigabe im Chat den Connector an und liefert einen Download-Link (die Datei heißt exakt _tm_connector_<id>.php; der Inhalt läuft nicht durch Tool-Args oder Logs). Nach dem Upload getConnectorStatus({project, test: true}) — beim ersten Kontakt wird das Start-Secret ersetzt und die Download-Kopie auf unserem Server gelöscht. Der Download-Link gilt nur 72 h (Boot-Fenster des Start-Secrets); wird der Connector nie installiert, löscht der tägliche prune_tool_cache-Lauf die Kopie danach trotzdem, ebenso ein neuer Download die Kopie des Vorgängers. Mit SFTP-Zugang: installConnectorViaSftp({project}). Muster im Builder: showPattern({name: 'contao-redakteur'}).

Secret rotieren (Button oder deployGateway/refreshDatabaseGateways) tauscht das Secret, das alte bleibt 15 Minuten gültig. Deinstallieren lässt den Connector sich selbst löschen; ist er nicht erreichbar, wird das Secret bei uns gelöscht (die Datei ist dann wirkungslos) und der Kunde entfernt sie per FTP.

#Sicherheitsmodell (Connector)

Alles aus dem Sicherheitsmodell des Gateways (SQL-Analyse, Tabellen-Profil, Upload-Prüfung, generische Fehler) gilt unverändert.

Grenzen:

• Wer Schreibzugriff auf das Dateisystem des Kunden hat, kann Statusdatei und Marker löschen — innerhalb der ersten 72 h nach dem Download gilt dann wieder das Start-Secret. Wer dort schreiben kann, kann aber ohnehin die DB-Zugangsdaten des Systems lesen.
• Profil, Präfix, Denylist-Ausnahmen, IP-Allowlist, Tabellen-Erweiterungen und Schreibrecht-Erweiterungen brauchen einen neuen Connector (neu herunterladen, hochladen, testen).
• Der Connector braucht HTTPS beim Kunden und Schreibrecht im eigenen Verzeichnis oder in state_dir. TaskMonkey spricht ihn nur über https:// an, über den EgressGuard (keine internen oder reservierten Adressen, DNS gepinnt, keine Redirects).
• PHP ab 7.3 mit pdo_mysql.
• Web Application Firewalls bei Shared-Hostern (z. B. mod_security) können Requests mit SQL im Body blocken — das gilt auch für das Gateway. Symptom: 403 oder eine HTML-Fehlerseite statt JSON (bzw. „nicht korrekt signiert“). Dann den Hoster bitten, die Regel für die Connector-URL auszunehmen. Eine Base64-Kapselung des Bodys ist vorgesehen, wird aber erst umgesetzt, wenn das bei einem Kunden tatsächlich auftritt.

#Health-Check

// config/tenants/<workspace>/scheduled.php
'check_db_connectors' => [
    'enabled' => true,
    'tool' => 'checkDatabaseConnectors',
    'interval' => '30min',
    'description' => 'DB-Connectoren pingen, Admin-Mail nach 2 Fehlschlägen',
    'args' => ['failure_threshold' => 2],   // Mails gehen nur an admin_emails des Workspaces
],

Nach zwei Fehlschlägen in Folge geht eine Mail an die Admins, bei Wiederkehr eine Entwarnung. Für die tägliche Secret-Rotation zusätzlich refreshDatabaseGateways einplanen (siehe oben); er rotiert bei Connector-Projekten das Secret.

#Update auf Gateway-Protokoll 5

Protokoll 5 bringt Backups und Rollback. SSH-Gateways ersetzt ensureGateway automatisch. Connectoren bis zum nächsten Download: die Backup-Tools melden „kennt Backups und Rollback noch nicht — Connector neu herunterladen“, Schreiben über executePreparedQuery/executeQuery geht weiter, aber ohne automatisches Backup und ohne Rollback-Eintrag (das Tool-Result sagt es, auto_backup.unsupported). Die Contao-Redakteur-Tools schreiben dann nicht („Connector aktualisieren (Protokoll 5)“), weil sie Rückgängig-Machen versprechen. Für den vollen Umfang den Connector im Manage-Bereich neu herunterladen und hochladen. Vorher prüfen, dass PHP eine Ebene über dem Web-Root schreiben darf — sonst backup_dir setzen (bei Protokoll 5 gilt: ohne Journal-Ablage kein Schreiben). Der Ping (deployGateway) zeigt unter backups das Verzeichnis und ob es passt.

Die frühere Contao-Undo-Liste im Chat-State (contao_undo) gibt es nicht mehr; Änderungen, die vor dem Update gemacht wurden, lassen sich nicht mehr per Undo zurücknehmen (Versionen in tl_version bleiben).

#Update auf Gateway-Protokoll 4

Protokoll 4 bringt die Contao-Actions contao_version (Versionen in tl_version) und cache_invalidate (HTTP-Cache leeren) für die Contao-Redakteur-Tools. SSH-Gateways ersetzt ensureGateway automatisch (Protokoll veraltet). Connectoren tragen ihr Script fest beim Kunden: bis zum nächsten Download melden clearCmsCache/createContaoVersion „kennt die Action noch nicht“ — die Contao-Tools arbeiten trotzdem (Undo in TaskMonkey bleibt, Version und Cache-Leeren fehlen dann). Für den vollen Umfang den Connector im Manage-Bereich neu herunterladen und hochladen.

#Update auf Gateway-Protokoll 3

Gateways, die vor den System-Profilen deployt wurden (Protokoll ≤ 2), laufen ohne Tabellen-Prüfung weiter, bis sie ablaufen. getGatewayStatus meldet sie als outdated, ensureGateway ersetzt sie beim nächsten Aufruf automatisch. Laufende Gateways nach dem Update einmal neu deployen (deployGateway oder refreshDatabaseGateways).

Tools, die auf Tabellen außerhalb des Profils zugreifen (eigene Erweiterungen, generische Anwendungen), brauchen danach tables/extra_tables in der Connection-Config.

#Beispiel-Flow im Chat

User: "Welche News sind im Kundenweb diese Woche erschienen?"

Modell:
1. ensureGateway(project: 'kunde_web')   → Gateway läuft (oder wird deployt)
2. executeQuery(sql: "SELECT headline, FROM_UNIXTIME(date) FROM tl_news WHERE date > UNIX_TIMESTAMP() - 604800")

Antwort: "Drei News: …"

Einmalige Recherchen können am Ende removeGateway rufen. Für wiederkehrende Tasks ensureGateway nehmen und das Gateway laufen lassen.

#Use-Cases

• Content-Pflege: News, Seiten, Produkttexte anlegen oder korrigieren
• Migrations-Checks: „Sind alle Datensätze aus der alten DB rüber?"
• Live-Reporting: „Zeig mir den heutigen Umsatz aus dem Shop" (Bestellungen per extra_tables)
• Konsistenz-Checks: „Gibt es Produkte ohne Kategorie?"

Was sich nicht dafür eignet:

• Massendaten-Migrationen (Tool-Calls haben ein Token-Budget)
• Zugriff auf Benutzer-, Kunden- oder Zahlungsdaten — dafür ist das Gateway absichtlich gesperrt
• Daten, die du dauerhaft brauchst — pull sie einmal, leg sie in deine eigene DB (z. B. Supabase)

#Verwandt

• Supabase — wenn du eine eigene DB brauchst, nicht eine fremde anzapfen willst
• Eigene REST-API anbinden — wenn das Zielsystem eine API hat, nimm die statt SQL

#Debug

tm test-tool ensureGateway project=kunde_shop
tm test-tool executeQuery project=kunde_shop sql='SHOW TABLES'
tm logs

• Deploy schlägt fehl: meistens SSH-Key falsch, web_root nicht beschreibbar, oder base_url zeigt nicht auf den Web-Root. Reines SSH-Login zum Ziel manuell testen.
• Host key verification failed: der Server hat einen anderen Host-Key als beim ersten Kontakt. Erst klären, warum (Umzug? Angriff?), dann storage/database_gateways/known_hosts/<workspace>_<projekt> löschen oder host_key setzen.
• Access to table '…' is not allowed (profile …): die Tabelle steht nicht im Profil oder auf der Denylist. deployGateway/ensureGateway zeigen, welches Profil erkannt wurde; ggf. profile, tables oder extra_tables setzen.
• Query failed: … mit error_code: die Details (Original-Meldung der DB) stehen im Tool-Log.
• Connector antwortet mit 404: Datei nicht (mehr) im Web-Root, base_url zeigt woanders hin, IP nicht in allowed_ips oder Secret passt nicht (z. B. Connector neu heruntergeladen, aber alte Datei hochgeladen). Neu herunterladen, hochladen, testen.
• Uhrzeit weicht ab: Server-Uhr des Kunden liegt mehr als 5 min daneben — Hoster ansprechen.
• Connector state file not writable: PHP darf im Connector-Verzeichnis nicht schreiben. Verzeichnis beschreibbar machen oder state_dir setzen und neuen Connector erzeugen.
• Backup directory must be outside the web root / could not be created / „Automatisches Backup vor dem Schreiben fehlgeschlagen“: backup_dir auf ein beschreibbares Verzeichnis außerhalb des Web-Roots setzen (bei Connectoren danach neu herunterladen). deployGateway zeigt unter backups.dir, wohin das Gateway schreiben würde.
• Backup aborted: server time limit reached / larger than … MB: Laufzeitlimit bzw. backup_max_mb — Tabellen einschränken, Limit erhöhen oder beim Hoster max_execution_time anheben.