ޑައުންޓައިމް ނެތި އަޕްގްރޭޑްކުރުން

ޤާއިދަތައް docs/architecture/23-ops.md ގެ 7 އަދި docs/architecture/07-data.md ގެ 4.1 ގައިވެއެވެ. މިއީ އެކްޝަން ޕްރޮސީޖަރެވެ.

މިގޮތަށް ސޭފް ވާ ގެރެންޓީ

Release R ހިންގާނީ schema R އާއި schema R އިން 1 މަތިވެ ކުޑަ ވަރޝަނަކުއެވެ. Schema ބަދަލު ތިން ފިޔަވަޅަކަށް ބަހާލައެވެ:

1. ބޮޑުކުރުން: އާ column، table ނުވަތަ index އެއް އިތުރުކުރުން. ކުރީގެ code އެއީ ނުބަލާނެއެވެ.
2. އަލުންތަބާވުން، އެންމެ ކުޑަ release އެއްގެ މުއްދަތަށް: އާ code އިން ދެ ފޯމު ލިޔެ، އާ އެއް ކިޔާއި، resumable job އެއްގައި ކުރީގެ row ތައް ފިލާކޮށްލާށެވެ.
3. ކޮންޓްރެކްޓް: ފަހު ރިލީޒެއްގައި ކުރީގެ ފޯމު ފޮހުން، ވަކިން.

އެހެންވެ rolling upgrade ގެ ކޮންމެ ވަގުތަކުވެސް، ކުރީގެ އަދި އާ process ތައް އެއް database އާއެކު ހިންގާނެއެވެ. ދައުން migration ނެތެވެ: ގަޑިއިރެއް ކުރިން column އެއް ފޮހި migration އެއް، އެ ގަޑިއިރު ލިޔެވި row ތައް އަނބުރާ ދޭނެއް ނޫނެވެ.

schema-compat CI job އިން ކޮންމެ release އެއްގައި ކުރީ release ގެ test ތައް އާ schema ގައި ހިންގައި މި ގެރެންޓީ ޗެކްކުރެއެވެ.

ފެށުމުގެ ކުރިން

1. Release notes ކިޔާށެވެ. maintenance window އެއް ބޭނުންވާ release އެއްގައި އޭގެ ގަޑި މިންވަރާއެކު ބުނެއެވެ؛ release އަކު އެންމެ އެއްފަހަރު.
2. Restore drill ހިންގާ، ނުވަތަ މި release އަށް green ކަމަށް ބަލާށެވެ (backup-restore.md). drill ފޭލްވިޔާ upgrade ބްލޮކް ކުރެވެއެވެ.
3. Base backup އެއް ނަގާށެވެ: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose، އެއް 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

މި އޯޑަރ ހަމަޖެހޭގޮތަށް ހޮވިފައިވެއެވެ:

1. ފުރަތަމަ migrate ކުރޭ، ކުރީގެ release ޓްރެފިކް ދައްކާމުން. Expand migration އެއް އޭނަށް ފެންނާނެއް ނޫނެވެ.
2. ދެން web tier. SIGTERM ލިބުމުން web process އެއް /readyz އަށް draining ކުރި، ހިންގަމުންދާ request 30 ސިކުންތުގައި ނިމައި، stream ތައް reconnect hint އާއެކު ނިންމައި، ކްލޯޒް ކުރެއެވެ. stop_grace_period 40 ސިކުންތު ކަމުން Compose ހެލްތީ drain އެއް ދަތިކޮށް ނުނިމޭނެއެވެ.
3. ފަހުން workers؛ އާ consumer އެދޭން ކުރިން އާ event shape އުފެއްދޭ. Workers ވަގުތުން fetch ހުއްޓާ، 120 ސިކުންތު ދެއެވެ؛ ނިމޭނެއް ނޫން job އެހެންތަނަކުން އަލުން fetch ވެ، ކޮންމެ job އެއް idempotent ކަމުން އެއީ ސޭފްވެއެވެ. Scheduler ދެން ހިންގޭ tick ގައި leadership ދެއެވެ.

އެއް host ގައި Compose ކޮންމެ container އެއްވެސް އެކަނި ބަދަލުކުރާތީ service އަކަށް ކުޑަ ގަޑި ގެއްލޭނެއެވެ. gap ނެތި ހިންގަން web tier ދެ container އަކަށް ތިބާގެ proxy ގެ ފަހަތުގައި ހިންގާ (އިތުރު web service އާއި އޭގެ published port ނެތި override file އެއް)، އެކަކަކު އަލުން ހަދާ، ދެންކުރާ ކުރިން ހެލްތީ ވާންދެން މެންޒާތެއް ކުރާށެވެ.

ގިނަ host ނުވަތަ orchestrator

އެއްގޮތް އޯޑަރ ބޭނުންކުރާށެވެ: އެއް job އަކުން އެއްފަހަރު migrate ކޮށް، web tier އަށް surge 1 އަދި unavailable 0 އަކަށް އައިސް، ދެން workers. Readiness probe ތައް /readyz އަށް، liveness ތައް /healthz އަށް ދާގޮތަށް ސެޓްކުރާށެވެ.

Dedicated tenant database ތަކާއެކު migrate އިން ދެކަންވެސް ކުރެއެވެ: ފުރަތަމަ control database މަތިން، ދެން ops.tenant_database ގައި ލިސްޓް ކުރެވިފައި ހުރި ކޮންމެ database އެއް، އެކްލޮކްކޮށް، ވަކިވަކިން. tenant database އެއްގެ ފޭލިއަރއަކުން އެހެން ތަކެއްޗެއް ހުއްޓާނެއް ނޫނެވެ. ހުރިހާ database ނިމުމުން migration ledger ތައް ކޮމްޕޭރކޮށް، ކޮންމެ database އެއް control database އާއި ހަމަ migration ތައް އެޕްލައި ނުކުރިޔާ non-zero އިން ނިމެ، ކާކު ކުރި ނުވަތަ ފަހު ހުރިތޯ ނަންދެއެވެ. އެ command އިން ކޮންމެ database އަކުގައި queue table އިންސްޓޯލްކުރެއެވެ؛ worker އިން pinned tenant ގެ job ތައް ލިޔިފައިވާ database އަކުން ނަގައެވެ.

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

ކޮންމެ dedicated database އެއް ހޯދަނީ އޭނާ register ކުރި ނަމަކުންނެވެ. env:QUIRE_DB_NORTHWIND_URL ގޮތުގައި ރަޖިސްޓަރކުރި database އަކަށް:

_MIGRATOR connection ނެތް ރަޖިސްޓަރ ކުރި database އެއް failure ކަމަށް report ކުރެވެއެވެ، ދޫކުރެވޭނެއް ނޫނެވެ. Control database ނިމުމުން web tier roll ކުރެވޭނެއެވެ. ގަޑިއެއް ފަހުވި tenant database އެއް ވާނިން ދެއެވެ؛ ދުވަހެއްވިއްޔާ page ކުރެއެވެ.

pgvector

Migration 0264 އިން grounding corpus އަށް pgvector HNSW index ބޭނުންކުރެއެވެ؛ server އަށް extension ހުރިނަމަ. Compose postgres service އަކުން އެއާއެކު build ކުރެއެވެ (docker/postgres.Dockerfile). އިމޭޖް ބަދަލުކުރި ފަހުން ފުރަތަމަ migrate އިން superuser bootstrap އިން extension ހަދައި، 0264 އިން generated vector column އަދި index އެއް އިތުރުކުރެއެވެ. އެ column އިތުރުކުރުމުން app.ai_chunk އެއްފަހަރު exclusive lock ދަށުން rewrite ވާތީ grounding request ތައް އޭގެ ބެރުގައި ތިބޭނެއެވެ؛ އެ table އާ އެހެން ކަމެއް ނުކުރެއެވެ.

pgvector ނެތް server އެއްގައި 0264 އިން notice log ކޮށް އެއްވެސް ނުބަދަލުކޮށް retrieval exact ގައި ދެމިތިބެއެވެ. pgvector 0.8 އިން ކުޑަ server އެއްގައި column އަދި index ހަދާ، އެ extension upgrade ވާންދެން retrieval exact އަށްވެސް ދެމިތިބެއެވެ (alter extension vector update)؛ filtered HNSW scan ތަކަށް 0.8 ގެ iterative scan ތައް ބޭނުންވެއެވެ. މިފަހަރަކު extension ނެތް server އެއްގައި އެއީ ހުޅުވަން، extension އިންސްޓޯލްކޮށް bootstrap އަލުން ހިންގާ (ނުވަތަ superuser ކަމުގައި create extension vector)، ދެން quire_migrator ގޮތުގައި:

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

Idempotent އެވެ، enabled ނުވަތަ unavailable ރިޓަރންކުރެއެވެ. ކޮންމެ dedicated tenant database އަކުގައިވެސް ހިންގާށެވެ.

ރޯލްބެކް ކުރުން

Code ރޯލްބެކް ކޮންމެއިރަކުވެސް ކުރެވޭނެއެވެ: QUIRE_RELEASE ކުރީ tag އަށް ސެޓްކޮށް up -d އަލުން ކުރާށެވެ. Release އެއްގެ ތެރޭގައި schema ދިމާތައް އެއްގޮތް ކަމުން މިއީ ހިންގައެވެ.

Schema ރޯލްބެކް ކުރެވޭނެ ގޮތެއް ނެތެވެ. އަނބުރާ ނުކުރެވޭ ކަންކަން އަދި އޭގެ ޙައްލު:

އެހެންވެ contract migration އެއް އެކަނި ޝިޕްކުރެވެނީ: ދެން restore ކުރާއިރު ސާފު ބޯޑަރީއެއް ހުންނާނެތީއެވެ.

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