Päivittäminen ilman käyttökatkoa

Säännöt löytyvät tiedoston docs/architecture/23-ops.md kohdasta 7 ja tiedoston docs/architecture/07-data.md kohdasta 4.1. Tässä on työohje.

Turvallisuuden takaava yhteensopivuus

Julkaisu R toimii skeeman R ja sitä edeltävän skeeman kanssa. Jokainen skeemamuutos jaetaan laajennus-, siirtymä- ja poistovaiheeseen:

1. Laajennus: lisää uusi sarake, taulu tai indeksi. Vanha koodi ohittaa sen.
2. Siirtymä kestää vähintään yhden julkaisun ajan: uusi koodi kirjoittaa molemmat rakenteet ja lukee uutta. Jatkettava työ täydentää vanhat rivit.
3. Poisto: poista vanha rakenne yksin myöhemmässä julkaisussa.

Rullaavan päivityksen jokaisessa vaiheessa vanhat ja uudet prosessit voivat siis käyttää samaa tietokantaa. Alasmuuttoja ei ole: tunti sitten pudotettua saraketta ei voi palauttaa sisältöineen, joka on kirjoitettu sen poistamisen jälkeen.

schema-compat-CI-työ tarkistaa yhteensopivuuden jokaisessa julkaisussa ajamalla edellisen version testit uudella skeemalla.

Ennen aloittamista

1. Lue julkaisutiedot. Huoltoikkunaa vaativassa julkaisussa siitä kerrotaan ja annetaan arvio; tällainen julkaisu on enintään kerran julkaisukierroksessa.
2. Suorita palautusharjoitus tai varmista, että tämän julkaisun harjoitus on onnistunut (backup-restore.md). Epäonnistunut harjoitus estää päivityksen.
3. Ota perustason varmuuskopio: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, yksi isäntä

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ärjestys on harkittu:

1. Suorita migraatiot ensin vanhan julkaisun palvellessa liikennettä. Laajennusvaiheen migraatiot eivät näy vanhalle versiolle.
2. Päivitä verkkopalvelut seuraavaksi. SIGTERM-signaalin saatuaan kukin verkkoprosessi merkitsee /readyz-tilaksi draining, viimeistelee käsittelyssä olevat pyynnöt 30 sekunnissa, sulkee virrat uudelleenyhdistämisvihjeen kera ja poistuu. stop_grace_period on 40 sekuntia, joten Compose ei katkaise onnistuvaa alasajoa.
3. Päivitä työntekijäprosessit viimeiseksi, jotta uusin tapahtumamuoto tuotetaan ennen kuin uusin käsittelijä sitä odottaa. Työntekijät lakkaavat hakemasta töitä heti ja saavat 120 sekuntia. Keskeneräiseksi jäänyt työ haetaan suoritettavaksi muualla. Tämä on turvallista, koska jokainen työ on idempotentti. Ajastin siirtää johtajuuden seuraavan käynnistyksensä yhteydessä.

Yhden isännän Composer vaihtaa säiliöt peräkkäin, joten palveluihin tulee lyhyt katkos. Täysin katkoton päivitys edellyttää, että verkkopalvelu suoritetaan kahtena säiliönä oman välityspalvelimesi takana (korvaava asetustiedosto lisää toisen verkkopalvelun julkaisematta porttia) ja säiliöt luodaan uudelleen yksitellen. Odota, että kukin on terve, ennen seuraavaa.

Useita isäntiä tai orkestroija

Käytä samaa järjestystä: suorita migraatiot kerran yksittäisenä työnä, päivitä sitten verkkopalvelut lisäyksellä yksi ja poissaolomäärällä nolla, ja päivitä lopuksi työntekijät. Aseta valmiustarkistukset osoitteeseen /readyz ja elossaolotarkistukset osoitteeseen /healthz.

Omistetuissa vuokraajatietokannoissa migrate-vaihe tekee molemmat: se migroi ensin ohjaustietokannan ja sen jälkeen kukin ops.tenant_database-taulussa luetelluista tietokannoista yksitellen omalla lukollaan. Yhden tietokannan virhe ei pysäytä muita. Kun kaikki tietokannat on käsitelty, migraatiokirjauksia verrataan. Komento palauttaa virhekoodin, ellei jokaisessa tietokannassa ole täsmälleen samoja migraatioita kuin ohjaustietokannassa, ja nimeää jäljessä tai edellä olevat tietokannat. Sama komento asentaa jonotaulut kaikkiin tietokantoihin, sillä työntekijä käsittelee kiinnitetyn vuokraajan työt siinä tietokannassa, johon ne kirjoitettiin.

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

Jokaiseen omistettuun tietokantaan otetaan yhteys sen rekisteröidyllä nimellä. Rekisteröity tietokanta env:QUIRE_DB_NORTHWIND_URL tarvitsee seuraavat muuttujat:

Rekisteröity tietokanta ilman _MIGRATOR-yhteyttä ilmoitetaan virheenä, eikä sitä ohiteta. Verkkopalvelut voi ottaa käyttöön, kun ohjaustietokanta on päivitetty. Tunnin myöhässä oleva vuokraajatietokanta aiheuttaa varoituksen; vuorokauden myöhässä oleva hälytyksen.

pgvector

Migraatiosta 0264 lähtien pohjustustietoa käytetään pgvector HNSW -indeksillä, jos palvelimella on laajennus. Compose-palvelun postgres-kuva sisältää sen (docker/postgres.Dockerfile). Ensimmäinen kuvavaihdon jälkeinen migrate luo laajennuksen pääkäyttäjän alustustoiminnolla. Migraatio 0264 lisää sen jälkeen luodun vektorisarakkeen ja rakentaa indeksin. Sarakkeen lisäys kirjoittaa app.ai_chunk-taulun kerran uudelleen yksinomaisella lukolla, joten pohjustuspyynnöt odottavat sitä. Mikään muu ei käytä taulua.

Palvelimessa ilman pgvectoria migraatio 0264 kirjaa ilmoituksen eikä tee muutoksia, ja haku pysyy täsmällisenä. Jos pgvector on vanhempi kuin 0.8, sarake ja indeksi luodaan mutta haku pysyy täsmällisenä, kunnes laajennus päivitetään (alter extension vector update), sillä suodatetut HNSW-haut tarvitsevat version 0.8 iteratiivista hakua. Ota se myöhemmin käyttöön asentamalla laajennus ja suorittamalla alustustoiminto uudelleen (tai create extension vector pääkäyttäjänä) ja aja sitten quire_migrator-roolilla:

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

Toiminto on idempotentti ja palauttaa enabled tai unavailable. Suorita se myös jokaisessa omistetussa vuokraajatietokannassa.

Palautus aiempaan versioon

Koodin palauttaminen on aina mahdollista: aseta QUIRE_RELEASE aiempaan tunnisteeseen ja suorita up -d uudelleen. Tämä toimii, sillä skeema on yhteensopiva molempiin suuntiin saman julkaisun sisällä.

Skeeman palautusta ei tueta. Näitä muutoksia ei voi perua; palauta ne näin:

Siksi poistomigraatio toimitetaan yksinään: tietokannan palautuksella on silloin selkeä rajakohta.

Päivityksen tarkistus

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