Nadogradnja bez prekida rada

Pravila su navedena u odjeljku 7 dokumenta docs/architecture/23-ops.md i odjeljku 4.1 dokumenta docs/architecture/07-data.md. Ovo je postupak nadogradnje.

Garancija koja omogućava sigurnu nadogradnju

Izdanje R ispravno radi sa šemom R i šemom R minus jedan. Svaka promjena šeme podijeljena je na proširenje, prijelaz i uklanjanje:

1. Proširenje: dodajte novu kolonu, tabelu ili indeks. Stari kod ih ignoriše.
2. Prijelaz, tokom najmanje jednog izdanja: novi kod zapisuje u oba oblika i čita novi; zadatak koji se može nastaviti popunjava stare redove.
3. Uklanjanje: u kasnijem izdanju, kao jedinu promjenu, uklonite stari oblik.

Tako stari i novi procesi tokom postepene nadogradnje uvijek mogu dijeliti istu bazu. Povratne migracije ne postoje: migracija koja je prije sat vremena uklonila kolonu ne može vratiti redove unesene u tom satu.

CI zadatak schema-compat provjerava ovu garanciju za svako izdanje tako što testove prethodnog izdanja pokreće nad novom šemom.

Prije početka

1. Pročitajte bilješke izdanja. Ako izdanje zahtijeva period održavanja, bilješke navode procjenu; takav period predviđen je najviše jednom po izdanju.
2. Pokrenite probu vraćanja sigurnosne kopije ili potvrdite da je za ovo izdanje uspješno prošla (backup-restore.md). Neuspjela proba blokira nadogradnju.
3. Napravite osnovnu sigurnosnu kopiju: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose na jednom hostu

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

Redoslijed je namjeran:

1. Prvo migrirajte, dok staro izdanje još poslužuje promet. Promjene za proširenje nisu vidljive starom izdanju.
2. Zatim nadogradite web sloj. Pri SIGTERM-u svaki web proces postavlja /readyz na draining, dovršava zahtjeve u toku najkasnije za 30 sekundi, zatvara tokove uz uputu za ponovno povezivanje i gasi se. stop_grace_period je 40 sekundi, pa Compose neće prekinuti uredno gašenje.
3. Na kraju nadogradite workere, tako da se novi oblik događaja proizvodi prije nego što ga počne očekivati najnoviji potrošač. Workeri odmah prestaju preuzimati zadatke i dobijaju 120 sekundi; zadatak koji ne mogu dovršiti preuzima se drugdje, što je sigurno jer je svaki zadatak idempotentan. Scheduler predaje vodstvo na sljedećem ciklusu.

Na jednom hostu Compose zamjenjuje kontejnere redom, pa svaka usluga kratko prekida rad. Za neprekidan rad pokrenite dva web kontejnera iza vlastitog proxyja (u override datoteci dodajte drugu web uslugu bez objavljenog porta) i rekreirajte ih jedan po jedan, čekajući da svaki postane zdrav prije sljedećeg.

Više hostova ili orkestrator

Zadržite isti redoslijed: jednom pokrenite migraciju kao zaseban zadatak, zatim postepeno nadogradite web sloj s jednim dodatnim i nula nedostupnih instanci, pa workere. Provjere spremnosti usmjerite na /readyz, a provjere aktivnosti na /healthz.

Kada su baze podataka klijenata namjenske, korak migrate migrira kontrolnu bazu, zatim svaku bazu navedenu u ops.tenant_database, jednu po jednu i uz vlastitu blokadu. Greška u jednoj bazi klijenta ne zaustavlja ostale. Nakon migracije svih baza upoređuju se evidencije migracija; komanda završava kodom koji nije nula osim ako je u svakoj bazi primijenjeno tačno isto kao u kontrolnoj bazi, te navodi svaku bazu koja zaostaje ili je ispred. Ista komanda instalira tabele reda u svakoj bazi jer worker obrađuje zadatke fiksiranog klijenta u bazi u koju su upisani.

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

Svakoj namjenskoj bazi pristupa se pomoću imena pod kojim je registrovana. Za bazu registrovanu kao env:QUIRE_DB_NORTHWIND_URL potrebno je:

Registrovana baza bez veze _MIGRATOR prijavljuje se kao neuspješna, nikad se ne preskače. Web sloj može se nadograditi nakon završetka migracije kontrolne baze. Kašnjenje baze klijenta od jednog sata izaziva upozorenje, a kašnjenje od jednog dana šalje stranicu.

pgvector

Od migracije 0264 korpus uzemljenja koristi pgvector HNSW indeks ako server ima tu ekstenziju; Compose postgres servis izgrađen je s njom (docker/postgres.Dockerfile). Prvi migrate nakon promjene slika stvara ekstenziju putem početne postavke superusera, a migracija 0264 dodaje generisanu vektorsku kolonu i gradi indeks. Dodavanje kolone jednom prepisuje app.ai_chunk uz ekskluzivnu blokadu, pa zahtjevi za uzemljenje čekaju; ništa drugo ne koristi tu tabelu.

Na serveru bez pgvectora migracija 0264 bilježi obavještenje i ne mijenja ništa, a dohvat ostaje tačan. Uz pgvector stariji od 0.8 kolona i indeks se izgrade, ali dohvat ostaje tačan dok se ekstenzija ne nadogradi (alter extension vector update), jer filtriranim HNSW pretragama trebaju iterativni prolazi iz verzije 0.8. Da biste kasnije omogućili funkciju na serveru bez nje, instalirajte ekstenziju, ponovo izvršite početnu postavku (ili kao superuser pokrenite create extension vector), pa kao quire_migrator pokrenite:

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

Operacija je idempotentna i vraća enabled ili unavailable. Pokrenite je i na svakoj namjenskoj bazi klijenta.

Vraćanje prethodne verzije

Vraćanje koda uvijek je moguće: postavite QUIRE_RELEASE na prethodnu oznaku, pa ponovo pokrenite up -d. To radi jer je šema kompatibilna u oba smjera unutar izdanja.

Vraćanje šeme nije podržano. Evo šta se ne može poništiti i kako se oporaviti:

Zato se migracija uklanjanja objavljuje sama: vraćanje tada ima jasnu granicu.

Provjera nadogradnje

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