Aġġornament mingħajr downtime

Ir-regoli jinsabu f’docs/architecture/23-ops.md sezzjoni 7 u docs/architecture/07-data.md sezzjoni 4.1. Din hija l-proċedura.

Il-garanzija li tagħmilha sigura

Release R taħdem korrettement kontra schema R u schema R nieqes waħda. Kull bidla tal-iskema tinqasam fi expand, transition u contract:

1. Expand: żid il-kolonna, it-tabella jew l-indiċi l-ġdid. Il-kodiċi l-qadim jinjoraha.
2. Transition, għal mill-inqas release waħda: il-kodiċi l-ġdid jikteb iż-żewġ forom u jaqra l-ġdida; xogħol li jista’ jitkompla jimla r-ringieli qodma.
3. Contract: armi l-forma l-qadima, f’release aktar tard, waħedha.

Għalhekk f’kull mument ta’ aġġornament rolling, proċessi qodma u ġodda jistgħu jaqsmu database waħda. M’hemm l-ebda migrazzjoni ’l isfel: migrazzjoni li armat kolonna siegħa ilu ma tistax trodd lura r-ringieli miktuba f’dik is-siegħa.

Ix-xogħol CI schema-compat jiċċekkja l-garanzija f’kull release billi jħaddem it-testijiet tar-release ta’ qabel kontra l-iskema l-ġdida.

Qabel ma tibda

1. Aqra n-noti tar-release. Release li teħtieġ tieqa ta’ manutenzjoni tgħid hekk, bl-istima; l-aktar waħda għal kull release.
2. Ħaddem id-drill tar-restore, jew ikkonferma li ħadem aħdar għal din ir-release (backup-restore.md). Drill fallut jimblokka l- aġġornament.
3. Ħu backup bażi: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose, host wieħed

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

L-ordni hija deliberata:

1. Emigra l-ewwel, waqt li r-release l-qadima sservi t-traffiku. Migrazzjonijiet Expand huma inviżibbli għaliha.
2. Il-livell web wara. Fuq SIGTERM kull proċess web idawwar /readyz għal draining, ilesti talbiet in-flight fi żmien 30 sekonda, jagħlaq streams b’ħjiel ta’ konnessjoni mill-ġdid, u joħroġ. stop_grace_period huwa 40 sekonda biex Compose qatt ma jaqta’ drain b’saħħtu.
3. Workers l-aħħar, biex il-forma tal-avveniment l-aktar ġdida tiġi prodotta qabel ma l-aktar ġdid konsumatur jistenniha. Workers jieqfu jġibu f’daqqa u jieħdu 120 sekonda; xogħol li ma jistax jispiċċa jerġa’ jinġieb x’imkien ieħor, li huwa sigur għax kull xogħol huwa idempotenti. L-iskedar jgħaddi t-tmexxija fid-dawra li jmiss tiegħu.

Fuq host wieħed, Compose jissostitwixxi kull container min-naħa tiegħu, għalhekk hemm vojt qasir għal kull servizz. Għal ebda vojt xejn, ħaddem il-livell web bħala żewġ containers wara il-proxy tiegħek (fajl override li jżid it-tieni servizz web mingħajr port ippubblikat), u oħloqhom mill-ġdid wieħed kull darba, tistenna lil kull wieħed jirrapporta b’saħħtu qabel li jmiss.

Diversi hosts jew orkestratur

Uża l-istess ordni: emigra darba minn xogħol wieħed, imbagħad dawwar il-livell web b’surge wieħed u mhux disponibbli żero, imbagħad il-workers. Indika sondi ta’ readiness lejn /readyz u liveness lejn /healthz.

B’databases dedikati tat-tenant, il-pass migrate jagħmel it-tnejn: jemigra id-database tal-kontroll l-ewwel, imbagħad kull database elenkata f’ ops.tenant_database, waħda kull darba, kull waħda taħt il-lock tagħha. Falliment f’ database waħda tat-tenant ma jwaqqafx lill-oħrajn. Meta kull database titlesta dan iqabbel il-ledgers tal-migrazzjoni u joħroġ non-zero sakemm kull database tkun applikat eżatt il-migrazzjonijiet li d-database tal-kontroll għandha, billi jsemmi kull waħda li hija wara jew quddiem. L-istess kmand jinstalla t-tabelli tal-queue f’kull database, għax il-worker jikkonsma x-xogħol ta’ tenant imwaħħal fejn kienu miktuba.

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

Il-migrazzjoni normali u s-setup tal-ewwel ġirja jinstallaw ukoll id-dokumenti legali Ingliżi kanoniċi tal-operatur Quire f’ops.platform_policy_version. L-installatur huwa idempotenti: il-korpi Ingliżi neqsin biss u preċiż il-korpi placeholder maħluqa mill-migrazzjoni jiġu sostitwiti. Iż-żrieragħ jiġu arkivjati u tiżdied verżjoni ppubblikata ġdida; ir-referenzi storiċi ta’ aċċettazzjoni u l-korpi jinżammu. Kwalunkwe verżjoni ġenwina miktuba mill-operatur, inkluż abbozz, tinżamm u trid tiġi mmaniġġjata permezz tal-console tal-Policies tal-pjattaforma. Id-dokumenti, il-verżjonijiet u l-kunsens tal-politiki tal-kerrej qatt ma jinbidlu b’din it-transizzjoni. Din hija pubblikazzjoni tat-test tal-operatur, mhux ċertifikazzjoni legali u lanqas twettiq awtomatiku tal-wegħdiet tiegħu.

Kull database dedikata tintlaħaq permezz tal-isem li hija rreġistrata taħtu. Database rreġistrata bħala env:QUIRE_DB_NORTHWIND_URL teħtieġ:

Database rreġistrata bla konnessjoni _MIGRATOR tiġi rrapportata bħala falliment, qatt skippjata. Il-livell web jista’ ddawwar ladarba d-database tal-kontroll titlesta. Database tat-tenant lura b’siegħa twissi; b’ġurnata tpeġġja.

pgvector

Mill-migrazzjoni 0264 il-corpus tal-grounding juża indiċi pgvector HNSW fejn is-server għandu l-estensjoni; is-servizz postgres ta’ Compose huwa mibni biha (docker/postgres.Dockerfile). L-ewwel migrate wara li tbiddel l-immaġnijiet toħloq l-estensjoni permezz tal-bootstrap tas-superuser, u 0264 imbagħad iżid kolonna vettorjali ġġenerata u tibni l-indiċi. Iż-żieda tal-kolonna terġa’ tikteb app.ai_chunk darba taħt lock esklussiva, biex talbiet ta’ grounding jistennewha; xejn ieħor ma jmiss dik it-tabella.

Fuq server mingħajr pgvector, 0264 jilloggja avviż u ma jbiddel xejn, u l-irkupru jibqa’ eżatt. B’pgvector anzjan minn 0.8 il-kolonna u l-indiċi jinbnew iżda l-irkupru jibqa’ eżatt sakemm l-estensjoni tiġi aġġornata (alter extension vector update), għax scans HNSW iffiltrati jeħtieġu scans iterattivi ta’ 0.8. Biex tattivaha aktar tard fuq server mingħajrha, installa l- estensjoni, ħaddem il-bootstrap mill-ġdid (jew create extension vector bħala superuser), imbagħad bħala quire_migrator:

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

Hija idempotenti u tirritorna enabled jew unavailable. Ħaddimha fuq kull database dedikata tat-tenant ukoll.

Treġġigħ lura

It-treġġigħ lura tal-kodiċi huwa dejjem disponibbli: issettja QUIRE_RELEASE għat- tag ta’ qabel u up -d mill-ġdid. Dan jaħdem għax l-iskema hija kompatibbli fiż-żewġ direzzjonijiet f’release.

It-treġġigħ lura tal-iskema mhuwiex offrut. Dak li ma jistax jitneħħa, u kif tirkupra minnu:

Għalhekk migrazzjoni contract tibgħat waħedha: restore imbagħad ikollu konfini nadif.

Kontroll tal-aġġornament

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