Надградба без прекин

Правилата се во docs/architecture/23-ops.md оддел 7 и docs/architecture/07-data.md оддел 4.1. Ова е постапката.

Гаранцијата што го прави безбедно

Издание R работи точно спроти шема R и шема R минус еден. Секоја промена на шемата е поделена на проширување, преод и склучување:

1. Проширување: додадете ја новата колона, табела или индекс. Стариот код ја игнорира.
2. Преод, барем за едно издание: новиот код запишува во двата облици и чита од новиот; работа што може да продолжи ги пополнува старите редови.
3. Склучување: отстранете го стариот облик, во подоцнежно издание, самостојно.

Затоа во секој момент на течна надградба, старите и новите процеси можат да споделуваат една база на податоци. Нема спуштачки миграции: миграција што пред еден час отстранила колона не може да ги врати редовите запишани во тој час.

CI-работата schema-compat ја проверува гаранцијата на секое издание со извршување на тестовите од претходното издание спроти новата шема.

Пред да започнете

1. Прочитајте ги белешките за изданието. Издание што бара прозорец за одржување го наведува тоа, со проценка; најмногу едно по издание.
2. Изведете ја вежбата за враќање или потврдете дека поминала успешно за ова издание (backup-restore.md). Неуспешната вежба ја блокира надградбата.
3. Направете основно резервно копие: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, еден домаќин

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

Редоследот е намерен:

1. Прво мигрирајте, додека старото издание опслужува сообраќај. Миграциите за проширување се невидливи за него.
2. Потоа веб-слојот. При SIGTERM секој веб-процес ја превртува /readyz во draining, ги завршува тековните барања во рок од 30 секунди, ги затвора тековите со напомена за повторно поврзување и излегува. stop_grace_period е 40 секунди за да Compose никогаш не прекинува здраво празнење.
3. Workers последни, така што најновиот облик на настан се произведува пред најновиот потрошувач да го очекува. Workers веднаш престануваат да влечат и добиваат 120 секунди; работа што не може да заврши се влече повторно на друго место, што е безбедно бидејќи секоја работа е идемпотентна. Распоредувачот ја предава водството при следниот тик.

На еден домаќин, Compose го заменува секој контејнер по ред, така што има краток пресек по услуга. За да нема пресек воопшто, извршете го веб-слојот како два контејнера зад вашиот сопствен прокси (датотека за отфрлување што додава втора web-услуга без објавен порт) и креирајте ги повторно еден по еден, чекајќи секој да пријави здравје пред следниот.

Неколку домаќини или оркестратор

Користете го истиот редослед: мигрирајте еднаш од една работа, потоа тркалајте го веб-слојот со surge еден и unavailable нула, па работниците. Насочете ги проверките за подготвеност на /readyz, а проверките за живост на /healthz.

Со посебни бази на податоци на закупец, чекорот migrate го прави и двете: прво ја мигрира контролната база, потоа секоја база наведена во ops.tenant_database, една по една, секоја под своја брава. Неуспех во една база на закупец не ги запира другите. Кога секоја база ќе заврши, ги споредува дневниците на миграции и излегува со ненулта вредност освен ако секоја база ги применила точно миграциите што ги има контролната база, наведувајќи ја секоја што заостанува или е пред неа. Истата команда ги инсталира табелите со редици во секоја база, бидејќи работникот ги консумира работите на врзаниот закупец таму каде што биле запишани.

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

Нормалната миграција и првичното поставување исто така ги инсталираат канонските англиски правни документи на операторот Quire во ops.platform_policy_version. Инсталерот е идемпотентен: се заменуваат само недостасувачките англиски текстови и точно оние привремени текстови што ги создаде миграцијата. Семињата се архивираат и се вметнува нова објавена верзија; историските референци на прифаќање и текстовите се зачувуваат. Секоја вистинска верзија напишана од операторот, вклучувајќи нацрт, се зачувува и мора да се управува преку конзолата Политики на платформата. Документите, верзиите и согласноста на политиките на закупецот никогаш не се менуваат со оваа транзиција. Ова е објавување на текстот на операторот, а не правна сертификација ниту автоматско исполнување на неговите ветувања.

Секоја посебна база се достигнува преку името под кое е регистрирана. База регистрирана како env:QUIRE_DB_NORTHWIND_URL бара:

Регистрирана база без врска _MIGRATOR се пријавува како неуспех, никогаш не се пропушта. Веб-слојот може да тркала откако контролната база ќе заврши. База на закупец што заостанува за еден час предупредува; за еден ден испраќа повик.

pgvector

Од миграција 0264 корпусот за засновање користи pgvector HNSW-индекс каде што серверот ја има екстензијата; услугата postgres на Compose е изградена со неа (docker/postgres.Dockerfile). Првиот migrate по менувањето на сликите ја создава екстензијата преку почетното поставување на суперкорисник, а 0264 потоа додава генерирана вектор-колона и го гради индексот. Додавањето на колоната повторно го запишува app.ai_chunk еднаш под исклучителна брава, така што барањата за засновање чекаат на неа; ништо друго не ја допира таа табела.

На сервер без pgvector, 0264 запишува белешка и не менува ништо, а пребарувањето останува точно. Со pgvector постар од 0.8 колоната и индексот се изградени, но пребарувањето останува точно сè додека екстензијата не се надгради (alter extension vector update), бидејќи филтрираните HNSW-скенирања го бараат интеративното скенирање од 0.8. За да го овозможите подоцна на сервер што ја нема, инсталирајте ја екстензијата, повторно извршете го почетното поставување (или create extension vector како суперкорисник), па како quire_migrator:

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

Таа е идемпотентна и враќа enabled или unavailable. Извршете ја и на секоја посебна база на закупец.

Враќање назад

Враќањето на кодот е секогаш достапно: поставете го QUIRE_RELEASE на претходната ознака и повторно up -d. Тоа работи бидејќи шемата е компатибилна во двата правци во рамките на изданието.

Враќањето на шемата не се нуди. Она што не може да се поништи и како да се оправи од тоа:

Затоа миграцијата за склучување се испорачува сама: враќањето тогаш има чиста граница.

Проверување на надградбата

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