Aghjurnà senza interruzzione

E regule si trovanu in a sezzione 7 di docs/architecture/23-ops.md è in a sezzione 4.1 di docs/architecture/07-data.md. Eccu a prucedura.

A garanzia chì rende sicuru l’aghjurnamentu

A versione R funziona currettamente cù u schema R è u schema R menu unu. Ogni cambiamentu di schema hè spartutu in espansione, transizione è cuntrazione:

1. Espansione: aghjunghje a nova culonna, tavula o indice. U codice vechju ùn ne tene contu.
2. Transizione, per almenu una versione: u codice novu scrive e duie forme è leghje a nova; un travagliu ripigliabile riempie i filari vechji.
3. Cuntrazione: sguassà a forma vechja, in una versione dopu, da sola.

Cusì in ogni mumentu d’un aghjurnamentu progressivu, i prucessi vechji è novi ponu sparte una basa di dati. Ùn ci sò micca migrazioni di ritornu: una migrazione chì hà sguassatu una culonna un’ora fà ùn pò restituisce i filari scritti in quell’ora.

U travagliu CI schema-compat verifica sta garanzia à ogni versione eseguendu i testi di a versione precedente contr’à u schema novu.

Nanzu di principià

1. Leghjite e note di versione. Una versione chì hà bisognu d’una finestra di mantenimentu l’indica, cù a stima; à u più una per versione.
2. Eseguite a prova generale di risturazione, o cunfirmate ch’ella hè passata per sta versione (backup-restore.md). Una prova fallita impedisce l’ aghjurnamentu.
3. Fate una copia di salvezza di basa: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, un host

export QUIRE_RELEASE=2026.10.0            # or set it in docker/.env
docker compose -f docker/compose.yaml pull   # or build
docker compose -f docker/compose.yaml run --rm migrate
docker compose -f docker/compose.yaml up -d --no-deps web content collab
docker compose -f docker/compose.yaml up -d --no-deps worker scheduler

L’ordine hè intenzionale:

1. Migrà prima, mentre a versione vechja serve u trafficu. E migrazioni d’espansione ùn li sò visibili.
2. Dopu u nivellu web. À SIGTERM ogni prucessu web mette /readyz à draining, compie e dumande in corsu in 30 seconde, chjude i flussi cù una indicazione di ricunnessione, è esce. stop_grace_period hè 40 seconde cusì Compose ùn interrompe mai una chjusura sana.
3. I worker à a fine, affinchì a forma nova di l’avvenimentu sia prodotta prima chì u novu cunsumatore l’aspetti. I worker smettenu subitu di piglià travagli è anu 120 seconde; un travagliu chì ùn si pò compie hè ripigliatu in un altru locu, ciò chì hè sicuru perchè ogni travagliu hè idempotente. U scheduler cede a direzzione à a so prossima battuta.

Nant’à un host, Compose rimpiazza ogni cuntainer à turnu, dunque ci hè una corta interruzzione per serviziu. Per ùn avè nisuna interruzzione, eseguite u nivellu web cum’è dui cuntainer daretu à u vostru proxy (un schedariu di override chì aghjusta un secondu serviziu web senza portu publicatu), è ricreate li unu à volta, aspettendu chì ognunu indichi ch’ellu hè sanu prima di passà à u prossimu.

Parechji host o un orchestratore

Aduprate u listessu ordine: migrà una volta da un travagliu unicu, dopu aghjurnà u nivellu web cù un surplus di unu è zero indisponibili, dopu i worker. Puntate e sonde di prontezza à /readyz è quelle di salute à /healthz.

Cù basi di dati dedicate à tenant, u passu migrate face tramindui: migra prima a basa di cuntrollu, dopu ogni basa elencata in ops.tenant_database, una per volta, ognuna cù u so propiu serrame. Un fallimentu in una basa di tenant ùn impedisce micca l’altre. Quandu tutte e basi sò pronte, paraguneghja i registri di migrazione è esce cù un codice micca zeru à menu chì ogni basa abbia applicatu esattamente e stesse migrazioni chè a basa di cuntrollu, indicendu ognuna chì hè in ritardu o in anticipu. U listessu cumandu installa e tavule di fila in ogni basa, perchè u worker cunsuma i travagli di un tenant fissatu in u locu induve sò stati scritti.

bun apps/worker/src/migrate.ts   # what the Compose step runs
bun run db:migrate:all                            # the same, from a checkout

A migrazione nurmale è a prima installazione mettenu dinù i ducumenti ghjuridichi inglesi canonichi di l’operatore Quire in ops.platform_policy_version. L’installatore hè idempotente: solu i testi inglesi mancanti è i testi provvisori sementati da a migrazione sò rimpiazzati. E sementi sò archiviate è una nova versione publicata hè aghjunta; i riferimenti storichi d’accettazione è i testi fermanu. Ogni versione scritta da l’operatore, ancu una bozza, hè cunservata è deve esse gestita da a console Pulitiche di a piattaforma. I ducumenti, e versione è u cunsensu di e pulitiche di i tenant ùn cambianu mai cù stu passaghju. Hè a publicazione di u testu di l’operatore, micca una certificazione ghjuridica nè l’esecuzione automatica di e so prumesse.

Ogni basa dedicata hè accessuta per mezu di u nome cù u quale hè registrata. Una basa registrata cum’è env:QUIRE_DB_NORTHWIND_URL hà bisognu di:

Una basa registrata senza cunnessione _MIGRATOR hè signalata cum’è fallimentu, mai saltata. U nivellu web pò esse aghjurnatu una volta chì a basa di cuntrollu hè pronta. Una basa di tenant in ritardu d’un’ora avverte; d’un ghjornu manda una alerta urgente.

pgvector

Da a migrazione 0264, u corpus di fundamentazione usa un indice HNSW di pgvector induve u servitore hà l’estensione; u serviziu Compose postgres hè custruitu cù ella (docker/postgres.Dockerfile). U primu migrate dopu à cambià l’imagine crea l’estensione via l’inizializazione di superuser, è dopu 0264 aghjusta una culonna vettoriale generata è custruisce l’indice. L’aghjunta di a culonna riscrive app.ai_chunk una volta sottu à un serrame esclusivu, dunque e dumande di fundamentazione aspettanu; nunda altru tocca quella tavula.

Nant’à un servitore senza pgvector, 0264 scrive un avvisu è ùn cambia nunda, è u recuperu ferma esattu. Cù una versione di pgvector più vechja chè 0.8, a culonna è l’indice sò creati ma u recuperu ferma esattu finu à aghjurnà l’estensione (alter extension vector update), perchè e ricerche HNSW filtrate anu bisognu di e ricerche iterative di 0.8. Per attivà la dopu nant’à un servitore senza ella, installate l’ estensione, rieseguite l’inizializazione (o create extension vector cum’è superuser), dopu cum’è quire_migrator:

set maintenance_work_mem = '1GB';  -- the HNSW build is much faster in memory
select ops.ai_chunk_enable_vector_index();

Hè idempotente è restituisce enabled o unavailable. Eseguite lu ancu nant’à ogni basa di dati dedicata à tenant.

Ritornu à a versione precedente

U ritornu di codice hè sempre pussibule: stabilite QUIRE_RELEASE à a etichetta precedente è eseguite torna up -d. Funziona perchè u schema hè cumpatibile in e duie direzzioni dentru una versione.

U ritornu di schema ùn hè micca prupostu. Ciò chì ùn si pò annullà, è cumu ricuperà ne:

Hè per quessa chì una migrazione di cuntrazione hè distribuita sola: una risturazione hà tandu una fruntiera chjara.

Verificà l’aghjurnamentu

docker compose -f docker/compose.yaml ps           # every service healthy
curl -fsS http://localhost:8080/readyz             # ready, and what is configured
docker compose -f docker/compose.yaml logs migrate # the migrations applied