Opgradeer sonder stilstand

Die reëls staan in afdeling 7 van docs/architecture/23-ops.md en afdeling 4.1 van docs/architecture/07-data.md. Dit is die prosedure.

Die waarborg wat dit veilig maak

Vrystelling R loop korrek teen skema R en skema R minus een. Elke skemaverandering word in uitbreiding, oorgang en kontrak verdeel:

1. Uitbreiding: voeg die nuwe kolom, tabel of indeks by. Ou kode ignoreer dit.
2. Oorgang, vir minstens een vrystelling: nuwe kode skryf albei vorms en lees die nuwe een; ’n hervatbare taak vul ou rye terug.
3. Kontrak: verwyder die ou vorm alleen in ’n latere vrystelling.

Dus kan ou en nuwe prosesse tydens elke rollende opgradering een databasis deel. Daar is geen afgraderingsmigrasies nie: ’n migrasie wat ’n uur gelede ’n kolom verwyder het, kan nie die rye teruggee wat in daardie uur geskryf is nie.

Die schema-compat-CI-taak kontroleer die waarborg met elke vrystelling deur die vorige vrystelling se toetse teen die nuwe skema uit te voer.

Voordat jy begin

1. Lees die vrystellingnotas. ’n Vrystelling wat ’n instandhoudingsvenster nodig het, sê dit en gee ’n skatting; hoogstens een per vrystelling.
2. Voer die hersteltoets uit, of bevestig dat dit vir hierdie vrystelling groen was (backup-restore.md). ’n Mislukte toets blokkeer die opgradering.
3. Maak ’n basisrugsteun. docker compose -f docker/compose.yaml --profile backup run --rm backup

Docker Compose, een gasheer

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

Die volgorde is doelbewus:

1. Migreer eerste, terwyl die ou vrystelling verkeer bedien. Uitbreidingsmigrasies is vir dié weergawe onsigbaar.
2. Webvlak daarna. By SIGTERM stel elke webproses /readyz op draining, voltooi versoeke wat reeds loop binne 30 sekondes, sluit strome met ’n herverbindingwenk en sluit af. stop_grace_period is 40 sekondes sodat Compose nooit ’n gesonde afvoer afsny nie.
3. Werkers laaste, sodat die nuutste gebeurtenisvorm geproduseer word voordat die nuutste verbruiker dit verwag. Werkers hou dadelik op om nuwe take te haal en kry 120 sekondes; ’n taak wat nie kan klaarmaak nie, word elders weer gehaal. Dit is veilig omdat elke taak idempotent is. Die skeduleerder dra leierskap by sy volgende tik oor.

Op een gasheer vervang Compose elke houer om die beurt, dus is daar ’n kort gaping per diens. Vir geen gaping nie, laat die webvlak as twee houers agter jou eie instaanbediener loop (’n oorheersingslêer voeg ’n tweede webdiens sonder gepubliseerde poort by) en herskep hulle een op ’n slag; wag dat elkeen gesond rapporteer voor die volgende.

Verskeie gashere of ’n orkestreerder

Gebruik dieselfde volgorde: migreer een keer met ’n enkele taak, rol dan die webvlak oor met surge een en unavailable zero, daarna die werkers. Rig gereedheidsondersoeke na /readyz en lewendigheidsondersoeke na /healthz.

Met toegewyde tenant-databasisse doen die migrate-stap albei: dit migreer eers die beheerdatabasis en dan elke databasis in ops.tenant_database, een op ’n slag en elk onder sy eie slot. ’n Mislukking in een tenant-databasis stop nie die ander nie. Wanneer elke databasis klaar is, vergelyk dit migrasielogboeke en eindig met ’n nie-nul-status tensy elke databasis presies dieselfde migrasies as die beheerdatabasis toegepas het; dit benoem elkeen wat agter of voor is. Dieselfde opdrag installeer die tou-tabelle in elke databasis, want die werker verbruik ’n vasgepende tenant se take waar hulle geskryf is.

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

Elke toegewyde databasis word bereik met die naam waaronder dit geregistreer is. ’n Databasis geregistreer as env:QUIRE_DB_NORTHWIND_URL benodig:

’n Geregistreerde databasis sonder ’n _MIGRATOR-verbinding word as ’n mislukking gerapporteer, nooit oorgeslaan nie. Die webvlak kan gerol word sodra die beheerdatabasis klaar is. ’n Tenant-databasis wat ’n uur agter is, gee ’n waarskuwing; ná ’n dag word ’n alarm gestuur.

pgvector

Vanaf migrasie 0264 gebruik die grondingskorpus ’n pgvector-HNSW-indeks waar die bediener die uitbreiding het; die Compose-postgres-diens is daarmee gebou (docker/postgres.Dockerfile). Die eerste migrate ná beeldwisseling skep die uitbreiding deur die superuser-aanvangsopstelling, en 0264 voeg dan ’n gegenereerde vektorkolom by en bou die indeks. Die kolombyvoeging herskryf app.ai_chunk een keer onder ’n eksklusiewe slot, dus wag grondingsversoeke daarvoor; niks anders raak daardie tabel nie.

Op ’n bediener sonder pgvector teken 0264 ’n kennisgewing aan en verander niks; herwinning bly presies. Met ’n pgvector ouer as 0.8 word kolom en indeks gebou, maar herwinning bly presies totdat die uitbreiding opgegradeer is (alter extension vector update), want gefiltreerde HNSW-skanderings het iteratiewe skanderings van 0.8 nodig. Om dit later op ’n bediener daarsonder te aktiveer, installeer die uitbreiding, voer die aanvangsopstelling weer uit (of create extension vector as superuser), en voer dan as quire_migrator uit:

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

Dit is idempotent en gee enabled of unavailable terug. Voer dit ook op elke toegewyde tenant-databasis uit.

Rol terug

Om kode terug te rol is altyd moontlik: stel QUIRE_RELEASE op die vorige merker en voer up -d weer uit. Dit werk omdat die skema in albei rigtings binne ’n vrystelling versoenbaar is.

Om skema terug te rol, word nie aangebied nie. Wat nie omkeerbaar is nie, en hoe om daarvan te herstel:

Daarom word ’n kontrakmigrasie alleen verskeep: herstel het dan ’n skoon grens.

Kontroleer die opgradering

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