Gérer les migrations de base de données du noyau

Les migrations du noyau EmDash mettent à jour les tables propres d’EmDash et les colonnes standard des tables de contenu. Elles ne créent, suppriment ni renomment vos collections et champs ; consultez Evolving a Deployed Site pour les modifications du modèle de contenu.

Le mode de migration à l’exécution est auto par défaut, de sorte que les déploiements existants continuent d’appliquer les migrations du noyau en attente au démarrage. Les migrations gérées par le déploiement permettent à un build de migrer sa base de données avant que le nouveau code d’application ne reçoive du trafic, puis permettent à l’exécution de vérifier ou de faire confiance à cette étape de déploiement.

Build, migrate, deploy, check

Un build ou sync Astro écrit .emdash/migrations.json. Ce manifeste sans secrets enregistre la version exacte d’EmDash, l’ensemble ordonné des migrations, la configuration des locales et l’exécuteur de migrations de l’adaptateur utilisé par ce build.

Exécutez ces commandes depuis le projet dont les dépendances ont produit le manifeste. Commencez par construire et inspecter la cible.

pnpm build
pnpm emdash migrate --status

Après avoir confirmé que la cible rapportée est la base de données prévue, lancez la migration interactive. Vérifiez à nouveau la cible à l’invite avant de confirmer. Puis déployez le même build et vérifiez le schéma déployé.

pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

emdash migrate --status rapporte les migrations appliquées, en attente et inconnues sans modifier la base de données. La commande simple emdash migrate affiche la cible et demande confirmation avant d’appliquer les migrations en attente.

--check n’applique jamais de migrations et termine avec un code non nul lorsque des migrations connues sont en attente ou que la base de données contient des enregistrements de migration inconnus du build. Utilisez --status lorsque vous souhaitez inspecter les mêmes ensembles de migrations sans le code de sortie non nul « travail requis » de check. La référence CLI distingue les codes de sortie en attente, inconnus, de confirmation, d’interruption et opérationnels.

L’application non interactive et chaque application avec --json nécessitent --expected-target-fingerprint ; la commande échoue si la cible résolue ne correspond pas. Utilisez ces options dans les jobs de déploiement automatisés, pas pour le workflow interactif décrit ci-dessus.

Utilisez --manifest path/to/migrations.json pour un manifeste stocké ailleurs. Pour une investigation locale, --from-config [--config astro.config.mjs] évalue explicitement la configuration de projet de confiance sans exécuter les hooks Astro ni démarrer un serveur. Les pipelines de déploiement doivent consommer le manifeste du build.

Sélectionner la base de données explicitement

L’adaptateur configuré fournit des informations de cible sans secrets au manifeste. Les identifiants restent dans les variables d’environnement et ne sont lus que par la commande de migration.

Adaptateur	Cible du manifeste	Variable d’identifiants par défaut	Remplacement utile
SQLite	Chemin de base de données ou URL `file:`	—	`--database <chemin>`
libSQL	URL publique	`TURSO_AUTH_TOKEN`	Configurer `migrationAuthTokenEnv`
PostgreSQL	Nom de la variable de connexion	`DATABASE_URL`	`--database-url-env <nom>`
Cloudflare D1	Nom du binding Wrangler	`CLOUDFLARE_API_TOKEN`	`--d1`, `--account-id`, `--wrangler-config`, `--wrangler-env`
Hyperdrive	Nom du binding primaire et de la variable d’origine	Variable direct-origin spécifique au binding	Configurer `migrationConnectionStringEnv`

Les chemins SQLite relatifs sont résolus depuis la racine du projet, pas depuis le package EmDash installé ni depuis le sous-répertoire courant du shell. Les étiquettes de cible PostgreSQL, libSQL et Hyperdrive omettent les identifiants et paramètres d’URL.

Provisionner D1 avant de le migrer

La création d’une base de données D1 et la migration de son schéma sont des opérations distinctes. emdash migrate ne crée jamais une base de données manquante.

Provisionnez la base de données et enregistrez son UUID de production.
```
pnpm wrangler d1 create my-site-production
```
Ajoutez cet UUID au binding et à l’environnement prévus dans wrangler.jsonc.
Construisez le site pour que le binding D1 soit enregistré dans .emdash/migrations.json.

Définissez l’ID de compte et un token avec permission d’édition D1. Inspectez la cible sélectionnée, puis lancez la migration interactive. Confirmez l’invite uniquement lorsque le compte et la base de données correspondent à la base de données de production prévue.

export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."
pnpm emdash migrate \
  --status \
  --wrangler-config wrangler.jsonc \
  --wrangler-env production
pnpm emdash migrate \
  --wrangler-config wrangler.jsonc \
  --wrangler-env production

Vous pouvez également fournir --account-id avec --d1 <uuid-ou-nom-de-base-de-données>. La recherche par nom doit résoudre exactement une base de données. Les IDs de prévisualisation, les IDs de substitution, les comptes en conflit et les bindings ambigus échouent de manière fermée.

Configurer les migrations D1 dans CI

D1 ne fournit pas le verrou de migration consultatif utilisé par PostgreSQL. Exécutez au plus un job de migration par compte et UUID de base de données.

Définissez les secrets et variables suivants dans l’environnement CI :

Secret CLOUDFLARE_API_TOKEN : un token avec permission d’édition D1.
Variable CLOUDFLARE_ACCOUNT_ID : l’ID de compte Cloudflare propriétaire de la base de données.
Variable D1_DATABASE_ID : l’UUID de la base de données D1 de production.
Variable EMDASH_TARGET_FINGERPRINT : l’empreinte affichée par emdash migrate --status après avoir vérifié le compte et la base de données localement.

Le workflow GitHub Actions suivant utilise ces valeurs et associe le groupe de concurrence aux deux identifiants immuables de D1. Son étape d’application est non interactive, il fournit donc explicitement l’empreinte de la cible vérifiée.

name: Deploy

on:
  workflow_dispatch:

concurrency:
  group: emdash-migrations-${{ vars.CLOUDFLARE_ACCOUNT_ID }}-${{ vars.D1_DATABASE_ID }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - name: Inspect EmDash migration target
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --status --json \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"
      - name: Apply EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          EMDASH_TARGET_FINGERPRINT: ${{ vars.EMDASH_TARGET_FINGERPRINT }}
        run: |
          pnpm emdash migrate \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}" \
            --expected-target-fingerprint "$EMDASH_TARGET_FINGERPRINT"
      - run: pnpm wrangler deploy
      - name: Check EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --check \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"

Mettez à jour EMDASH_TARGET_FINGERPRINT uniquement après avoir vérifié une cible modifiée localement. L’empreinte ne contient aucun identifiant, mais la modifier sans vérifier le compte et la base de données supprime la protection contre la migration de la mauvaise base de données.

Hyperdrive se connecte à l’origine

L’exécuteur de migrations de Hyperdrive ouvre une connexion PostgreSQL directe vers l’origine. Il n’envoie pas de trafic de migration via Hyperdrive, n’utilise pas le binding caché optionnel et n’hérite pas de l’accessibilité réseau privé du Worker.

Le runner de déploiement doit pouvoir atteindre l’origine. Définissez migrationConnectionStringEnv sur hyperdrive() lorsque la variable spécifique au binding par défaut est inadaptée, et fournissez cette variable uniquement au job de migration. Gardez séparés les identifiants Hyperdrive d’exécution et les identifiants de déploiement direct-origin.

Adopter l’application à l’exécution progressivement

La configuration d’intégration EmDash suivante active l’application à l’exécution tout en conservant les migrations automatiques en développement.

emdash({
	database,
	migrations: {
		runtime: "check",
		dev: "auto",
	},
});

auto est la valeur par défaut rétrocompatible. L’exécution au démarrage vérifie et applique les migrations en attente.
check effectue une requête de statut directionnelle et renvoie 503 avant de servir une requête lorsque des migrations connues sont en attente. Il tolère les enregistrements d’un build compatible plus récent pendant un déploiement progressif.
manual n’effectue aucune migration ni requête de statut à l’exécution. Utilisez-le uniquement après que le pipeline de déploiement applique et vérifie chaque build de manière fiable.

EMDASH_MIGRATIONS_MODE peut remplacer le mode à l’exécution lorsque le même artefact est promu à travers plusieurs environnements. Les routes de contournement de configuration et de développement obéissent au mode effectif ; elles ne peuvent pas migrer silencieusement derrière check ou manual.

Un déploiement progressif conservateur est auto pendant l’introduction du job de déploiement, puis check une fois le job fiable, puis manual lorsqu’une vérification externe est imposée pour chaque déploiement.

Compatibilité pendant les déploiements progressifs

Les migrations du noyau suivent le séquencement expand/deploy/contract. Un déploiement peut temporairement exécuter d’anciens et de nouveaux isolats d’application contre la base de données étendue, et un backfill peut encore être en cours. Ne contractez pas un schéma tant que chaque version déployée n’a pas cessé de l’utiliser.

Les enregistrements de migration appliqués inconnus sont tolérés par le check à l’exécution uniquement pour cette direction de déploiement progressif. La vérification exacte de la CLI les signale et apply refuse la mutation, car la base de données peut être plus récente ou avoir un historique de migration divergent.

Dépannage

Aucun manifeste de migration trouvé. Construisez ou synchronisez d’abord le projet. Utilisez --manifest pour un emplacement d’artefact non standard ou choisissez explicitement --from-config pour une investigation locale.
L’artefact ne correspond pas à l’EmDash du projet. Reconstruisez et déployez l’application et le manifeste ensemble. Exécutez la CLI du projet au lieu d’une installation globale.
La cible est manquante ou ambiguë. Provisionnez-la d’abord, puis fournissez un chemin de base de données explicite, un nom de variable de connexion, un sélecteur D1, ou une configuration et un environnement Wrangler sélectionnés. EmDash ne devine pas à partir de variables d’environnement ou de bindings non liés.
L’empreinte de la cible a changé. Arrêtez et vérifiez le compte, l’environnement, le nom de la base de données, l’UUID ou le chemin affichés. Mettez à jour l’empreinte attendue uniquement après avoir confirmé la cible prévue.
Des enregistrements de migration inconnus sont présents. Ne supprimez pas les enregistrements et ne relancez pas apply. Confirmez que l’artefact de l’application est la version prévue et recherchez si un build plus récent ou divergent a migré la base de données.
Un résultat d’écriture D1 est ambigu. Ne rejouez pas la commande de migration. Exécutez emdash migrate --status contre le même compte et UUID de base de données, inspectez le résultat et escaladez si la migration s’est arrêtée en cours de route.
Hyperdrive ne peut pas se connecter. Testez l’accessibilité depuis le runner de déploiement vers l’origine PostgreSQL et vérifiez la variable direct-origin. La connectivité Worker-vers-Hyperdrive ne prouve pas que le runner peut atteindre l’origine.