Quireን ሳያቋርጡ ማሻሻል

ህጎቹ በdocs/architecture/23-ops.md ክፍል 7 እና በdocs/architecture/07-data.md ክፍል 4.1 ውስጥ ተገልጸዋል። ይህ የሚከተለው ሂደት ነው።

ደህንነቱን የሚያረጋግጠው ዋስትና

የR ልቀት ከR ስኪማና ከR ቀደም ባለው ስኪማ ጋር በትክክል ይሰራል። እያንዳንዱ የስኪማ ለውጥ በማስፋፋት፣ በሽግግርና በማጥበብ ደረጃዎች ይከፈላል፦

1. ማስፋፋት፦ አዲሱን አምድ፣ ሰንጠረዥ ወይም ኢንዴክስ ያክሉ። አሮጌው ኮድ ችላ ይለዋል።
2. ሽግግር፦ ቢያንስ ለአንድ ልቀት አዲሱ ኮድ ሁለቱንም ቅርጾች ይጽፋል፣ አዲሱንም ያነባል፤ ከቀድሞ ረድፎች ውሂብ ለመሙላት እንደገና ሊቀጥል የሚችል ስራ ይካሄዳል።
3. ማጥበብ፦ በኋለኛ ልቀት ውስጥ ብቻ አሮጌውን ቅርጽ ያስወግዱ።

ስለዚህ በማንኛውም ቀስ በቀስ ማሻሻያ ወቅት አሮጌና አዲስ ሂደቶች አንድ ውሂብ ጎታ ሊጋሩ ይችላሉ። ወደ ቀድሞ ስሪት የሚመልስ ማይግሬሽን የለም፤ ከአንድ ሰዓት በፊት አምድ የሰረዘ ማይግሬሽን በዚያ ሰዓት የተጻፉትን ረድፎች መመለስ አይችልም።

የschema-compat CI ስራ ይህን ዋስትና በእያንዳንዱ ልቀት ይፈትሻል፤ የቀደመውን ልቀት ሙከራዎች በአዲሱ ስኪማ ላይ ያስኬዳል።

ከመጀመርዎ በፊት

1. የልቀቱን ማስታወሻዎች ያንብቡ። የጥገና ጊዜ የሚፈልግ ልቀት ይህንና የሚጠበቀውን ጊዜ ይጠቅሳል፤ በአንድ ልቀት ከአንድ አይበልጥም።
2. የrestore ልምምዱን ያካሂዱ ወይም ለዚህ ልቀት በስኬት መጠናቀቁን ያረጋግጡ (backup-restore.md)። ያልተሳካ ልምምድ ማሻሻያውን ያግዳል።
3. መነሻ ምትኬ ይውሰዱ፦ docker compose -f docker/compose.yaml --profile backup run --rm backup።

Docker Compose፣ አንድ አገልጋይ

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. መጀመሪያ ማይግሬት ያድርጉ፣ አሮጌው ልቀት ትራፊክን እያገለገለ ሳለ። የማስፋፊያ ማይግሬሽኖች ለእሱ አይታዩም።
2. ቀጥሎ የድር ክፍሉን። SIGTERM ሲደርስ እያንዳንዱ የድር ሂደት /readyzን ወደ draining ይቀይራል፣ በሂደት ያሉ ጥያቄዎችን 30 ሰከንድ ውስጥ ያጠናቅቃል፣ ለድጋሚ ግንኙነት ምክር በመስጠት ዥረቶችን ይዘጋል፣ ከዚያም ይወጣል። stop_grace_period 40 ሰከንድ ስለሆነ Compose ጤናማ የማቆሚያ ሂደትን አያቋርጥም።
3. Workerዎችን በመጨረሻ። አዲሱ የክስተት ቅርጽ አዲሱ ተቀባይ ከመጠበቁ በፊት እንዲመረት። Workerዎች ማምጣትን ወዲያውኑ ያቆማሉ፣ 120 ሰከንድም ያገኛሉ፤ ያልተጠናቀቀ ስራ በሌላ ቦታ እንደገና ይወሰዳል፣ ይህም እያንዳንዱ ስራ idempotent ስለሆነ ደህና ነው። Scheduler በሚቀጥለው ዙር መሪነቱን ያስረክባል።

በአንድ አገልጋይ Compose ኮንቴይነሮችን በተራ ስለሚተካ ለእያንዳንዱ አገልግሎት አጭር ክፍተት ይኖራል። ምንም ክፍተት እንዳይኖር የድር ክፍሉን ከራስዎ proxy ጀርባ በሁለት ኮንቴይነሮች ያስኪዱ (ሁለተኛ web አገልግሎትን ያለ የውጭ ለደንበኛ የታተመ port የሚጨምር override ፋይል በመጠቀም)፣ አንዱን በአንድ ጊዜ ይፍጠሩ፣ ቀጣዩን ከመጀመርዎ በፊት ጤናማ መሆኑን ይጠብቁ።

ብዙ አገልጋዮች ወይም ኦርኬስትሬተር

ተመሳሳይ ቅደም ተከተል ይከተሉ፦ ከአንድ ስራ አንድ ጊዜ ማይግሬት ያድርጉ፣ ከዚያ የድር ክፍሉን በአንድ ተጨማሪ ኮንቴይነር እየጨመሩ ቀስ ብለው ያዘምኑ፣ ከዚያም workerዎችን። የreadiness ምርመራን /readyz ላይ፣ livenessን /healthz ላይ ያድርጉ።

የተለዩ የተከራይ ውሂብ ጎታዎች ሲኖሩ migrate ደረጃው ሁለቱንም ያደርጋል፤ መጀመሪያ የመቆጣጠሪያውን ውሂብ ጎታ፣ ከዚያ በops.tenant_database የተዘረዘሩትን ሁሉ አንድ በአንድ በራሳቸው lock ስር ያዘምናል። በአንዱ የተከራይ ውሂብ ጎታ ያለ ስህተት ሌሎቹን አያቆምም። ሁሉም ሲጠናቀቁ የማይግሬሽን መዝገቦችን ያነጻጽራል፤ የውሂብ ጎታዎቹ ከመቆጣጠሪያው የተለዩ ማይግሬሽኖችን ካደረጉ ወይም ካልደረሱበት ስማቸውን በመጥቀስ በስህተት ይወጣል። Worker የተከራይ ስራዎችን በተመደቡበት ውሂብ ጎታ ስለሚያነብ፣ ተመሳሳይ ትእዛዝ በእያንዳንዱ ውሂብ ጎታ queue ሰንጠረዦችንም ይጭናል።

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

እንደምሳሌ የሚሰረስ ማሸጋገሪያ እና የመጀመሪያ አሰላሽ አዘጋጅት የQuire ተጠቃሚውን ቀጥታ በእንግሊዝኛ የሆነ መረጃ ሰነዶችንም ወደ ops.platform_policy_version ያስገባሉ። መያዣው የራሱን መልስ የሚያደርግ ነው፦ የጠፉ አንግሊዝኛ ዝርዘር ጽሑፎች እና በትክክል ከማሸገጣቸው በተሆኑ ቦታ ሙያ ጽሑፎች ብቻ ይተካሉ። የማሸገጣቸው ግርቶች በማስቀመጥ ላይ ይጣራሉ እና አዲስ የተታተረ ዝርዝር ይገባል፤ የታሪክ የመቀበያ ማጣቀሻዎችና ጽሑፎች ይጠበቃሉ። በእውነት በተጠቃሚው የተጻፈ የማንኛውም ዝርዝር በላይነገር ከዚህ ስምትፍ ጨምሮ ተጠብቆ እንደነገር መቆጠሩ በፕላትፎም የመመሪያ ኮንሶል መስተናቀቅ ይገባል። የተከራይ የመመሪያ ሰነዶች፣ ዝርዝሮችና ፈቃድ በዚህ ማለዋወር ፈጽሞ አይቀየሩም። ይህ የተጠቃሚ ጽሑፍ ማሳተም ነው፤ ሕጋዊ ማረጋገጫ ወይም የተስተራሙ ደረጃዎችን በራሱ ማፈጸም አይደለም።

እያንዳንዱ የተለየ ውሂብ ጎታ በተመዘገበበት ስም ይደረስበታል። እንደ env:QUIRE_DB_NORTHWIND_URL የተመዘገበ ውሂብ ጎታ የሚከተሉትን ይፈልጋል፦

_MIGRATOR ግንኙነት የሌለው የተመዘገበ ውሂብ ጎታ እንደ ስህተት ይቆጠራል፤ ፈጽሞ አይዘለልም። የመቆጣጠሪያው ውሂብ ጎታ ከተጠናቀቀ በኋላ የድር ክፍሉ በቀስታ ሊዘመን ይችላል። የተከራይ ውሂብ ጎታ በአንድ ሰዓት ከዘገየ ማስጠንቀቂያ፣ በአንድ ቀን ከዘገየ ማንቂያ ይላካል።

pgvector

ከማይግሬሽን 0264 ጀምሮ grounding corpus አገልጋዩ extension ካለው የpgvector HNSW ኢንዴክስ ይጠቀማል፤ Compose postgres አገልግሎት ከእሱ ጋር ተሰርቷል (docker/postgres.Dockerfile)። ወደ አዲስ image ከተቀየሩ በኋላ የመጀመሪያው migrate extensionውን በsuperuser ማስነሻ ይፈጥራል፤ 0264 ደግሞ የተፈጠረ vector አምድና ኢንዴክሱን ይጨምራል። አምዱን መጨመር app.ai_chunkን አንድ ጊዜ በexclusive lock ይጽፋል፤ ስለዚህ grounding ጥያቄዎች ይጠብቃሉ፤ ሌላ ምንም ነገር ሰንጠረዡን አይነካም።

pgvector በሌለው አገልጋይ 0264 ማስታወሻ ይጽፋልና ምንም አይቀይርም፤ ፍለጋው ትክክለኛ ይቀጥላል። ከ0.8 የቆየ pgvector ላይ አምዱና ኢንዴክሱ ይገነባሉ፣ ግን ለተጣራ HNSW ፍለጋ የ0.8 ተደጋጋሚ ፍለጋ ስለሚያስፈልግ extensionው እስኪዘምን ድረስ ፍለጋው ትክክለኛ ይቀጥላል (alter extension vector update)። በኋላ ማንቃት ከፈለጉ extensionውን ይጫኑ፣ ማስነሻውን እንደገና ያስኪዱ (ወይም 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();

ይህ ተደጋጋሚ ሲሆን enabled ወይም unavailable ይመልሳል። በእያንዳንዱ የተከራይ ውሂብ ጎታ ላይም ያስኪዱት።

ወደ ቀድሞ ስሪት መመለስ

የኮድ መመለስ ሁልጊዜ ይቻላል፦ QUIRE_RELEASEን ወደ ቀደመው tag ያድርጉና up -dን እንደገና ያስኪዱ። በልቀቱ ውስጥ ስኪማው በሁለቱም አቅጣጫ ስለሚስማማ ይሰራል።

የስኪማ መመለስ አይደገፍም። የማይመለሱትና የማገገሚያ መንገዳቸው፦

ለዚህ ነው contract ማይግሬሽን ብቻውን የሚለቀቀው፤ ማገገሚያውም ግልጽ ድንበር አለው።

ማሻሻያውን መፈተሽ

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