বন্ধ নকৰাকৈ আপগ্ৰেড

নিয়মসমূহ docs/architecture/23-ops.mdৰ section 7 আৰু docs/architecture/07-data.mdৰ section 4.1-ত। এইটোৱেই পদ্ধতি।

ইয়াক নিৰাপদ কৰা নিশ্চয়তা

Release R-এ schema R আৰু schema R minus one-ৰ সৈতে সঠিকভাৱে চলে। প্ৰতিটো schema পৰিৱৰ্তন expand, transition আৰু contract-ত ভাগ হয়:

1. Expand: নতুন column, table বা index যোগ কৰক। পুৰণি code-এ ইয়াক উপেক্ষা কৰে।
2. Transition, অন্ততঃ এটা release-লৈ: নতুন code-এ দুয়ো format লিখে আৰু নতুনটো পঢ়ে; resumable job-এ পুৰণি row backfill কৰে।
3. Contract: পিছৰ release-ত অকলে পুৰণি format drop কৰক।

সেয়ে rolling upgrade-ৰ প্ৰতিটো মুহূৰ্তত পুৰণি আৰু নতুন process-এ এটা database share কৰিব পাৰে। Down migration নাই: এঘণ্টা আগতে column drop কৰা migration-এ সেই এঘণ্টাত লিখা row ঘূৰাই আনিব নোৱাৰে।

schema-compat CI job-এ প্ৰতিটো release-ত আগৰ release-ৰ test নতুন schema-ৰ ওপৰত চলাই এই নিশ্চয়তা পৰীক্ষা কৰে।

আৰম্ভ কৰাৰ আগতে

1. Release note পঢ়ক। Maintenance window লাগে এনে release-এ estimate-সহ কয়; প্ৰতিটো release-ত সৰ্বাধিক এটা।
2. Restore drill চলাওক অথবা এই release-ৰ বাবে সফল হৈছে বুলি নিশ্চিত কৰক (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-এ traffic serve কৰি থাকোঁতে। Expand migration ইয়াৰ বাবে অদৃশ্য।
2. তাৰ পিছত web tier। SIGTERM-ত প্ৰতিটো web process-এ /readyzক draining কৰে, ইতিমধ্যে চলা request 30 ছেকেণ্ডৰ ভিতৰত শেষ কৰে, reconnect hint-সহ stream বন্ধ কৰি exit কৰে। stop_grace_period 40 ছেকেণ্ড, যাতে Compose-এ সুস্থ drain কেতিয়াও নকাটে।
3. শেষত worker, যাতে নতুনতম event format-টো consumer-এ আশা কৰাৰ আগতে সৃষ্টি হয়। Worker-এ নতুন কাম fetch কৰা তৎক্ষণাত বন্ধ কৰি 120 ছেকেণ্ড পায়; শেষ কৰিব নোৱাৰা job আন ঠাইত পুনৰ fetch হয়, প্ৰতিটো job idempotent হোৱা বাবে নিৰাপদ। Scheduler-এ পৰৱৰ্তী tick-ত leadership হস্তান্তৰ কৰে।

এটা host-ত Compose-এ প্ৰতিটো container এটাকৈ সলনি কৰে, সেয়ে প্ৰতিটো service-ত চুটি gap থাকে। একেবাৰে gap নোহোৱাকৈ চলাবলৈ web tier-টো নিজৰ proxy-ৰ পিছত দুটা container হিচাপে চলাওক (published port নথকা দ্বিতীয় web service যোগ কৰা override file-ৰে) আৰু এটাকৈ recreate কৰি পৰৱৰ্তীটো কৰাৰ আগতে সুস্থ বুলি নিশ্চিত কৰক।

কেইবাটাও host বা orchestrator

একেই ক্ৰম: এটা job-ৰে এবাৰ migrate কৰি web tier surge one আৰু unavailable zero-ৰে roll কৰক, তাৰ পিছত worker। Readiness probe /readyzলৈ আৰু liveness probe /healthzলৈ দিয়ক।

Dedicated tenant database-সহ, migrate step-এ দুয়ো কৰে: প্ৰথমে control database, তাৰ পিছত ops.tenant_databaseত তালিকাভুক্ত প্ৰতিটো database নিজা lock-ৰ অধীনত এটাকৈ migrate কৰে। এটা tenant database-ত বিফলতাই আনবোৰ নৰখে। সকলো database শেষ হ’লে migration ledger তুলনা কৰি control database-ত প্ৰয়োগ কৰা migration-ৰ সৈতে প্ৰতিটো database হুবহু মিলা নহ’লে non-zero exit কৰে, পিছত বা আগত থকাটো নামসহ কয়। Worker-এ pinned tenant-ৰ job লিখা database-তে consume কৰে বাবে প্ৰতিটো database-ত queue table-ও এই command-এ install কৰে।

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

সাধাৰণ মাইগ্ৰেশন আৰু প্ৰথম-পৰা সেটআপেও ops.platform_policy_version লৈ কেনেকীয়া ইংৰাজী Quire অপাৰেটৰৰ আইনি নথিসমূহ স্থাপন কৰে। ইন্ষ্টলাৰটো idempotent: কেৱল অনুপস্থিত ইংৰাজী body আৰু মাইগ্ৰেশনে seed কৰা ঠিক প্লেসহোল্ডাৰ body সহ কেৱলেই সলনি কৰা হয়। Seedসমূহ archive কৰা হয় আৰু নতুন প্ৰকাশিত version সংযোজন কৰা হয়; ইতিহাসৰ গ্ৰহণ সুত্ৰতা আৰু bodyসমূহ ধৰি ৰাখা হয়। অপাৰেটৰে সত্যিই লিখা যিকোনো version, draft সহ, সংৰক্ষিত থাকে আৰু ইয়াক প্লেটফৰ্মৰ নীতি কন্সোলৰ দ্বাৰা পৰিচালনা কৰিব লাগে। এই cutoverৰে tenant ৰ নীতি নথি, version আৰু সম্মতি কেতিয়াও সলনি কৰা হয় নাই। এইখন অপাৰেটৰৰ লেখা প্ৰকাশ, আইনগত স্বীকৃতি নহয় বা ইয়াৰ প্ৰতিশ্ৰুতিসমূহ স্বয়ংক্ৰিয়ভাৰে পূৰণ নহয়।

প্ৰতিটো dedicated database register কৰা নামৰে পোৱা যায়। env:QUIRE_DB_NORTHWIND_URL হিচাপে register কৰা database-ৰ বাবে লাগে:

_MIGRATOR connection নথকা registered database-এ skip নহয়, failure report হয়। Control database শেষ হ’লেই web tier roll কৰিব পাৰে। এঘণ্টা পিছত থকা tenant database-এ warning দিয়ে; এদিন হ’লে page কৰে।

pgvector

Migration 0264-ৰ পৰা server-ত extension থাকিলে grounding corpus-এ pgvector HNSW index ব্যৱহাৰ কৰে; Compose-ৰ postgres service-ত ইয়াক build কৰা হয় (docker/postgres.Dockerfile)। Image সলনিৰ পিছত প্ৰথম migrate-এ superuser bootstrap-ৰে extension সৃষ্টি কৰে; তাৰ পিছত 0264-এ generated vector column যোগ কৰি index build কৰে। Column যোগ কৰোঁতে app.ai_chunk exclusive lock-ৰ অধীনত এবাৰ rewrite হয়, সেয়ে grounding request অপেক্ষা কৰে; আন একোৱে সেই table নুচুৱে।

pgvector নথকা server-ত 0264-এ notice log কৰি একো নসলায়, retrieval exact-য়েই থাকে। 0.8তকৈ পুৰণি pgvector-ত column আৰু index build হয়, কিন্তু extension upgrade নকৰালৈ retrieval exact থাকে (alter extension vector update), কাৰণ filtered HNSW scan-ৰ বাবে 0.8-ৰ iterative scan লাগে। পিছত ইয়াক সক্ৰিয় কৰিবলৈ extension install কৰি 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-তো চলাওক।

Rollback

Code rollback সদায় সম্ভৱ: QUIRE_RELEASE আগৰ tag-ত দি পুনৰ up -d চলাওক। Release-ৰ ভিতৰত schema দুয়ো দিশত compatible হোৱা বাবে চলে।

Schema rollback দিয়া নহয়। যিবোৰ undo নহয় আৰু পুনৰুদ্ধাৰৰ উপায়:

সেইবাবেই contract migration অকলে ship হয়: 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