Das Schema einer bereitgestellten Site weiterentwickeln

EmDash speichert Collections, Felder und Taxonomien in der Datenbank neben den Inhalten. Verwenden Sie diesen Leitfaden, um dieses Live-Inhaltsmodell zu ändern, ohne es mit einem Code-Deployment, einem erstmaligen Seed oder einer EmDash-Core-Migration zu verwechseln. Die Beispiele verwenden Cloudflare D1; dieselbe Trennung gilt für jeden Datenbank-Adapter.

Was ändert was

Eine Site durchläuft vier unterschiedliche Workflows. Jeder berührt eine andere Ebene:

Workflow	Was sich ändert	Wie
Inhalte bearbeiten	Einträge, Medien, Einstellungen	Admin-Bereich oder Content-API
Code-Deployment	Templates, Konfiguration, EmDash-Version	`wrangler deploy` – kann von EmDash verwaltete Datenbanktabellen migrieren
Erstmaliges Bootstrapping	Alles, ausgehend von leer	Migrationen + Seed-Datei + Setup-Assistent, automatisch beim ersten Start
Schema-Weiterentwicklung	Collections, Felder, Taxonomien	Admin-Bereich oder `emdash schema` gegen die Live-Site (diese Seite)

Die Seed-Datei beteiligt sich nur an der dritten Zeile. Ihr Schema und ihre Struktur werden einmalig angewendet, bei der ersten Anfrage, bevor der Setup-Assistent abgeschlossen wurde. Das Deployment einer geänderten Seed-Datei gegen eine bestehende Datenbank bewirkt nichts – das Schema einer Live-Site wird immer über den Admin-Bereich oder die API weiterentwickelt.

Das Schema im Admin-Bereich ändern

Der Admin-Bereich ist der primäre Weg, eine bereitgestellte Site weiterzuentwickeln. Öffnen Sie im Admin Content Types und fügen Sie Collections und Felder hinzu, bearbeiten oder entfernen Sie sie. Änderungen werden sofort wirksam – die Content-API, der Loader und die Bearbeitungsoberfläche lesen das Schema zur Laufzeit aus der Datenbank.

Die verfügbaren Feldtypen, Validierungsregeln und Widget-Optionen finden Sie unter Sammlungen und Felder.

Generieren Sie nach einer Schemaänderung die TypeScript-Typen neu, die Ihre Templates verwenden. Der Befehl emdash types liest das Schema aus einer laufenden Instanz und kann daher direkt auf die bereitgestellte Site zeigen:

npx emdash types --url https://example.com

Das Schema über die CLI ändern

Die emdash schema-Befehle sprechen über die REST-API mit einer laufenden Instanz und funktionieren daher gegen eine bereitgestellte Site genauso wie gegen die lokale Entwicklung. Authentifizieren Sie sich einmalig mit dem Device-Flow:

npx emdash login --url https://example.com

Alternativ erstellen Sie im Admin unter Settings → API Tokens ein API-Token und übergeben es mit --token oder über die Umgebungsvariable EMDASH_TOKEN – nützlich für CI.

Entwickeln Sie das Schema anschließend mit denselben Befehlen weiter, die Sie lokal verwenden würden:

npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com

Diese Befehle können in ein Skript eingecheckt werden, sodass jede Umgebung dieselbe geordnete Änderung erhält. Die Befehle sind nicht automatisch idempotent: Das erneute Ausführen von create oder add-field gegen ein bereits vorhandenes Objekt kann fehlschlagen. Prüfen Sie das Ziel mit emdash schema list oder get, halten Sie fest, welche Umgebung welchen Schritt abgeschlossen hat, und brechen Sie beim ersten Fehler ab.

Die vollständige Befehlsliste finden Sie in der CLI-Referenz.

Die Seed-Datei synchron halten

Die in Ihren Build eingebettete Seed-Datei bestimmt, womit eine frische Datenbank initialisiert wird: eine neue Preview-Umgebung, ein Disaster-Recovery-Neuaufbau oder eine zweite Bereitstellung derselben Site. Beschreibt der Seed noch den Starter-Blog, während sich die Produktion zu etwas anderem entwickelt hat, wird jede frische Umgebung mit dem falschen Modell gebootstrappt.

Der Build bettet die erste gefundene Seed-Datei ein: .emdash/seed.json, den Pfad in package.json#emdash.seed oder seed/seed.json. Ist keine vorhanden, wird ein integrierter Standard-Seed (das Starter-Blog-Modell) eingebettet, und astro dev gibt eine Warnung aus.

Exportieren Sie nach der Weiterentwicklung des Schemas einer bereitgestellten Site das Live-Modell zurück in Ihr Repository. emdash export-seed liest eine lokale SQLite-Datei. Erstellen Sie die SQL-Dateien wie unter Einen Offsite-D1-Dump erstellen beschrieben, laden Sie die Tabellen und Zeilen in eine lokale Datenbank und exportieren Sie den Seed:

sqlite3 prod.db < backup-schema.sql
sqlite3 prod.db < backup-folders.sql
sqlite3 prod.db < backup-data.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

Der exportierte Seed enthält die Einstellungen, Collections, Taxonomien, Menüs, Weiterleitungen, Widget-Bereiche und Sections der Live-Site. Fügen Sie --with-content hinzu, um Einträge einzuschließen. Committen Sie die aktualisierte .emdash/seed.json zusammen mit dem Code, der vom neuen Schema abhängt, damit eine frische Umgebung immer mit einem Modell gebootstrappt wird, das der Code versteht.

Änderungen in einer Preview-Umgebung proben

Eine destruktive Schemaänderung (ein Feld entfernen, eine Collection umstrukturieren) probt man am sichersten an einer Wegwerfkopie der Produktion.

Erstellen Sie eine separate Preview-D1-Datenbank und lassen Sie Wrangler sie der Umgebung preview hinzufügen:
```
npx wrangler d1 create emdash-db-preview \
  --binding DB --env preview --update-config
```
Vergewissern Sie sich, dass env.preview.d1_databases den neuen Datenbanknamen und die UUID enthält. Bindings werden nicht aus der Wrangler-Konfiguration der obersten Ebene geerbt.

Erstellen Sie die SQL-Dateien aus der Produktion wie unter Einen Offsite-D1-Dump erstellen beschrieben und importieren Sie sie dann der Reihe nach über das DB-Binding der Preview-Umgebung:

npx wrangler d1 execute DB --env preview --remote --file=./backup-schema.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-folders.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-data.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-indexes.sql

Die Preview-Site baut ihren Suchindex beim ersten Aufruf der Such-API neu auf, wie in diesem Abschnitt beschrieben.

Bauen Sie das Projekt, stellen Sie es in der Preview-Umgebung bereit und führen Sie die Schemaänderung dann gegen die Preview-URL aus:

npm run build
npx wrangler deploy --env preview
npx emdash schema remove-field posts legacy_field --url https://preview.example.com

Prüfen Sie die öffentlichen Seiten, die Admin-Formulare, die generierten Typen und jedes Template, das die geänderten Felder liest. Erstellen Sie ein frisches Produktions-Datenbank-Backup und führen Sie dieselben Befehle dann einmal gegen die Produktion aus.

Von einem Fehler erholen

Ein Feld wurde versehentlich entfernt. Die Spalte und ihre Daten sind aus der Live-Datenbank verschwunden. Stellen Sie sie aus einem punktgenauen D1-Time-Travel-Backup wieder her oder fügen Sie das Feld erneut hinzu und stellen Sie seine Werte aus einem früheren Offsite-D1-Dump wieder her.
Eine frische Umgebung wurde mit dem falschen Modell gebootstrappt. Der eingebettete Seed war veraltet oder fehlte. Aktualisieren Sie .emdash/seed.json (siehe Die Seed-Datei synchron halten), bauen Sie neu und richten Sie das Deployment auf eine leere Datenbank, um erneut zu bootstrappen.
Schema und Templates stimmen nicht überein. Deployments und Schemaänderungen sind unabhängig voneinander, ordnen Sie sie daher bewusst: Additive Schemaänderungen (neue Collection, neues optionales Feld) kommen zuerst, danach der Code, der sie verwendet. Bei Entfernungen stellen Sie zuerst den Code bereit, der das Feld nicht mehr verwendet, und entfernen dann das Feld.