Runbook: migrazione D1

Quando usarlo

Usare questo runbook quando uno o più file in migrations/ devono essere applicati al D1 di sviluppo o produzione. Non usarlo per riparazioni SQL improvvisate.

Prerequisiti

Issue operativo che nomina ambiente e migrazioni;
SHA esatto con CI verde;
file pending ispezionati e compatibilità valutata;
nessun'altra operazione sullo stesso D1;
backup o strategia di recupero richiesti dall'Issue;
API e Frontend non inclusi nello stesso run.

Procedura

Elencare le migrazioni pending:

npx wrangler d1 migrations list DB --env <AMBIENTE> --remote

Confrontare l'elenco con l'Issue; fermarsi su differenze.
Eseguire il preflight dell'ambiente.
Ottenere il go/no-go specifico per D1.
In sviluppo selezionare migrate-api-d1 con MIGRATE_DEVELOPMENT_API_D1.
In produzione selezionare migrate-d1 con MIGRATE_PRODUCTION_D1.
Attendere il run terminale.
Rileggere l'elenco pending e verificare gli invarianti in sola lettura.
Solo dopo successo autorevole valutare un deployment separato.

Verifiche attese

sono state applicate soltanto le migrazioni autorizzate;
la storia migrazioni è coerente;
gli invarianti e le letture rappresentative passano;
API e Frontend non sono stati distribuiti;
non sono avvenute scritture editoriali di prova.

Condizioni di stop

Fermarsi se il numero o l'ordine dei file differisce, lo schema atteso non coincide, il run fallisce, l'evidenza è ambigua, le letture non passano o una correzione richiede SQL fuori migrazione.

Rollback o recupero

Non usare il rollback Worker per correggere D1. Conservare l'ambiente fail-closed e creare una migrazione forward correttiva in un nuovo Issue. Un ripristino dati richiede una procedura e un'autorizzazione dedicate.

Evidenza da conservare

SHA e ambiente;
elenco pending prima e dopo;
nomi dei file applicati;
run e risultato terminale;
verifiche degli invarianti;
conferma che nessun Worker è stato distribuito;
necessità o meno di recupero successivo.