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

EmDash stocke les collections, champs et taxonomies dans la base de données à côté du contenu. Utilisez ce guide pour modifier le modèle de contenu en production sans le confondre avec un déploiement de code, un seeding initial ou une migration core 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. Il est appliqué une fois, quand la base de données est vide et que l’assistant de configuration n’a pas été complété. Déployer un fichier seed modifié contre une base de données existante ne fait rien — faire évoluer le schéma d’un site en production passe toujours par le panneau d’admin ou l’API.

Modifier le schéma dans le panneau d’admin

Le panneau d’admin est le moyen principal de faire évoluer un site déployé. Ouvrez Content Types dans l’admin et ajoutez, modifiez ou supprimez des collections et des champs. Les modifications 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 au runtime.

Voir Collections et champs pour les types de champs disponibles, les règles de validation et les options de widgets.

Après avoir modifié le schéma, régénérez les types TypeScript utilisés par vos templates. La commande emdash types lit le schéma depuis 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 contre un site déployé de la même manière que contre le dev local. Authentifiez-vous une fois avec le flux de dispositif :

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

Alternativement, créez un token API dans l’admin sous Paramètres → Tokens API et passez-le avec --token ou la variable d’environnement EMDASH_TOKEN — utile pour la CI.

Puis faites évoluer le schéma avec les mêmes commandes que vous utiliseriez localement :

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 enregistrées dans un script pour que chaque environnement reçoive le même changement ordonné. Les commandes ne sont pas automatiquement idempotentes : réexécuter create ou add-field contre un objet existant peut échouer. Inspectez la cible avec emdash schema list ou get, notez quel environnement a complété chaque étape, et arrêtez à la première erreur.

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

Garder le fichier seed synchronisé

Le fichier seed intégré dans votre build détermine ce avec quoi une base de données vierge s’initialise : un nouvel environnement de preview, une reconstruction de récupération 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 environnement vierge s’initialise avec le mauvais modèle.

Le build intègre le premier fichier seed trouvé à .emdash/seed.json, le chemin dans package.json#emdash.seed, ou seed/seed.json. Si aucun n’est présent, un seed par défaut intégré (le modèle du blog de démarrage) est intégré, et astro dev enregistre un avertissement.

Après avoir fait évoluer le schéma d’un site déployé, exportez le modèle en production vers votre dépôt. emdash export-seed lit un fichier SQLite local, et wrangler d1 export en produit un depuis la base de données D1 déployée :

npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

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

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

Un changement destructif de schéma (supprimer un champ, restructurer une collection) est plus sûr répété contre 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 depuis un point de sauvegarde D1 Time Travel, ou rajoutez le champ et restaurez ses valeurs depuis un wrangler d1 export antérieur.
• Un environnement vierge s’est initialisé avec le mauvais modèle. Le seed intégré était périmé ou manquant. Mettez à jour .emdash/seed.json (voir Garder le fichier seed synchronisé), reconstruisez et pointez le déploiement vers une base de données vide pour réinitialiser.
• Le schéma et les templates 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 optionnel) d’abord, 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.