Evolvere lo schema di un sito distribuito

EmDash memorizza collezioni, campi e tassonomie nel database accanto al contenuto. Usa questa guida per modificare il modello di contenuto in produzione senza confonderlo con un deploy del codice, un seeding iniziale o una migrazione core di EmDash. Gli esempi usano Cloudflare D1; la stessa separazione si applica a ogni adattatore di database.

Cosa cambia cosa

Un sito attraversa quattro workflow distinti. Ognuno tocca un livello diverso:

Workflow	Cosa cambia	Come
Modifica contenuto	Voci, media, impostazioni	Pannello admin o API dei contenuti
Deploy del codice	Template, config, versione EmDash	`wrangler deploy` — può migrare le tabelle DB gestite da EmDash
Bootstrap iniziale	Tutto, da zero	Migrazioni + file seed + procedura guidata, automatico al primo avvio
Evoluzione dello schema	Collezioni, campi, tassonomie	Pannello admin o `emdash schema` contro il sito in produzione (questa pagina)

Il file seed partecipa solo alla terza riga. Viene applicato una volta, quando il database è vuoto e la procedura guidata non è stata completata. Distribuire un file seed modificato contro un database esistente non fa nulla — evolvere lo schema di un sito in produzione avviene sempre attraverso il pannello admin o l’API.

Modificare lo schema nel pannello admin

Il pannello admin è il modo principale per evolvere un sito distribuito. Apri Content Types nell’admin e aggiungi, modifica o rimuovi collezioni e campi. Le modifiche hanno effetto immediato — l’API dei contenuti, il loader e l’interfaccia di modifica leggono tutti lo schema dal database a runtime.

Vedi Collezioni e campi per i tipi di campo disponibili, le regole di validazione e le opzioni dei widget.

Dopo aver modificato lo schema, rigenera i tipi TypeScript usati dai tuoi template. Il comando emdash types legge lo schema da un’istanza in esecuzione, quindi può puntare direttamente al sito distribuito:

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

Modificare lo schema dalla CLI

I comandi emdash schema comunicano con un’istanza in esecuzione tramite la sua API REST, quindi funzionano contro un sito distribuito allo stesso modo del dev locale. Autenticati una volta con il flusso dispositivo:

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

In alternativa, crea un token API nell’admin sotto Impostazioni → Token API e passalo con --token o la variabile d’ambiente EMDASH_TOKEN — utile per la CI.

Poi evolvi lo schema con gli stessi comandi che useresti localmente:

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

Questi comandi possono essere registrati in uno script affinché ogni ambiente riceva lo stesso cambiamento ordinato. I comandi non sono automaticamente idempotenti: rieseguire create o add-field contro un oggetto già esistente può fallire. Ispeziona il target con emdash schema list o get, registra quale ambiente ha completato ogni passo e fermati al primo errore.

Vedi il riferimento CLI per l’elenco completo dei comandi.

Mantenere il file seed sincronizzato

Il file seed incorporato nel tuo build determina con cosa si inizializza un database nuovo: un nuovo ambiente di preview, una ricostruzione di disaster recovery o un secondo deployment dello stesso sito. Se il seed descrive ancora il blog di avvio mentre la produzione si è evoluta in qualcos’altro, ogni ambiente nuovo si inizializza con il modello sbagliato.

Il build incorpora il primo file seed trovato in .emdash/seed.json, il percorso in package.json#emdash.seed o seed/seed.json. Se nessuno è presente, viene incorporato un seed predefinito integrato (il modello del blog di avvio) e astro dev registra un avviso.

Dopo aver evoluto lo schema di un sito distribuito, esporta il modello in produzione nel tuo repository. emdash export-seed legge un file SQLite locale e wrangler d1 export ne produce uno dal database D1 distribuito:

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

Il seed esportato contiene le impostazioni, collezioni, tassonomie, menu, redirect, aree widget e sezioni del sito in produzione. Aggiungi --with-content per includere le voci. Fai commit del .emdash/seed.json aggiornato insieme al codice che dipende dal nuovo schema, così un ambiente nuovo si inizializza sempre con un modello che il codice comprende.

Provare le modifiche su un ambiente di preview

Una modifica distruttiva dello schema (rimuovere un campo, ristrutturare una collezione) è più sicura se provata contro una copia usa e getta della produzione.

Crea un database D1 di preview separato e lascia che Wrangler lo aggiunga all’ambiente preview:
```
npx wrangler d1 create emdash-db-preview \
  --binding DB --env preview --update-config
```
Conferma che env.preview.d1_databases contenga il nuovo nome del database e l’UUID. I binding non vengono ereditati dalla configurazione Wrangler di livello superiore.

Esporta la produzione, poi importa l’SQL attraverso il binding DB dell’ambiente di preview:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
npx wrangler d1 execute DB --env preview --remote --file=./prod.sql

Costruisci il progetto, distribuiscilo nell’ambiente di preview, poi esegui la modifica dello schema contro l’URL di preview:

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

Verifica le pagine pubbliche, i formulari admin, i tipi generati e qualsiasi template che legge i campi modificati. Fai un backup fresco del database di produzione, poi esegui gli stessi comandi una volta contro la produzione.

Recuperare da un errore

Un campo è stato rimosso per errore. La colonna e i suoi dati sono spariti dal database in produzione. Ripristina da un punto di backup D1 Time Travel, oppure riaggiungi il campo e ripristina i suoi valori da un precedente wrangler d1 export.
Un ambiente nuovo si è inizializzato con il modello sbagliato. Il seed incorporato era obsoleto o mancante. Aggiorna .emdash/seed.json (vedi Mantenere il file seed sincronizzato), ricostruisci e punta il deploy a un database vuoto per reinizializzare.
Lo schema e i template non concordano. I deploy e le modifiche dello schema sono indipendenti, quindi ordinali deliberatamente: le modifiche additive dello schema (nuova collezione, nuovo campo opzionale) prima, poi il codice che li usa. Per le rimozioni, distribuisci prima il codice che smette di usare il campo, poi rimuovi il campo.