Evolvere lo schema di un sito distribuito

EmDash memorizza collezioni, campi e tassonomie nel database accanto ai contenuti. Usa questa guida per modificare quel modello di contenuto in produzione senza confonderlo con una distribuzione del codice, un seed iniziale o una migrazione del core di EmDash. Gli esempi usano Cloudflare D1; la stessa separazione vale per ogni adattatore di database.

Cosa cambia cosa

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

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

Il file seed partecipa solo alla terza riga. Il suo schema e la sua struttura vengono applicati una sola volta, alla prima richiesta prima che la procedura guidata di configurazione sia stata completata. Distribuire un file seed modificato su un database esistente non fa nulla: l’evoluzione dello schema di un sito in produzione avviene sempre tramite il pannello admin o l’API.

Modificare lo schema nel pannello admin

Il pannello admin è il modo principale per far evolvere un sito distribuito. Apri Content Types nell’amministrazione 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.

Consulta 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 su un sito distribuito allo stesso modo in cui funzionano nello sviluppo locale. Autenticati una volta con il device flow:

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

In alternativa, crea un token API nell’amministrazione in Settings → API Tokens e passalo con --token o con la variabile d’ambiente EMDASH_TOKEN, utile per la CI.

Poi fai evolvere lo schema con gli stessi comandi che useresti in locale:

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 inseriti in uno script, così ogni ambiente riceve la stessa modifica ordinata. I comandi non sono automaticamente idempotenti: rieseguire create o add-field su un oggetto già esistente può fallire. Ispeziona la destinazione con emdash schema list o get, annota quale ambiente ha completato ogni passaggio e fermati al primo errore.

Consulta il riferimento della CLI per l’elenco completo dei comandi.

Mantenere sincronizzato il file seed

Il file seed incorporato nella tua build determina con cosa viene inizializzato un database nuovo: un nuovo ambiente di preview, una ricostruzione per disaster recovery o una seconda distribuzione dello stesso sito. Se il seed descrive ancora il blog iniziale mentre la produzione si è evoluta in qualcos’altro, ogni nuovo ambiente esegue il bootstrap con il modello sbagliato.

La build incorpora il primo file seed trovato in .emdash/seed.json, nel percorso indicato in package.json#emdash.seed o in seed/seed.json. Se non ce n’è nessuno, viene incorporato un seed predefinito integrato (il modello del blog iniziale) e astro dev registra un avviso.

Dopo aver fatto evolvere lo schema di un sito distribuito, riesporta il modello in produzione nel tuo repository. emdash export-seed legge un file SQLite locale. Crea i file SQL come descritto in Creare un dump D1 offsite, carica le tabelle e le righe in un database locale ed esporta il 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

Il seed esportato contiene le impostazioni, le collezioni, le tassonomie, i menu, i reindirizzamenti, le aree widget e le sezioni del sito in produzione. Aggiungi --with-content per includere le voci. Fai il commit del .emdash/seed.json aggiornato insieme al codice che dipende dal nuovo schema, così un nuovo ambiente esegue sempre il bootstrap 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ù sicuro provarla su 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
```
Verifica che env.preview.d1_databases contenga il nome e l’UUID del nuovo database. I binding non vengono ereditati dalla configurazione Wrangler di primo livello.

Crea i file SQL dalla produzione come descritto in Creare un dump D1 offsite, poi importali in ordine tramite il binding DB dell’ambiente di preview:

npx wrangler d1 execute DB --env preview --remote --file=./backup-schema.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-folders.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-data.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-indexes.sql

Il sito di preview ricostruisce il proprio indice di ricerca alla prima chiamata all’API di ricerca, come descritto in quella sezione.

Compila il progetto, distribuiscilo nell’ambiente di preview, poi esegui la modifica dello schema sull’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 moduli dell’amministrazione, i tipi generati e qualsiasi template che legga i campi modificati. Esegui un nuovo backup del database di produzione, poi esegui una sola volta gli stessi comandi sulla 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 backup a un punto nel tempo di D1 con Time Travel, oppure aggiungi di nuovo il campo e ripristina i suoi valori da un dump D1 offsite precedente.
Un nuovo ambiente ha eseguito il bootstrap con il modello sbagliato. Il seed incorporato era obsoleto o mancante. Aggiorna .emdash/seed.json (consulta Mantenere sincronizzato il file seed), ricompila e punta la distribuzione a un database vuoto per rieseguire il bootstrap.
Lo schema e i template non coincidono. Le distribuzioni e le modifiche dello schema sono indipendenti, quindi ordinale con cura: le modifiche additive dello schema (nuova collezione, nuovo campo facoltativo) vengono prima, poi il codice che le usa. Per le rimozioni, distribuisci prima il codice che smette di usare il campo, poi rimuovi il campo.