Gestire le migrazioni del database del core

Le migrazioni del core di EmDash aggiornano le tabelle proprie di EmDash e le colonne standard nelle tabelle di contenuto. Non creano, rimuovono o rinominano le vostre collezioni e campi; consultate Evolving a Deployed Site per le modifiche al modello di contenuto.

La modalità di migrazione a runtime è auto per impostazione predefinita, quindi i deploy esistenti continuano ad applicare le migrazioni del core in sospeso all’avvio. Le migrazioni gestite dal deploy consentono a un build di migrare il suo database prima che il nuovo codice applicativo riceva traffico, e poi consentono al runtime di verificare o fidarsi di quel passaggio di deploy.

Build, migrate, deploy, check

Un build o sync di Astro scrive .emdash/migrations.json. Questo manifesto senza segreti registra la versione esatta di EmDash, l’insieme ordinato di migrazioni, la configurazione delle locale e l’esecutore di migrazioni dell’adapter utilizzato da quel build.

Eseguite questi comandi dal progetto le cui dipendenze hanno prodotto il manifesto. Prima compilate e ispezionate il target.

pnpm build
pnpm emdash migrate --status

Dopo aver confermato che il target riportato è il database previsto, avviate la migrazione interattiva. Rivedete il target nuovamente al prompt prima di confermare. Poi distribuite lo stesso build e verificate lo schema distribuito.

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

emdash migrate --status riporta migrazioni applicate, in sospeso e sconosciute senza modificare il database. Il comando semplice emdash migrate mostra il target e chiede conferma prima di applicare le migrazioni in sospeso.

--check non applica mai migrazioni e termina con codice diverso da zero quando ci sono migrazioni conosciute in sospeso o il database contiene record di migrazione sconosciuti al build. Usate --status quando volete ispezionare gli stessi set di migrazioni senza il codice di uscita diverso da zero “lavoro richiesto” di check. Il riferimento CLI distingue codici di uscita in sospeso, sconosciuti, di conferma, interruzione e operativi.

L’applicazione non interattiva e ogni applicazione con --json richiedono --expected-target-fingerprint; il comando fallisce se il target risolto non corrisponde. Usate queste opzioni nei job di deploy automatizzati, non per il workflow interattivo descritto sopra.

Usate --manifest path/to/migrations.json per un manifesto memorizzato altrove. Per investigazioni locali, --from-config [--config astro.config.mjs] valuta esplicitamente la configurazione di progetto affidabile senza eseguire hook di Astro o avviare un server. I pipeline di deploy dovrebbero consumare il manifesto del build.

Selezionare il database esplicitamente

L’adapter configurato contribuisce informazioni di target senza segreti al manifesto. Le credenziali rimangono nelle variabili d’ambiente e vengono lette solo dal comando di migrazione.

Adapter	Target del manifesto	Variabile credenziali predefinita	Override utile
SQLite	Percorso del database o URL `file:`	—	`--database <percorso>`
libSQL	URL pubblica	`TURSO_AUTH_TOKEN`	Configurare `migrationAuthTokenEnv`
PostgreSQL	Nome della variabile di connessione	`DATABASE_URL`	`--database-url-env <nome>`
Cloudflare D1	Nome del binding Wrangler	`CLOUDFLARE_API_TOKEN`	`--d1`, `--account-id`, `--wrangler-config`, `--wrangler-env`
Hyperdrive	Nome del binding primario e della variabile di origine	Variabile direct-origin specifica del binding	Configurare `migrationConnectionStringEnv`

I percorsi SQLite relativi vengono risolti dalla radice del progetto, non dal pacchetto EmDash installato o dalla sottodirectory corrente della shell. Le etichette di target PostgreSQL, libSQL e Hyperdrive omettono credenziali e parametri URL.

Provisioning di D1 prima della migrazione

Creare un database D1 e migrare il suo schema sono operazioni separate. emdash migrate non crea mai un database mancante.

Provvisionare il database e registrare il suo UUID di produzione.
```
pnpm wrangler d1 create my-site-production
```
Aggiungere quell’UUID al binding e all’ambiente previsti in wrangler.jsonc.
Compilare il sito in modo che il binding D1 venga registrato in .emdash/migrations.json.

Impostare l’ID account e un token con permesso di modifica D1. Ispezionare il target selezionato, poi eseguire la migrazione interattiva. Confermare il prompt solo quando account e database corrispondono al database di produzione previsto.

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

In alternativa potete fornire --account-id con --d1 <uuid-o-nome-database>. La ricerca per nome deve risolvere esattamente un database. ID di anteprima, ID segnaposto, account in conflitto e binding ambigui falliscono in modo chiuso.

Configurare le migrazioni D1 in CI

D1 non fornisce il blocco di migrazione consultivo usato da PostgreSQL. Eseguite al massimo un job di migrazione per account e UUID di database.

Impostate i seguenti segreti e variabili nell’ambiente CI:

Segreto CLOUDFLARE_API_TOKEN: un token con permesso di modifica D1.
Variabile CLOUDFLARE_ACCOUNT_ID: l’ID account Cloudflare proprietario del database.
Variabile D1_DATABASE_ID: l’UUID del database D1 di produzione.
Variabile EMDASH_TARGET_FINGERPRINT: l’impronta digitale stampata da emdash migrate --status dopo aver verificato account e database localmente.

Il seguente workflow GitHub Actions utilizza questi valori e vincola il gruppo di concorrenza a entrambi gli identificatori immutabili di D1. Il suo passaggio di applicazione è non interattivo, quindi fornisce esplicitamente l’impronta digitale del target verificato.

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 }}"

Aggiornate EMDASH_TARGET_FINGERPRINT solo dopo aver verificato un target modificato localmente. L’impronta digitale non contiene credenziali, ma cambiarla senza verificare account e database rimuove la protezione contro la migrazione del database sbagliato.

Hyperdrive si connette all’origine

L’esecutore di migrazioni di Hyperdrive apre una connessione PostgreSQL diretta all’origine. Non invia traffico di migrazione attraverso Hyperdrive, non usa il binding cachato opzionale e non eredita l’accessibilità di rete privata dal Worker.

Il runner di deploy deve poter raggiungere l’origine. Impostate migrationConnectionStringEnv su hyperdrive() quando la variabile specifica del binding predefinita è inadatta, e fornite quella variabile solo al job di migrazione. Mantenete separate le credenziali Hyperdrive di runtime e le credenziali di deploy direct-origin.

Adottare l’applicazione a runtime gradualmente

La seguente configurazione di integrazione EmDash abilita l’applicazione a runtime mantenendo le migrazioni automatiche in sviluppo.

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

auto è il valore predefinito retrocompatibile. Il runtime all’avvio controlla e applica le migrazioni in sospeso.
check esegue una query di stato direzionale e restituisce 503 prima di servire una richiesta quando ci sono migrazioni conosciute in sospeso. Tollera record da un build compatibile più recente durante un deploy progressivo.
manual non esegue migrazioni né query di stato a runtime. Usatelo solo dopo che il pipeline di deploy applica e verifica ogni build in modo affidabile.

EMDASH_MIGRATIONS_MODE può sovrascrivere la modalità a runtime quando lo stesso artefatto viene promosso attraverso più ambienti. Le route di bypass di configurazione e sviluppo obbediscono alla modalità effettiva; non possono migrare silenziosamente dietro check o manual.

Un rollout conservativo è auto durante l’introduzione del job di deploy, poi check dopo che il job è affidabile, poi manual quando un controllo esterno è imposto per ogni deploy.

Compatibilità durante i deploy progressivi

Le migrazioni del core seguono il sequenziamento expand/deploy/contract. Un deploy può temporaneamente eseguire isolati di applicazione vecchi e nuovi contro il database espanso, e un backfill può essere ancora in corso. Non contraete uno schema fino a quando ogni versione distribuita non ha smesso di utilizzarlo.

I record di migrazione applicati sconosciuti sono tollerati dal check a runtime solo per questa direzione di deploy progressivo. Il controllo esatto della CLI li segnala e apply rifiuta la mutazione, perché il database potrebbe essere più recente o avere una storia di migrazione divergente.

Risoluzione dei problemi

Nessun manifesto di migrazione trovato. Compilate o sincronizzate prima il progetto. Usate --manifest per una posizione di artefatto non standard o scegliete esplicitamente --from-config per investigazioni locali.
L’artefatto non corrisponde all’EmDash del progetto. Ricompilate e distribuite applicazione e manifesto insieme. Eseguite la CLI del progetto invece di un’installazione globale.
Il target è mancante o ambiguo. Provvisionatelo prima, poi fornite un percorso di database esplicito, nome di variabile di connessione, selettore D1 o configurazione e ambiente Wrangler selezionati. EmDash non indovina da variabili d’ambiente o binding non correlati.
L’impronta digitale del target è cambiata. Fermatevi e verificate account, ambiente, nome del database, UUID o percorso mostrati. Aggiornate l’impronta digitale attesa solo dopo aver confermato il target previsto.
Sono presenti record di migrazione sconosciuti. Non cancellate i record e non rieseguite apply. Confermate che l’artefatto dell’applicazione è la versione prevista e investigate se un build più recente o divergente ha migrato il database.
Un risultato di scrittura D1 è ambiguo. Non ripetete il comando di migrazione. Eseguite emdash migrate --status contro lo stesso account e UUID di database, ispezionate il risultato ed escalate se la migrazione si è fermata a metà.
Hyperdrive non riesce a connettersi. Testate la raggiungibilità dal runner di deploy all’origine PostgreSQL e verificate la variabile direct-origin. La connettività Worker-verso-Hyperdrive non prova che il runner possa raggiungere l’origine.