Uwchraddio heb amser segur

Mae’r rheolau yn adran 7 o docs/architecture/23-ops.md ac adran 4.1 o docs/architecture/07-data.md. Dyma’r drefn.

Y warant sy’n gwneud hyn yn ddiogel

Mae datganiad R yn rhedeg yn gywir yn erbyn sgema R a sgema R llai un. Rhennir pob newid sgema yn ehangu, trawsnewid a chontractio:

1. Ehangu: ychwanegu’r golofn, tabl neu fynegai newydd. Mae’r hen god yn ei anwybyddu.
2. Trawsnewid, am o leiaf un datganiad: mae cod newydd yn ysgrifennu’r ddwy ffurf ac yn darllen yr un newydd; mae swydd y gellir ei hailddechrau yn ôl-lenwi rhesi hen.
3. Contractio: gollwng yr hen ffurf, mewn datganiad diweddarach, ar ei phen ei hun.

Felly, ar unrhyw adeg yn ystod uwchraddiad treigl, gall prosesau hen a newydd rannu un gronfa ddata. Nid oes mudo i lawr: ni all mudo a ollyngodd golofn awr yn ôl adfer y rhesi a ysgrifennwyd yn yr awr honno.

Mae’r swydd CI schema-compat yn gwirio’r warant ar bob datganiad drwy redeg profion y datganiad blaenorol yn erbyn y sgema newydd.

Cyn dechrau

1. Darllenwch nodiadau’r datganiad. Mae datganiad sydd angen ffenestr cynnal a chadw yn dweud hynny, ynghyd â’r amcangyfrif; un ar y mwyaf fesul datganiad.
2. Rhedwch y prawf adfer, neu cadarnhewch ei fod wedi pasio’n wyrdd ar gyfer y datganiad hwn (backup-restore.md). Mae prawf a fethodd yn rhwystro’r uwchraddiad.
3. Gwnewch gopi wrth gefn sylfaenol: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, un 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

Mae’r drefn yn fwriadol:

1. Mudo yn gyntaf, tra bo’r datganiad hen yn gwasanaethu traffig. Nid yw mudo ehangu yn weladwy iddo.
2. Y haen we nesaf. Ar SIGTERM, mae pob proses we yn newid /readyz i draining, yn gorffen ceisiadau sydd ar y gweill o fewn 30 eiliad, yn cau ffrydiau gyda gwybodaeth ailgysylltu, ac yn gadael. Mae stop_grace_period yn 40 eiliad, felly nid yw Compose byth yn torri draen iach.
3. Gweithwyr olaf, fel bod y siâp digwyddiad diweddaraf yn cael ei gynhyrchu cyn i’r defnyddiwr diweddaraf ei ddisgwyl. Mae gweithwyr yn stopio nôl gwaith ar unwaith ac yn cael 120 eiliad; caiff swydd na ellir ei gorffen ei nôl eto rywle arall, sy’n ddiogel oherwydd bod pob swydd yn idempotent. Mae’r scheduler yn trosglwyddo arweinyddiaeth ar ei tic nesaf.

Ar un host, mae Compose yn disodli pob cynhwysydd yn ei dro, felly ceir bwlch byr fesul gwasanaeth. I osgoi unrhyw fwlch, rhedwch y haen we fel dau gynhwysydd y tu ôl i’ch proxy eich hun (ffeil override sy’n ychwanegu ail wasanaeth web heb borth wedi’i gyhoeddi), a’u hail-greu un ar y tro, gan aros i bob un adrodd ei fod yn iach cyn yr un nesaf.

Sawl host neu drefnydd

Defnyddiwch yr un drefn: mudo unwaith o un swydd, yna treiglo’r haen we gydag un yn ymchwyddo a dim un yn anweithredol, yna’r gweithwyr. Pwyntiwch brobau parodrwydd at /readyz a bywiogrwydd at /healthz.

Gyda chronfeydd data tenantiaid penodedig, mae’r cam migrate yn gwneud y ddau beth: mae’n mudo cronfa ddata reoli yn gyntaf, yna pob cronfa a restrir yn ops.tenant_database, un ar y tro, pob un o dan ei glo ei hun. Nid yw methiant mewn un gronfa ddata tenant yn atal y lleill. Pan fydd pob cronfa wedi’i chwblhau, mae’n cymharu’r cofnodion mudo ac yn gadael gyda chod nad yw’n sero oni bai bod pob cronfa wedi cymhwyso’n union yr un mudo â chronfa ddata reoli, gan enwi pob un sydd ar ei hôl hi neu o’i blaen. Mae’r un gorchymyn yn gosod tablau ciw ym mhob cronfa ddata, oherwydd mae’r worker yn defnyddio swyddi tenant wedi’u pinio lle cawsant eu hysgrifennu.

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

Cyrhaeddir pob cronfa ddata benodedig drwy’r enw y’i cofrestrwyd oddi tano. Mae angen y canlynol ar gronfa ddata a gofrestrwyd fel env:QUIRE_DB_NORTHWIND_URL:

Mae cronfa ddata gofrestredig heb gysylltiad _MIGRATOR yn cael ei hadrodd fel methiant, byth yn cael ei hepgor. Gall yr haen we dreiglo unwaith y bydd y gronfa reoli wedi’i chwblhau. Mae cronfa tenant sydd awr ar ei hôl hi’n rhybuddio; ar ôl diwrnod mae’n anfon larwm.

pgvector

O fudo 0264 ymlaen, mae’r corpws sylfaenu’n defnyddio mynegai HNSW pgvector lle mae gan y gweinydd yr estyniad; mae gwasanaeth Compose postgres wedi’i adeiladu ag ef (docker/postgres.Dockerfile). Mae’r migrate cyntaf ar ôl newid delweddau’n creu’r estyniad drwy gychwyn superuser, ac yna mae 0264 yn ychwanegu colofn fector wedi’i chynhyrchu ac yn adeiladu’r mynegai. Mae ychwanegu’r golofn yn ailysgrifennu app.ai_chunk unwaith o dan glo unigryw, felly mae ceisiadau sylfaenu’n aros; nid yw dim arall yn cyffwrdd â’r tabl hwnnw.

Ar weinydd heb pgvector, mae 0264 yn cofnodi hysbysiad ac nid yw’n newid dim, ac mae adfer yn parhau’n union. Gyda fersiwn pgvector hŷn na 0.8, caiff y golofn a’r mynegai eu hadeiladu ond mae adfer yn parhau’n union nes uwchraddio’r estyniad (alter extension vector update), oherwydd mae angen sganiau ailadroddol 0.8 ar sganiau HNSW wedi’u hidlo. I’w alluogi’n ddiweddarach ar weinydd hebddo, gosodwch yr estyniad, rhedwch y cychwyn eto (neu create extension vector fel superuser), yna fel quire_migrator:

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

Mae’n idempotent ac yn dychwelyd enabled neu unavailable. Rhedwch ef ar bob cronfa ddata tenant benodedig hefyd.

Dychwelyd yn ôl

Mae dychwelyd cod bob amser ar gael: gosodwch QUIRE_RELEASE i’r tag blaenorol a rhedwch up -d eto. Mae hynny’n gweithio oherwydd bod y sgema’n gydnaws yn y ddau gyfeiriad o fewn datganiad.

Ni chynigir dychwelyd sgema. Yr hyn na ellir ei ddadwneud, a sut i adfer ohono:

Dyna pam mae mudo contractio’n cael ei ryddhau ar ei ben ei hun: mae gan adferiad ffin glir bryd hynny.

Gwirio’r uwchraddiad

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