Faire évoluer le schéma d’un site déployé

EmDash stocke les collections, les champs et les taxonomies dans la base de données, à côté du contenu. Utilisez ce guide pour modifier ce modèle de contenu en production sans le confondre avec un déploiement de code, un seed initial ou une migration du cœur d’EmDash. Les exemples utilisent Cloudflare D1 ; la même séparation s’applique à chaque adaptateur de base de données.

Ce qui change quoi

Un site passe par quatre workflows distincts. Chacun touche une couche différente :

Le fichier seed ne participe qu’à la troisième ligne. Son schéma et sa structure sont appliqués une seule fois, lors de la première requête, avant la fin de l’assistant de configuration. Déployer un fichier seed modifié sur une base de données existante ne fait rien : l’évolution du schéma d’un site en production passe toujours par le panneau d’administration ou l’API.

Modifier le schéma dans le panneau d’administration

Le panneau d’administration est le moyen principal de faire évoluer un site déployé. Ouvrez Content Types dans l’administration, puis ajoutez, modifiez ou supprimez des collections et des champs. Les changements prennent effet immédiatement : l’API de contenu, le loader et l’interface d’édition lisent tous le schéma depuis la base de données à l’exécution.

Consultez Collections et champs pour les types de champs disponibles, les règles de validation et les options de widget.

Après avoir modifié le schéma, régénérez les types TypeScript utilisés par vos modèles. La commande emdash types lit le schéma d’une instance en cours d’exécution ; elle peut donc pointer directement vers le site déployé :

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

Modifier le schéma depuis la CLI

Les commandes emdash schema communiquent avec une instance en cours d’exécution via son API REST ; elles fonctionnent donc sur un site déployé exactement comme en développement local. Authentifiez-vous une fois avec le device flow :

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

Vous pouvez aussi créer un jeton d’API dans l’administration sous Settings → API Tokens et le transmettre avec --token ou la variable d’environnement EMDASH_TOKEN — utile pour la CI.

Faites ensuite évoluer le schéma avec les mêmes commandes que celles que vous utiliseriez en local :

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

Ces commandes peuvent être versionnées dans un script afin que chaque environnement reçoive le même changement ordonné. Elles ne sont pas automatiquement idempotentes : relancer create ou add-field sur un objet qui existe déjà peut échouer. Inspectez la cible avec emdash schema list ou get, notez quel environnement a terminé chaque étape et arrêtez-vous à la première erreur.

Consultez la référence de la CLI pour la liste complète des commandes.

Garder le fichier seed synchronisé

Le fichier seed embarqué dans votre build détermine l’état initial d’une base de données neuve : un nouvel environnement de preview, une reconstruction après sinistre ou un second déploiement du même site. Si le seed décrit encore le blog de démarrage alors que la production a évolué vers autre chose, chaque nouvel environnement s’initialise avec le mauvais modèle.

Le build embarque le premier fichier seed trouvé à .emdash/seed.json, au chemin indiqué dans package.json#emdash.seed, ou à seed/seed.json. S’il n’y en a aucun, un seed par défaut intégré (le modèle du blog de démarrage) est embarqué, et astro dev affiche un avertissement.

Après avoir fait évoluer le schéma d’un site déployé, réexportez le modèle en production vers votre dépôt. emdash export-seed lit un fichier SQLite local. Créez les fichiers SQL comme décrit dans Créer un dump D1 hors site, chargez les tables et les lignes dans une base de données locale, puis exportez le 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

Le seed exporté contient les paramètres, les collections, les taxonomies, les menus, les redirections, les zones de widgets et les sections du site en production. Ajoutez --with-content pour inclure les entrées. Commitez le .emdash/seed.json mis à jour avec le code qui dépend du nouveau schéma, afin qu’un nouvel environnement s’initialise toujours avec un modèle que le code comprend.

Répéter les changements sur un environnement de preview

Un changement de schéma destructif (supprimer un champ, restructurer une collection) se répète plus sûrement sur une copie jetable de la production.

Récupérer d’une erreur

• Un champ a été supprimé par erreur. La colonne et ses données ont disparu de la base de données en production. Restaurez à partir d’une sauvegarde à un instant donné avec Time Travel de D1, ou rajoutez le champ et restaurez ses valeurs à partir d’un dump D1 hors site antérieur.
• Un nouvel environnement s’est initialisé avec le mauvais modèle. Le seed embarqué était obsolète ou absent. Mettez à jour .emdash/seed.json (consultez Garder le fichier seed synchronisé), reconstruisez et dirigez le déploiement vers une base de données vide pour recommencer l’initialisation.
• Le schéma et les modèles ne concordent pas. Les déploiements et les changements de schéma sont indépendants ; ordonnez-les donc délibérément : les changements de schéma additifs (nouvelle collection, nouveau champ facultatif) passent en premier, puis le code qui les utilise. Pour les suppressions, déployez d’abord le code qui cesse d’utiliser le champ, puis supprimez le champ.