Uuendamine katkestuseta

Reeglid on dokumentides docs/architecture/23-ops.md jaotis 7 ja docs/architecture/07-data.md jaotis 4.1. See on toimingujuhend.

Ohutuse tagav lubadus

Väljalase R töötab nii skeemiga R kui ka skeemiga R miinus üks. Iga skeemimuudatus jaguneb laiendamiseks, üleminekuks ja kokkutõmbamiseks:

1. Laiendus: lisa uus veerg, tabel või indeks; vana kood eirab seda.
2. Üleminek, vähemalt ühe väljalaske vältel: uus kood kirjutab mõlemat kuju ja loeb uut; jätkatav töö täidab vanad read.
3. Kokkutõmbamine: eemalda vana kuju eraldi, hilisemas väljalaskes.

Seega saavad jooksva uuenduse igal hetkel vanad ja uued protsessid kasutada üht andmebaasi. Tagasipööratavaid migratsioone pole: tund aega tagasi veeru kustutanud migratsioon ei taasta selle tunni jooksul kirjutatud ridu.

CI-töö schema-compat kontrollib seda igas väljalaskes, käivitades eelmise väljalaske testid uue skeemi vastu.

Enne alustamist

1. Loe väljalaskemärkmeid. Hooldusakent vajav väljalase teatab sellest koos kestuse hinnanguga; neid on kõige rohkem üks väljalaske kohta.
2. Käivita taastamiskatse või kinnita, et see on selle väljalaske jaoks edukalt lõppenud (backup-restore.md). Nurjunud katse peatab uuenduse.
3. Tee põhi-varukoopia: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose ühes hostis

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

Järjekord on tahtlik:

1. Käivita migratsioon esmalt, kui vana väljalase veel teenindab liiklust. Laiendusmigratsioonid sellele nähtavad pole.
2. Uuenda veebikihti seejärel. SIGTERM-i korral märgib iga veebiprotsess /readyz olekuks draining, lõpetab pooleliolevad päringud 30 sekundi jooksul, sulgeb vood taasühendamise vihjega ja väljub. stop_grace_period on 40 sekundit, nii et Compose ei katkesta tervet lõpetamist.
3. Töötlejad viimasena, et uusim sündmusekuju loodaks enne, kui uusim tarbija seda eeldab. Töötlejad lõpetavad kohe tööde võtmise ja neil on aega 120 sekundit; lõpetamata töö võetakse mujal uuesti ette. See on ohutu, sest kõik tööd on korduskindlad. Ajastaja annab juhtimise üle järgmisel tsüklil.

Ühe hosti puhul asendab Compose iga konteineri kordamööda, põhjustades igas teenuses lühikese katkestuse. Täielikuks katkestuseta uuendamiseks käita veebikihti enda puhverserveri taga kahe konteinerina (ülekirjutusfailis lisa teine web-teenus ilma avaldatud pordita) ning loo need ükshaaval uuesti, oodates enne järgmist terve oleku teadet.

Mitu hosti või orkestreerija

Kasuta sama järjekorda: käivita migratsioon ühe tööna, uuenda seejärel veebikihti lisamise arvuga üks ja kättesaamatute arvuga null ning lõpuks töötlejaid. Suuna valmiduskontrollid aadressile /readyz, elusolekukontrollid aadressile /healthz.

Eriandmebaasiga rentnike puhul teeb migrate mõlemad toimingud: migreerib esmalt juhtandmebaasi ning seejärel ükshaaval iga andmebaasi tabelis ops.tenant_database, igaüks enda luku all. Ühe rentniku andmebaasi viga ei peata ülejäänuid. Lõpus võrreldakse migratsioonide arvestust ning käsk lõpeb veakoodiga, kui kõigis andmebaasides pole kasutusel täpselt sama migratsioonide kogum mis juhtandmebaasis; nimetatakse iga maha või ette jäänud andmebaas. Sama käsk paigaldab igasse andmebaasi järjekorratabelid, sest töötleja tarbib seotud rentniku tööd sealt, kuhu need kirjutati.

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

Tavaline migratsioon ja esmane seadistus installivad samuti Quire’i operaatori kanoonilised ingliskeelsed juriidilised dokumendid asukohta ops.platform_policy_version. Installija on idempotentne: asendatakse ainult puuduvad ingliskeelsed tekstid ja täpselt migratsiooni loodud kohatäitetekstid. Seemned arhiveeritakse ja lisatakse uus avaldatud versioon; ajaloolised aktsepteerimisviited ja tekstid säilivad. Iga ehtne operaatori kirjutatud versioon, sealhulgas mustand, säilib ja seda tuleb hallata platvormi poliitikakonsooli kaudu. Rentniku poliitikadokumendid, versioonid ja nõusolek ei muutu selle üleminekuga kunagi. See on operaatori teksti avaldamine, mitte juriidiline sertifitseerimine ega selle lubaduste automaatne täitmine.

Iga eriandmebaasi kasutatakse registreeritud nime kaudu. Andmebaas env:QUIRE_DB_NORTHWIND_URL vajab järgmisi muutujaid:

Registreeritud andmebaasi puuduv _MIGRATOR-ühendus raporteeritakse veana, mitte ei jäeta vahele. Veebikihti saab uuendada pärast juhtandmebaasi valmimist. Tund aega maha jäänud rentniku andmebaas annab hoiatuse; päevajagu maha jäänu tekitab väljakutse.

pgvector

Alates migratsioonist 0264 kasutab andmestik serveris laienduse olemasolul pgvectori HNSW-indeksit; Compose’i postgres-teenus ehitatakse selle toega (docker/postgres.Dockerfile). Esimene migrate pärast kujutise vahetamist loob laienduse superkasutaja algseadistusega ning 0264 lisab genereeritud vektorveeru ja loob indeksi. Veeru lisamine kirjutab tabeli app.ai_chunk ühe korra eksklusiivse luku all ümber, nii et andmestikupäringud ootavad; muid tabeleid see ei puuduta.

Ilma pgvectorita serveris logib 0264 teate ega muuda midagi ning otsing jääb täpseks. Kui pgvector on vanem kui 0.8, luuakse veerg ja indeks, kuid otsing jääb täpseks kuni laienduse uuendamiseni (alter extension vector update), sest filtreeritud HNSW-otsing vajab versiooni 0.8 kordusläbimisi. Selle hilisemaks lubamiseks serveris, kus seda pole, paigalda laiendus, käivita algseadistus uuesti (või superkasutajana create extension vector) ja käivita seejärel quire_migrator-ina:

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

Käsk on korduskindel ja tagastab enabled või unavailable. Käivita see ka igas eriandmebaasiga rentniku andmebaasis.

Tagasipööramine

Koodi saab alati tagasi pöörata: määra QUIRE_RELEASE eelmisele sildile ja käivita up -d uuesti. See on võimalik, sest ühe väljalaske piires ühilduvad skeemid mõlemas suunas.

Skeemi ei pöörata tagasi. Tagasipööramatud muudatused ja taastamisviisid:

Seepärast tarnitakse kokkutõmbemigratsioon eraldi: taastamisel on siis selge piir.

Uuenduse kontrollimine

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