Pag-upgrade nga walay downtime

Anaa ang mga lagda sa seksiyon 7 sa docs/architecture/23-ops.md ug seksiyon 4.1 sa docs/architecture/07-data.md. Mao kini ang pamaagi.

Ang garantiya nga naghimo niini nga luwas

Husto ang pagpadagan sa Release R sa schema R ug schema R minus one. Bahinon ang matag kausaban sa schema ngadto sa expand, transition ug contract:

1. Expand: idugang ang bag-ong column, table o index. Dili kini tagdon sa karaang code.
2. Transition, sulod sa labing menos usa ka release: mosulat ang bag-ong code sa duha ka porma ug mobasa sa bag-o; pun-on pag-usab sa resumable job ang karaang mga row.
3. Contract: tangtangon ang karaang porma sa ulahing release, nga mao ra kini ang kausaban.

Busa sa matag higayon sa rolling upgrade, mahimong mogamit ang karaan ug bag-ong proseso sa usa ka database. Walay down migration: dili na maibalik sa migration nga mitangtang og column usa ka oras ang milabay ang mga row nga nasulat niadtong orasa.

Susiha sa CI job nga schema-compat kini nga garantiya sa matag release pinaagi sa pagpadagan sa mga test sa miaging release batok sa bag-ong schema.

Sa dili pa magsugod

1. Basaha ang release notes. Kon nagkinahanglan og maintenance window ang release, ipahibalo niini ang gibanabanang gidugayon; labing usa ra kada release.
2. Padagana ang restore drill, o pamatud-i nga malampuson kini niining release (backup-restore.md). Makababag sa upgrade ang napakyas nga drill.
3. Paghimo og base backup: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, usa ka host

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

Tinuyo ang han-ay:

1. Una ang migration, samtang nagserbisyo pa sa trapiko ang karaang release. Dili makita niini ang expand migration.
2. Sunod ang web tier. Sa SIGTERM, usbon sa matag web process ang /readyz ngadto sa draining, humanon ang nagdagan nang mga request sulod sa 30 segundos, sirad-an ang stream nga adunay pahibalo sa pag-reconnect, ug mogawas. 40 segundos ang stop_grace_period aron dili putlon sa Compose ang himsog nga pag-drain.
3. Kataposan ang mga worker, aron mabuhat una ang pinakabag-ong event nga porma sa dili pa kini paabuton sa bag-ong consumer. Mohunong dayon sa pagkuha og trabaho ang mga worker ug adunay 120 segundos; kon dili mahuman ang usa ka job, kuhaon kini pag-usab sa laing worker. Luwas kini kay idempotent ang matag job. Itugyan sa scheduler ang pagpangulo sa sunod nga tick niini.

Sa usa ka host, pulihan sa Compose ang matag container sa tagsa-tagsa, busa adunay mubo nga paghunong kada service. Aron walay hunong, padagana ang web tier isip duha ka container luyo sa kaugalingon nimong proxy (pinaagi sa override file nga magdugang og ikaduhang web service nga walay published port), ug pulihi sila tagsa-tagsa. Hulata nga himsog ang matag usa sa dili pa ilisan ang sunod.

Daghang host o orchestrator

Gamita gihapon ang samang han-ay: padagana kausa ang migration isip usa ka job, dayon i-roll ang web tier nga surge usa ug unavailable zero, unya ang mga worker. Itudlo ang readiness probe sa /readyz ug ang liveness sa /healthz.

Kon adunay kaugalingong tenant database, buhaton sa lakang nga migrate ang duha: una i-migrate ang control database, unya tagsa-tagsa ang tanang database nga gilista sa ops.tenant_database, matag usa ubos sa kaugalingong lock. Dili mapahunong sa kapakyasan sa usa ka tenant database ang uban. Kon mahuman na ang tanang database, itandi niini ang migration ledger ug mogawas nga non-zero gawas kon parehas gayod ang mga migration sa matag database ug sa control database; nganlan niini ang matag database nga nahabilin o nauna. I-install usab sa samang command ang mga queue table sa matag database, kay didto kuhaon sa worker ang mga job sa naka-pin nga tenant diin kini gisulat.

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

Maabot ang matag kaugalingong database pinaagi sa ngalan nga girehistro niini. Kinahanglan sa database nga narehistro isip env:QUIRE_DB_NORTHWIND_URL ang mosunod:

Kon walay _MIGRATOR connection ang narehistrong database, ireport kini nga kapakyasan; dili kini laktawan. Mahimo nang i-roll ang web tier kon nahuman ang control database. Magpasidaan kon usa ka oras nga naulahi ang tenant database; magpage kon usa na ka adlaw.

pgvector

Sugod sa migration 0264, mogamit ang grounding corpus og pgvector HNSW index kon anaa ang extension sa server; gitukod ang Compose postgres service uban niini (docker/postgres.Dockerfile). Sa unang migrate human mag-ilis og image, himoon ang extension pinaagi sa superuser bootstrap, unya magdugang ang 0264 og generated vector column ug magtukod sa index. Usbon kausa sa pagdugang sa column ang app.ai_chunk ubos sa exclusive lock, busa maghulat ang grounding request niini; walay laing mogamit sa maong table.

Kon walay pgvector sa server, mag-log og pahibalo ang 0264 ug walay usbon, ug magpabilin nga eksakto ang retrieval. Kon mas karaan sa 0.8 ang pgvector, matukod ang column ug index apan magpabiling eksakto ang retrieval hangtod ma-upgrade ang extension (alter extension vector update), kay nagkinahanglan og iterative scan sa 0.8 ang filtered HNSW scan. Aron ma-enable kini unya sa server nga wala pa niini, i-install ang extension, padagana pag-usab ang bootstrap (o create extension vector isip superuser), unya isip quire_migrator:

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

Idempotent kini ug mobalik og enabled o unavailable. Padagana usab kini sa matag kaugalingong tenant database.

Pag-rollback

Kanunayng mahimo ang pag-rollback sa code: itakda ang QUIRE_RELEASE sa miaging tag ug padagana pag-usab ang up -d. Molihok kini kay magkauyon ang schema sa duha ka direksiyon sulod sa usa ka release.

Dili itanyag ang pag-rollback sa schema. Mao kini ang mga dili na mabawi ug paagi sa pag-ayo:

Mao nga mag-inusara ang contract migration sa release: limpyo ang utlanan kon mag-restore.

Pagsusi sa upgrade

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