Etenaldirik gabe bertsio-berritzea

Arauak docs/architecture/23-ops.md ataleko 7. atalean eta docs/architecture/07-data.md ataleko 4.1 atalean daude. Hau da prozedura.

Seguru egiten duen bermea

R bertsioa behar bezala exekutatzen da R eskemarekin eta R ken bat eskemarekin. Eskema-aldaketa bakoitza handitze, trantsizio eta kontratu fasetan banatzen da:

1. Handitzea: gehitu zutabe, taula edo indize berria. Kode zaharrak ez dio jaramonik egiten.
2. Trantsizioa, gutxienez bertsio batean: kode berriak bi datu-egiturak idazten ditu eta berria irakurtzen du; berrabiaraz daitekeen lan batek errenkada zaharrak betetzen ditu.
3. Kontratua: kendu egitura zaharra ondorengo bertsio batean, bakarrik.

Beraz, bertsio-berritze mailakatu baten une oro, prozesu zaharrek eta berriek datu-base bera parteka dezakete. Ez dago atzeranzko migraziorik: duela ordubete zutabe bat ezabatu zuen migrazio batek ezin ditu ordubete horretan idatzitako errenkadak itzuli.

schema-compat CI lanak bertsio bakoitzean egiaztatzen du bermea, aurreko bertsioaren probak eskema berriaren aurka exekutatuz.

Hasi aurretik

1. Irakurri bertsio-oharrak. Mantentze-leihoa behar duen bertsioak hala adierazten du, iraupenaren estimazioarekin; gehienez bat dago bertsio bakoitzeko.
2. Exekutatu leheneratze-proba, edo egiaztatu bertsio honetan berdez amaitu dela (backup-restore.md). Huts egindako probak bertsio-berritzea blokeatzen du.
3. Egin oinarrizko babeskopia: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, ostalari bakarra

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

Ordena nahita dago horrela:

1. Migratu lehenik, bertsio zaharrak trafikoa zerbitzatzen duen bitartean. Handitze-migrazioak ikusezinak dira harentzat.
2. Ondoren web-maila. SIGTERM jasotzean, web-prozesu bakoitzak /readyz egoera draining bihurtzen du, abian dauden eskaerak 30 segundoan amaitzen ditu, korronteak berriz konektatzeko iradokizunarekin ixten ditu, eta amaitu egiten da. stop_grace_period 40 segundo da, Composek drainatze osasuntsua ez mozteko.
3. Worker-ak azkenik, gertaera-egitura berriena sortu dadin kontsumitzaile berrienak espero aurretik. Worker-ek berehala uzten diote lan berriak hartzeari eta 120 segundo dituzte; amaitu ezin duten lana beste instantzia batek berriro hartzen du, lan bakoitza idempotentea baita. Scheduler-ak lidergoa hurrengo tick-ean uzten du.

Ostalari bakarrean, Composek edukiontzi bakoitza txandaka ordezkatzen du, eta zerbitzu bakoitzean tarte labur bat dago. Etenik batere ez izateko, exekutatu web-maila bi edukiontzitan zure proxyaren atzean (bigarren web-zerbitzua argitaratutako atakarik gabe gehitzen duen override fitxategi batekin), eta sortu berriro banan-banan, hurrengoa osasuntsu dagoela adierazi arte itxaronez.

Hainbat ostalari edo orkestratzaile bat

Erabili ordena bera: migratu behin lan bakar batetik, eguneratu web-maila igoera bat eta erabilgarri ez dagoen instantzia zero utzita, eta azkenik worker-ak. Zuzendu prestasun-zundak /readyz helbidera eta bizitasun-zundak /healthz helbidera.

Maizterren datu-base bereiziak badaude, migrate urratsak biak egiten ditu: lehenik kontrol-datu-basea migratzen du, eta ondoren ops.tenant_database zerrendako datu-base bakoitza, banan-banan eta bere blokeoarekin. Maizter baten datu-baseko akatsak ez ditu gainerakoak gelditzen. Datu-base guztiak amaitzean, migrazioen erregistroak alderatzen ditu eta zero ez den kodearekin amaitzen da kontrol-datu-baseak aplikatutako migrazio berak datu-base guztiek aplikatu ez badituzte; atzean edo aurreratuta dagoen bakoitza izendatzen du. Komando berak ilarako taulak instalatzen ditu datu-base bakoitzean, worker-ak finkatutako maizter baten lanak idatzi ziren datu-base berean kontsumitzen dituelako.

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

Migrazio arruntak eta lehen exekuzioko konfigurazioak Quire operadorearen ingelesezko lege-dokumentu kanonikoak ere instalatzen dituzte ops.platform_policy_version atalean. Instalatzailea idempotentea da: falta diren ingelesezko testuak eta migrazioak ereindako behin-behineko testu zehatzak baino ez dira ordezkatzen. Haziak artxibatu egiten dira eta argitaratutako bertsio berri bat txertatzen da; onarpen-erreferentzia historikoak eta testuak gorde egiten dira. Operadoreak benetan idatzitako edozein bertsio, zirriborroa barne, gorde egiten da eta plataformaren Politiken kontsolatik kudeatu behar da. Maizterraren politika-dokumentuak, bertsioak eta adostasuna ez dira inoiz aldatzen trantsizio honekin. Hau operadore-testua argitaratzea da, ez ziurtagiri juridikoa ez eta haren promesen betetze automatikoa.

Datu-base bereizi bakoitza erregistratuta dagoen izenaren bidez atzitzen da. env:QUIRE_DB_NORTHWIND_URL gisa erregistratutako datu-base batek hau behar du:

_MIGRATOR konexiorik gabeko datu-base erregistratu bat akats gisa jakinarazten da, ez da inoiz saltatzen. Web-maila kontrol-datu-basea prest dagoenean eguneratu daiteke. Ordubetez atzeratutako maizter-datu-base batek abisua sortzen du; egun batez atzeratzen bada, alerta bidaltzen da.

pgvector

0264 migrazioaz geroztik, oinarritze-korpusak pgvector HNSW indizea erabiltzen du, zerbitzariak hedapena badu; Composeko postgres zerbitzua harekin eraikitzen da (docker/postgres.Dockerfile). Irudiak aldatu ondorengo lehen migrate exekuzioak hedapena sortzen du supererabiltzailearen abio-prozesuaren bidez; ondoren, 0264 migrazioak sortutako bektore-zutabea gehitzen du eta indizea eraikitzen du. Zutabea gehitzeak app.ai_chunk behin berridazten du blokeo esklusibo baten pean, beraz oinarritze-eskaerek itxaron behar dute; beste ezerk ez du taula ukitzen.

pgvector ez duen zerbitzari batean, 0264k ohar bat erregistratzen du eta ez du ezer aldatzen; berreskuratzeak zehatza izaten jarraitzen du. 0.8 baino zaharragoa den pgvector batean, zutabea eta indizea eraikitzen dira, baina berreskuratzeak zehatza izaten jarraitzen du hedapena eguneratu arte (alter extension vector update), iragazitako HNSW eskaneatzeek 0.8ren eskaneatze iteratiboak behar baitituzte. Geroago pgvector gabeko zerbitzari batean aktibatzeko, instalatu hedapena, exekutatu berriro abio-prozesua (edo create extension vector supererabiltzaile gisa), eta ondoren, quire_migrator gisa:

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

Idempotentea da, eta enabled edo unavailable itzultzen du. Exekutatu maizterren datu-base bereizi bakoitzean ere.

Atzera egitea

Kodea aurreko bertsiora itzultzea beti dago erabilgarri: ezarri QUIRE_RELEASE aurreko etiketara eta exekutatu up -d berriro. Eskemak bertsio beraren barruan bi noranzkoetan bateragarriak dira.

Eskema lehengoratzea ez dago eskaintzen. Hauek dira desegin ezin direnak eta berreskuratzeko moduak:

Horregatik argitaratzen da kontratu-migrazio bat bakarrik: leheneratzeak muga garbia izan dezan.

Bertsio-berritzea egiaztatzea

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