Atnaujinimas be prastovos

Taisyklės yra docs/architecture/23-ops.md 7 skyriuje ir docs/architecture/07-data.md 4.1 skyriuje. Štai procedūra.

Garantija, dėl kurios tai saugu

Versija R veikia teisingai su schema R ir schema R minus viena. Kiekvienas schemos pakeitimas išskirtas į išplėtimą, pereinamąjį ir sutraukimą:

1. Išplėtimas: pridedamas naujas stulpelis, lentelė arba indeksas. Senas kodas jo ignoruoja.
2. Pereinamasis, bent vienai versijai: naujas kodas įrašo abiejų formų ir skaito naują; tęsti galima užduotis senas eilutes užpildo.
3. Sutraukimas: sena forma išmetama vėlesnėje versijoje, atskirai.

Taigi kiekvieną rito atnaujinimo momentą seni ir nauji procesai gali dalytis viena duomenų baze. Nužemėjimo migracijų nėra: migracija, kuri prieš valandą išmetė stulpelį, negali grąžinti per tą valandą įrašytų eilučių.

CI užduotis schema-compat tikrina šią garantiją kiekvienai versijai vykdydama ankstesnės versijos testus prieš naują schemą.

Prieš pradėdami

1. Perskaitykite versijos pastabas. Versijai, kuriai reikia techninės priežiūros lango, tai nurodyta su įvertinimu; daugiausia vienas toks per versiją.
2. Paleiskite atkūrimo pratybas arba patvirtinkite, kad šiai versijai jos praėjo žalios (backup-restore.md). Nepavykusios pratybos blokuoja atnaujinimą.
3. Padarykite bazinę atsarginę kopiją: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, viena sistema

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

Eilė yra numatyta sąmoningai:

1. Pirmiausia migracija, kol sena versija aptarnauja srautą. Išplėtimo migracijos jai nematomos.
2. Tada tinklo sluoksnis. Gavus SIGTERM kiekvienas web procesas /readyz perjungia į draining, per 30 sekundžių užbaigia vykdančias užklausas, uždaro srautus su pakartotinio prisijungimo užuomina ir išeina. stop_grace_period yra 40 sekundžių, kad Compose niekada nenutrauktų sveiko ištuštinimo.
3. Paskutiniai darbininkai, kad naujausia įvykio forma būtų sukurta anksčiau, nei to laukia naujausias vartotojas. Darbininkai iš karto nustoja imti ir gauna 120 sekundžių; užduotis, kuri negali baigtis, bus paimta kitur, o tai saugu, nes kiekviena užduotis idempotentinė. Tvarkytuvas vadovavimą perduoda kitu savo taku.

Vienoje sistemoje Compose keičia kiekvieną konteinerį iš eilės, todėl kiekvienai paslaugai yra trumpa pertraukėlė. Kad pertraukėlės visai nebūtų, paleiskite tinklo sluoksnį kaip du konteinerius už savo paties įėjimo taško (perrašymo failas, pridedantis antrą web paslaugą be skelbiamo porto) ir atkurkite juos po vieną, palaukdami, kol kiekvienas praneš apie sveikatą, prieš kitą.

Kelių sistemų arba orkestratorius

Naudokite tą pačią tvarką: migraciją atlikite vieną kartą iš vienos užduoties, tada atnaujinkite tinklo sluoksnį su surge one ir unavailable zero, tada darbininkus. Pasiruošumo zondus nukreipkite į /readyz, o gyvybės – į /healthz.

Turint atskiras nuomininkų duomenų bazes, žingsnis migrate daro abu dalykus: pirma migruoja valdymo duomenų bazę, tada kiekvieną ops.tenant_database sąraše išvardytą duomenų bazę po vieną, kiekvieną su savo užraktu. Vienos nuomininko duomenų bazės nesėkmė nesustabdo kitų. Kai baigiama visos, palyginamos migracijų knygos ir išeinama su ne nuliniu kodu, jei ne kiekviena duomenų bazė pritaikė lygiai tas pačias migracijas, kaip valdymo duomenų bazė, įvardijant kiekvieną atsiliekančią arba pirmaujančią. Ta pati komanda įdiegia eilės lenteles kiekvienoje duomenų bazėje, nes darbininkas suvartoja pririšto nuomininko užduotis ten, kur jos buvo įrašytos.

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

Kiekviena atskira duomenų bazė pasiekiama pavadinimu, kuriuo ji užregistruota. Duomenų bazė, užregistruota kaip env:QUIRE_DB_NORTHWIND_URL, reikia:

Užregistruota duomenų bazė be _MIGRATOR ryšio pranešama kaip nesėkmė, niekada nepraleidžiama. Tinklo sluoksnis gali riti, kai baigiama valdymo duomenų bazė. Nuomininko duomenų bazė, atsilikusi valandą, įspėjama; parą – kviečiama budintis.

pgvector

Nuo migracijos 0264 pagrindo korpusas naudoja pgvector HNSW indeksą ten, kur serveryje yra plėtinys; Compose postgres paslauga pastatyta su ja (docker/postgres.Dockerfile). Pirmas migrate pakeitus atvaizdus sukuria plėtinį per superuserio pradinę sąrangą, o 0264 tada prideda generuojamą vektorių stulpelį ir stato indeksą. Stulpelio pridėjimas kartą perrašo app.ai_chunk su išskirtiniu užraktu, todėl pagrindo užklausos jo laukia; niekas kitas tos lentelės neliečia.

Serveryje be pgvector 0264 užrašo pranešimą ir nieko nekeičia, o paieška lieka tiksli. Su pgvector, senesniu už 0.8, stulpelis ir indeksas pastatomi, bet paieška lieka tiksli, kol plėtinys neatnaujinamas (alter extension vector update), nes filtruoti HNSW nuskaitymai reikia 0.8 interaktyvių nuskaitymų. Kad vėliau tai įjungtumėte serveryje, kur jo nėra, įdiekite plėtinį, dar kartą paleiskite pradinę sąrangą (arba create extension vector superuseriu), tada kaip quire_migrator:

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

Tai idempotentiška ir grąžina enabled arba unavailable. Paleiskite ją ir kiekvienoje atskiroje nuomininko duomenų bazėje.

Atšaukimas

Kodo atšaukimas visada galimas: nustatykite QUIRE_RELEASE į ankstesnę žymą ir vėl up -d. Tai veikia, nes schema abiem kryptimis suderinama tos pačios versijos viduje.

Schemos atšaukimo nesiūloma. Kas negali būti atšaukta ir kaip iš to atkurti:

Todėl sutraukimo migracija išleidžiama atskirai: tada atkūrimas turi švarią ribą.

Atnaujinimo patikrinimas

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