Надстройване без престой

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

Гаранцията за безопасност

Версия 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. Накрая worker-ите, така че най-новият формат на събитията да се създава, преди най-новият обработчик да го очаква. Worker-ите спират да получават задачи веднага и имат 120 секунди; незавършена задача се получава отново другаде, което е безопасно, защото всяка задача е идемпотентна. Scheduler предава ръководството при следващия си такт.

На един хост Compose заменя контейнерите поотделно, така че за всяка услуга има кратка пауза. За непрекъсната работа пуснете два контейнера на уеб слоя зад собствен прокси (чрез override файл добавете втори уеб service без публикуван порт) и създавайте контейнерите един по един, като изчаквате всеки да стане здрав, преди да продължите.

Няколко хоста или оркестратор

Използвайте същия ред: стартирайте миграцията веднъж като отделна задача, после постепенно обновете уеб слоя с едно допълнително копие и нула недостъпни, след това worker-ите. Насочете проверките за готовност към /readyz, а проверките за активност — към /healthz.

При отделни бази на клиенти стъпката migrate изпълнява и двете: първо мигрира базата за управление, после всяка база от ops.tenant_database — последователно, всяка със собствена блокировка. Неуспешна миграция в една база не спира останалите. Когато всички са готови, процесът сравнява журналите на миграциите и завършва с ненулев код, освен ако във всяка база няма точно същите миграции като в управляващата база; посочва всяка база, която изостава или е напред. Същата команда инсталира таблиците за опашката във всяка база, защото worker обработва задачите на фиксиран клиент там, където са записани.

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

Всяка отделна база се достига чрез името, с което е регистрирана. За база с регистрация env:QUIRE_DB_NORTHWIND_URL са нужни:

Регистрирана база без връзка _MIGRATOR се отчита като неуспешна, никога не се пропуска. Уеб слоят може да се обнови, когато управляващата база е готова. База на клиент, изостанала с час, показва предупреждение; при изоставане с ден се изпраща известие.

pgvector

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

На сървър без pgvector миграция 0264 записва известие и не променя нищо; търсенето остава точно. При pgvector със стара версия от 0.8 колоната и индексът се създават, но търсенето остава точно, докато разширението не се обнови (alter extension vector update), защото филтрираните HNSW заявки изискват итеративното търсене от версия 0.8. За да го активирате по-късно на сървър без разширението, инсталирайте го, отново стартирайте началната настройка (или create extension vector като superuser), после изпълнете като 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