---
title: "Datenbank und Migrationen"
description: "Eigene Tabellen eines Plugins: Namen, Pflichtspalten, Verweise auf den Kern, Migrationsdateien, erlaubtes SQL, Fortschritt und Zugriff über db()"
---

Plugins speichern ihre Daten in **eigenen Tabellen** in der Datenbank von QuickTribe. Sie entstehen ausschließlich über SQL-Migrationen des Plugins; Doctrine und die Migrationen der Plattform sehen und verändern sie nicht. Für einfache Werte gibt es daneben [Zusatzfelder](/plugins/erweiterungspunkte#zusatzfelder), [Einstellungen und Zustand](/plugins/erweiterungspunkte#einstellungen) – ganz ohne eigene Tabelle.

## Pflichtmuster für Tabellen

- **Name:** `plg_<id>__<kurzname>`, in der ID wird `-` zu `_` (Plugin `hallo-welt` → `plg_hallo_welt__greetings`). Kurzname `[a-z][a-z0-9_]`, höchstens 31 Zeichen; jeder Bezeichner (auch Index- und Constraint-Namen) höchstens 64 Zeichen. Im Code liefert `db()->table('greetings')` den vollen Namen.
- **IDs:** `CHAR(36) CHARACTER SET ascii COLLATE ascii_bin`, erzeugt mit `db()->uuid()` (UUID v7, zeitlich sortierbar).
- **Community:** Jede Tabelle mit Personendaten hat `community_id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL` mit Index. `app:plugin:validate` warnt bei `CREATE TABLE` ohne diese Spalte. Jede Abfrage filtert nach ihr.
- **Verweise auf den Kern** (`event_id`, `membership_id`, `user_id`) als `CHAR(36)` **ohne Fremdschlüssel** – der Kern speichert IDs binär. Aufgeräumt wird über Hooks und einen Abgleich (siehe [unten](#verweise-auf-den-kern)).
- **Engine:** nur InnoDB, Zeichensatz `utf8mb4`.
- **Unveränderbarkeit** (etwa „nur anhängen“) gibt es auf Datenbank-Ebene nicht – Trigger sind nicht erlaubt. Sie ist Konvention im Code; Manipulationen erkennt man über Hash-Ketten, [Signaturen und Zeitstempel](/plugins/kern-dienste#verschlüsselung-und-signaturen).

## Migrationsdateien

Migrationen liegen als `migrations/NNNN_name.sql` im Plugin – vier Ziffern, aufsteigend, z. B. `0001_init.sql`, `0002_notes.sql`. Eine Datei enthält beliebig viele Anweisungen, getrennt durch `;`.

```sql
-- migrations/0001_init.sql
CREATE TABLE IF NOT EXISTS plg_hallo_welt__greetings (
    id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
    community_id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
    membership_id CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
    text VARCHAR(200) NOT NULL,
    created_at DATETIME NOT NULL,
    PRIMARY KEY (id),
    INDEX idx_plg_hallo_welt__greetings_community (community_id),
    INDEX idx_plg_hallo_welt__greetings_membership (membership_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

```sql
-- migrations/0002_notes.sql
ALTER TABLE plg_hallo_welt__greetings ADD COLUMN IF NOT EXISTS note TEXT NULL;
```

**Erlaubt** sind nur `CREATE TABLE [IF NOT EXISTS]`, `ALTER TABLE`, `DROP TABLE [IF EXISTS]`, `CREATE [UNIQUE|FULLTEXT|SPATIAL] INDEX [IF NOT EXISTS]`, `DROP INDEX`, `RENAME TABLE`, `INSERT INTO`, `UPDATE` und `DELETE FROM` – jeweils nur auf Tabellen des eigenen Präfixes; Fremdschlüssel nur zwischen eigenen Tabellen. Ein Prüfer liest jede Anweisung vollständig und weist alles andere ab, bevor irgendetwas läuft – etwa Trigger, Prozeduren, `GRANT`, `SET`, `LOAD`, `INTO OUTFILE`, `DIRECTORY`, `TABLESPACE`, Partitionierung, andere Engines, `@`-Variablen und Funktionen wie `SLEEP()` oder `LOAD_FILE()`. Bekannte Fehlalarme: Namen von `WITH`-Abfragen (Ausweg: auch sie mit dem eigenen Präfix benennen) und verschachtelte Joins der Form `a JOIN b JOIN c ON … ON …`.

Regeln:

- **Idempotent schreiben:** `IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, `DROP … IF EXISTS`. Sonst warnt `app:plugin:validate`.
- **Nie eine ausgeführte Datei ändern.** QuickTribe speichert eine Prüfsumme je Datei; ändert sich eine bereits ausgeführte Datei, gilt das Plugin als fehlerhaft und wird nicht geladen. Änderungen gehören in eine neue Datei.
- **Kein Zurück:** Ein Downgrade gibt es nicht.
- **Fortschritt je Anweisung:** MariaDB schreibt Tabellenänderungen sofort fest. Deshalb merkt sich QuickTribe nach jeder Anweisung den Stand und setzt nach einem Abbruch an der nächsten fort – solange die bereits ausgeführten Anweisungen unverändert sind; sonst beginnt die Datei von vorn.
- Ein Fehler bricht ab und nennt Datei, Nummer der Anweisung und Meldung der Datenbank.

Ausgeführt werden Migrationen beim Aktivieren, im Dienst `migrate`, mit `app:plugin:migrate` (siehe [Plugins betreiben → Migrationen](/plugins/betrieb#migrationen)) und in den Tests automatisch. Solange eine Migration offen ist, lädt QuickTribe das Plugin nicht. In der Entwicklung setzt `php bin/console app:plugin:migrate --all --fresh` alle Plugin-Tabellen zurück und baut sie neu auf.

## Zugriff im Code

| Methode | Zweck |
| --- | --- |
| `table(string $name): string` | voller Tabellenname aus dem Kurznamen |
| `uuid(): string` | neue ID (UUID v7) |
| `fetchAll($sql, $params = [], $types = [])`, `fetchOne()`, `fetchValue()` | lesen |
| `execute($sql, $params = [], $types = [])` | schreiben mit eigenem SQL, liefert die Zahl betroffener Zeilen |
| `insert(string $table, array $row)`, `update(string $table, array $data, array $criteria)`, `delete(string $table, array $criteria)` | einfache Schreibvorgänge mit Kurznamen; die Kriterien enthalten `community_id`, wenn die Tabelle die Spalte hat |
| `transactional(\Closure $work)` | Transaktion – einziger Weg dafür |
| `connection()` | die Doctrine-DBAL-Verbindung der Plattform, ohne jeden Schutz |

```php
$db = $this->ctx->db();
$rows = $db->fetchAll(
    'SELECT id, text FROM '.$db->table('greetings').' WHERE community_id = ? AND membership_id IN (?) ORDER BY created_at DESC',
    [$communityId, $membershipIds],
    [ParameterType::STRING, ArrayParameterType::STRING],
);

$db->transactional(function () use ($db, $communityId, $membershipId, $text): void {
    $db->insert('greetings', [
        'id' => $db->uuid(),
        'community_id' => $communityId,
        'membership_id' => $membershipId,
        'text' => $text,
        'created_at' => $this->ctx->clock()->now()->setTimezone(new \DateTimeZone('UTC'))->format('Y-m-d H:i:s'),
    ]);
    $this->ctx->tasks()->dispatch('archive', [], $communityId);   // läuft erst nach dem Commit
});
```

- **Nur eigene Tabellen.** Eigenes SQL greift nur auf `plg_<id>__*` zu; Daten der Plattform kommen über die [Kern-Dienste](/plugins/kern-dienste). Das ist Konvention (Vertrauensmodell) – in den Tests prüft ein Wächter die Tabellennamen jeder Abfrage und schlägt bei fremden Tabellen Alarm.
- **Bezeichner nie aus Eingaben**, Sortierung nur über eine feste Liste erlaubter Spalten; Werte immer als Parameter.
- **Transaktionen nur mit `transactional()`.** Anweisungen, die Transaktionen steuern oder implizit festschreiben (`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `LOCK TABLES`, `SET autocommit`, `CREATE`/`ALTER`/`DROP` außer temporären Tabellen, `TRUNCATE`, `RENAME` …), lehnt `db()` ab. Aufrufe anderer Dienste innerhalb von `transactional()` (Nachrichten, Benachrichtigungen) laufen in derselben Transaktion; Aufgaben und Hooks gehen erst nach dem Commit hinaus, ein Rollback verwirft sie.
- In GET-Handlern werfen `insert`, `update`, `delete` und `execute` eine `LogicException`.
- Zeitstempel als `DATETIME` in UTC speichern.

## Verweise auf den Kern

Weil Plugin-Tabellen keine Fremdschlüssel auf die Plattform haben, räumt das Plugin selbst auf:

1. **Aufräum-Hooks** – `member.left`, `event.deleted`, `account.deleted` – kommen auch an, wenn das Plugin in der Community ausgeschaltet ist (siehe [Hook-Katalog](/plugins/hooks)).
2. **Täglicher Abgleich** als [Job](/plugins/erweiterungspunkte#abgleich-und-löschfristen), denn Hooks kommen höchstens einmal und können bei einem Ausfall verloren gehen. Er läuft über die Communities der eigenen Tabellen (`SELECT DISTINCT community_id …`), **nicht** über `forEachCommunity()` – das kennt nur Communities, in denen das Plugin eingeschaltet ist, und keine gesperrten. Je Community mit eigenem `try`/`catch` und `shouldStop()`: `communities()->exists()` liefert, ob es die Community noch gibt, `events()->existing($communityId, $eventIds)` die noch vorhandenen Events, `events()->occurrence()` einen Termin (oder `null`), `members()->manyByMembership()` die Mitgliedschaften (mit Status und `canRead()`).
3. **Datenschutz:** Kontolöschung und gelöschte Communities erreichen das Plugin zuverlässig über `PrivacyAware` mit Wiederholung (siehe [Datenschutz und Beispieldaten](/plugins/datenschutz)).
