Upgrade maachen ouni Stillstand

D’Regelen stinn an docs/architecture/23-ops.md Kapitel 7 an docs/architecture/07-data.md Kapitel 4.1. Dëst ass d’Prozedur.

D’Garantie, déi et sécher mécht

Release R leeft korrekt géigeniwwer Schema R an Schema R minus een. All Schema-Ännerung gëtt an expand, transition an contract opgedeelt:

1. Expand: nei Sëll, Tabell oder Index derbäisetzen. Alen Code ignoréiert en.
2. Transition, fir mindestens eng Release: neien Code schreift béid Formen an liest déi nei; en weiderfouerbaren Job fëllt al Zeilen no.
3. Contract: d’al Form ewechhuelen, an enger méi spéiderer Release, eleng.

Also an all Moment vun engem rullenden Upgrade kënnen al a nei Prozesser eng eenzeg Datebank deelen. Et gëtt keng Migratioune virun zréck: eng Migratioun, déi virun enger Stonn eng Sëll ewechgeholl huet, kann d’Zeilen net zeréckginn, déi an där Stonn geschriwwen goufen.

De schema-compat-CI-Job kontrolléiert d’Garantie bei all Release, andeems hien d’Tester vun der viregter Release géint den neien Schema ausféiert.

Ier Dir ufänkt

1. Liest d’Notizen zur Release. Eng Release, déi en Ënnerhaltsfënster brauch, seet dat mat der Schätzung; héichstens een pro Release.
2. Féiert de Restauratiounstest aus, oder bestätegt datt en fir dës Release grénge gelaf huet (backup-restore.md). E feelgeschloenen Test blockéiert den Upgrade.
3. Hëlt en Basisbackup: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, een Server

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

D’Reienfolge ass bewosst:

1. Migréiert éischte, während déi al Release de Traffic bedéint. Expand-Migratioune sinn fir en unsiichtbar.
2. De Web-Tier duerno. Bei SIGTERM setzt all Web-Prozess /readyz op draining, féiert d’Demanden, déi schonn drënner sinn, bannendrem 30 Sekonnen fäerig, mécht Stréimungen mat engem Reconnect-Hinweis zou, an geet eraus. stop_grace_period sinn 40 Sekonnen, sou datt Compose ni eng gesond Opléisung ofschneid.
3. D’Worker lescht, sou datt déi neist Form vum Evenement produzéiert gëtt, iert de neiste Verbraicher se erwaart. D’Worker halen op ze huelen a kréien 120 Sekonnen; e Job, deen net fäerig ka ginn, gëtt anescht nach eng Kéier geholl, wat sécher ass well all Job idempotent ass. De Scheduler gëtt seng Féierung bei sengem nächsten Tick iwwer.

Op engem Host ersetzt Compose all Container der Rei no, sou datt et e kuerze Lach pro Service gëtt. Fir iwwerhaapt kee Lach, féiert de Web-Tier als zwee Container hanner Ärem eegenen Proxy (eng Iwwerschreiwungsdatebank, déi en zweeten Web-Service derbäisetzt ouni publicéiert Port), an erstellt se eemol no dem aneren nei, waart bis all seet datt en gesond ass, iert de nächste kënnt.

Méi Hosten oder en Orchester

Benotzt déiselwecht Reienfolge: eemol migréieren aus engem eenzegen Job, dann de Web-Tier ausrollen mat surge one an unavailable zero, an dunn d’Worker. Riicht d’Readiness-Proben op /readyz an d’Liveness-Proben op /healthz.

Mat dedikéierte Tenant-Datebanken mécht den migrate-Schritt béid: hien migréiert éischte d’Kontroll-Datebank, dann all Datebank, déi an ops.tenant_database opgelëscht ass, een nom aneren, all ënner sengem eegene Lock. E Feel an enger Tenant-Datebank stoppt déi aneren net. Wann all Datebank fäerig ass, vergläicht hien d’Migratiounsledger a geet mat Net-Null eraus, ausser all Datebank huet genauso d’Migratioune ugewannt, déi d’Kontroll-Datebank huet, a nennt all déi, déi hannendrun oder virudrun sinn. D’Selwecht Kommando installéiert d’Queue-Tabellen an all Datebank, well de Worker d’Joben vun engem festgeluechten Tenant do veraarbecht, wou se geschriwwen goufen.

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

Normal Migratioun a Éischt-Operriichte installéieren och déi kanonesch englesch juristesch Dokumenter vum Quire-Bedreiwer an ops.platform_policy_version. Den Installateur ass idempotent: et gi just feelend englesch Texter an exakt déi Plazhaltertexter ersat, déi d’Migratioun geséit huet. Seeds gi archivéiert an eng nei publizéiert Versioun gëtt agefouert; historesch Akzeptanzreferenzen an Texter bleiwe bestoen. All richteg vum Bedreiwer geschriwwe Versioun, och en Entworf, bleift bestoen a muss iwwer d’Politik-Konsole vun der Plattform geréiert ginn. Dokumenter, Versiounen an Zoustëmmung vun Tenant-Politike gi bei dësem Iwwergank ni geännert. Dat ass Publikatioun vum Bedreiwertext, keng juristesch Zertifizéierung an keng automatesch Erfëllung vu senge Verspriechen.

All dedikéiert Datebank gëtt iwwer den Numm erreech, ënner dem se registréiert ass. Eng Datebank, déi als env:QUIRE_DB_NORTHWIND_URL registréiert ass, braucht:

Eng registréiert Datebank ouni _MIGRATOR-Verbindung gëtt als Feel bericht, ni iwwersprongt. De Web-Tier kann ausgerullt ginn, sou wéi d’Kontroll-Datebank fäerig ass. Eng Tenant-Datebank, déi eng Stonn hannendrun ass, warnt; eng Dag hannendrun schéckt se en Alarm.

pgvector

Zënter Migratioun 0264 benotzt de Grounding-Korpus en pgvector-HNSW-Index, wann de Server d’Extensioun huet; de Compose-postgres-Service ass domat gebaut (docker/postgres.Dockerfile). Den éischten migrate no dem Wisel vun de Biller erstellt d’Extensioun iwwer de Superuser-Bootstrap, an 0264 sezt dunn eng generéiert Vektorsëll derbäi an baut den Index. D’Sëll derbäizesetzen schreift app.ai_chunk eemol ënner engem exklusiven Lock nei, sou datt Grounding-Demanden drop waart; näischt aneres beréiert där Tabell.

Op engem Server ouni pgvector loggt 0264 en Hinweis an ännert näischt, an d’Retrieval bleift exakt. Mat engem pgvector méi al wéi 0.8 ginn d’Sëll an den Index gebaut, mä d’Retrieval bleift exakt bis d’Extensioun eropgradéiert gëtt (alter extension vector update), well gefiltert HNSW-Scan déi iterativ Scanne vun 0.8 brauchen. Fir et duerno op engem Server ouni et ze aktivéieren, installéiert d’Extensioun, féiert de Bootstrap nach eng Kéier aus (oder create extension vector als Superuser), dann als quire_migrator:

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

En ass idempotent an gëtt enabled oder unavailable zréck. Féiert en och op all dedikéierter Tenant-Datebank aus.

Zréckrullen

Code zréckrullen ass ëmmer méiglech: setzt QUIRE_RELEASE op de viregten Tag a féiert up -d erëm aus. Dat funktionéiert well de Schema bannendrem enger Release an béid Richtunge kompatibel ass.

Schema zréckrullen gëtt net ugebueden. Wat net réckgängeg gëtt, a wéi een dovun sech erholt:

Dovunner hänkt et, dass eng Contract-Migratioun eleng kënnt: eng Restauratioun huet dann eng propper Grenz.

Den Upgrade kontrolléieren

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