Ĝisdatigi sen malfunkcio

La reguloj troviĝas en sekcio 7 de docs/architecture/23-ops.md kaj sekcio 4.1 de docs/architecture/07-data.md. Jen la proceduro.

La garantio kiu sekurigas la ĝisdatigon

Eldono R funkcias ĝuste kun skemo R kaj skemo R minus unu. Ĉiu skemoŝanĝo estas dividita en vastigon, transiron kaj kuntiron:

1. Vastigi: aldoni novan kolumnon, tabelon aŭ indekson. Malnova kodo ignoras ĝin.
2. Transiri, dum almenaŭ unu eldono: nova kodo skribas ambaŭ formojn kaj legas la novan; rekomencigebla tasko plenigas malnovajn vicojn.
3. Kuntiri: forigi la malnovan formon sola en posta eldono.

Do en ĉiu momento dum laŭpaŝa ĝisdatigo malnovaj kaj novaj procezoj povas kunhavi unu datumbazon. Ne ekzistas kontraŭmigroj: migrado foriginta kolumnon antaŭ unu horo ne povas redoni vicojn skribitajn dum tiu horo.

La CI-tasko schema-compat kontrolas la garantion ĉe ĉiu eldono, rulante testojn de la antaŭa eldono kontraŭ la nova skemo.

Antaŭ ol komenci

1. Legu la eldonajn notojn. Eldono postulanta prizorgan paŭzon tion diras kun takso; maksimume unu povas aperi por eldono.
2. Rulu la restarigan provon, aŭ konfirmu, ke ĝi sukcesis por ĉi tiu eldono (backup-restore.md). Malsukcesa provo blokas la ĝisdatigon.
3. Faru bazan sekurkopion: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose ĉe unu gastiganto

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

La ordo estas intenca:

1. Unue migri, dum la malnova eldono servas trafikon. Vastigaj migradoj estas nevideblaj por ĝi.
2. Poste retan tavolon. Ĉe SIGTERM ĉiu retprocezo ŝanĝas /readyz al draining, finas aktivajn petojn ene de 30 sekundoj, fermas fluojn kun indiko rekonekti kaj eliras. stop_grace_period estas 40 sekundoj por ke Compose neniam interrompu sanan ĉesigon.
3. Workers laste, por ke la plej nova formo de evento estu produktita antaŭ ol la plej nova ricevanto ĝin atendas. Workers ĉesas tuj preni taskojn kaj ricevas 120 sekundojn; tasko ne finita estas reprenata aliloke, sekure ĉar ĉiuj taskoj estas idempotentaj. La planilo transdonas gvidadon ĉe sia sekva intervalo.

Ĉe unu gastiganto Compose anstataŭigas ĉiun ujon laŭvice, do estas mallonga paŭzo por ĉiu servo. Por tute eviti paŭzon, rulu la retan tavolon kiel du ujojn malantaŭ via propra prokurilo (override-dosiero aldonanta duan retan servon sen publika pordo), kaj rekreu ilin unuope, atendante ĝis ĉiu raportas sanan staton antaŭ la sekva.

Pluraj gastigantoj aŭ orkestrilo

Uzu la saman ordon: migru unufoje per unuopa tasko, poste ruligu la retan tavolon kun superfluo unu kaj neatingeblaj nul, kaj laste la workers. Direktu preteco-sondilojn al /readyz kaj vivsondilojn al /healthz.

Kun dediĉitaj luantaj datumbazoj, la paŝo migrate faras ambaŭ: unue migras la kontrolan datumbazon, poste ĉiun datumbazon listigitan en ops.tenant_database, unuope sub ĝia propra ŝloso. Malsukceso en unu luanta datumbazo ne haltigas la ceterajn. Fininte ĉiujn, ĝi komparas la migradajn registrojn kaj eliras kun ne-nula stato krom se ĉiu datumbazo aplikis precize la samajn migradojn kiel la kontrola datumbazo; ĝi nomas ĉiun datumbazon malantaŭan aŭ antaŭan. La sama komando instalas atendovico-tabelojn en ĉiu datumbazo, ĉar worker konsumas taskojn de fiksita luanto tie, kie ili estis skribitaj.

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

Ĉiu dediĉita datumbazo estas atingata per sia registrita nomo. Datumbazo registrita kiel env:QUIRE_DB_NORTHWIND_URL bezonas:

Registrita datumbazo sen _MIGRATOR-konekto estas raportata kiel malsukceso, neniam preterlasata. La reta tavolo povas esti ruligata post la kontrola datumbazo. Luanta datumbazo malantaŭa je horo estigas averton; post tago ĝi paĝigas.

pgvector

Ekde migrado 0264 la grounding-korpuso uzas pgvector-HNSW-indekson kie la servilo havas la etendaĵon; la Compose-servo postgres estas konstruita kun ĝi (docker/postgres.Dockerfile). La unua migrate post ŝanĝo de imagoj kreas la etendaĵon per superuzanta bootstrap; poste 0264 aldonas generitan vektorkolumnon kaj konstruas la indekson. Aldono de kolumno reskribas app.ai_chunk unufoje sub ekskluziva ŝloso, do grounding-petoj atendas; nenio alia tuŝas tiun tabelon.

Ĉe servilo sen pgvector, 0264 registras rimarkon kaj faras nenian ŝanĝon; rehavigo restas preciza. Kun pgvector pli malnova ol 0.8 la kolumno kaj indekso estas konstruitaj sed rehavigo restas preciza ĝis ĝisdatigo de la etendaĵo (alter extension vector update), ĉar filtritaj HNSW-serĉoj bezonas la iteraciajn serĉojn de 0.8. Por aktivigi ĝin poste ĉe servilo sen ĝi, instalu la etendaĵon, rulu bootstrap denove (aŭ create extension vector kiel superuzanto), poste rulu kiel quire_migrator:

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

Ĝi estas idempotenta kaj redonas enabled aŭ unavailable. Rulu ĝin ankaŭ ĉe ĉiu dediĉita luanta datumbazo.

Reiri al antaŭa versio

Reiri al antaŭa kodo ĉiam eblas: agordu QUIRE_RELEASE al la antaŭa etikedo kaj rulu up -d denove. Tio funkcias ĉar la skemo estas kongrua ambaŭdirekte ene de eldono.

Reiro al antaŭa skemo ne estas ofertata. Jen kion oni ne povas malfari kaj kiel reakiri:

Tial kuntira migrado estas eldonata sola: restarigo tiam havas klaran limon.

Kontroli ĝisdatigon

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