बिना downtime अपग्रेड करना

नियम docs/architecture/23-ops.md के अनुभाग 7 और docs/architecture/07-data.md के अनुभाग 4.1 में हैं। यह प्रक्रिया है।

सुरक्षा की गारंटी

रिलीज़ R schema R और schema R minus one पर सही चलती है। हर schema बदलाव को विस्तार, संक्रमण और संकुचन में बाँटा जाता है:

1. विस्तार: नया कॉलम, टेबल या इंडेक्स जोड़ें। पुराना कोड उसे नज़रअंदाज़ करता है।
2. संक्रमण, कम-से-कम एक रिलीज़ तक: नया कोड दोनों रूप लिखता है और नया पढ़ता है; दोबारा जारी किया जा सकने वाला job पुराने rows भरता है।
3. संकुचन: बाद की रिलीज़ में, अकेले पुराने रूप को हटाएँ।

इसलिए क्रमिक अपग्रेड के हर पल पुराने और नए processes एक database साझा कर सकते हैं। Down migrations नहीं होतीं: एक घंटे पहले कॉलम हटाने वाला migration उस घंटे लिखी rows वापस नहीं ला सकता।

हर रिलीज़ पर schema-compat CI job पिछली रिलीज़ के tests नए schema पर चलाकर गारंटी जाँचता है।

शुरू करने से पहले

1. Release notes पढ़ें। Maintenance window चाहिए तो रिलीज़ अनुमान सहित बताती है; प्रति रिलीज़ अधिकतम एक।
2. Restore drill चलाएँ, या पुष्टि करें कि यह रिलीज़ हरे नतीजे से गुज़री (backup-restore.md)। असफल drill अपग्रेड रोकता है।
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 करें, जब पुरानी रिलीज़ traffic दे रही हो। वह विस्तार migration नहीं देखती।
2. फिर web tier। SIGTERM पर हर web process /readyz को draining करता है, 30 सेकंड के भीतर जारी requests पूरी करता है, reconnect hint के साथ streams बंद करता है और बाहर निकलता है। stop_grace_period 40 सेकंड है, इसलिए Compose स्वस्थ drain नहीं काटता।
3. आख़िर में Workers, ताकि नया consumer उम्मीद करे उससे पहले नया event रूप पैदा हो जाए। Workers तुरंत fetch करना रोककर 120 सेकंड पाते हैं; पूरा न होने वाला job कहीं और फिर fetch होता है, जो सुरक्षित है क्योंकि हर job idempotent है। अगली tick पर scheduler leadership सौंपता है।

एक host पर Compose हर container को बारी-बारी बदलता है, इसलिए हर service में थोड़ी रुकावट आती है। बिल्कुल बिना रुकावट के, अपने proxy के पीछे web tier दो containers में चलाएँ (override file में प्रकाशित port के बिना दूसरा web service जोड़ें), फिर एक समय में एक को फिर बनाएँ और अगले से पहले हर एक के स्वस्थ होने की प्रतीक्षा करें।

कई hosts या orchestrator

वही क्रम अपनाएँ: एक job से एक बार migrate करें, फिर surge एक और unavailable शून्य के साथ web tier क्रमशः बदलें, फिर workers। Readiness probe /readyz और liveness probe /healthz पर रखें।

समर्पित tenant databases हों तो migrate चरण दोनों काम करता है: पहले control database और फिर ops.tenant_database में सूचीबद्ध हर database को अलग lock के तहत बारी-बारी migrate करता है। एक tenant database की विफलता बाकी को नहीं रोकती। सभी database पूरे होने पर migration ledger की तुलना होती है; हर database में control database जितने ही migrations लागू न हों तो यह गैर-शून्य status से निकलता है और पीछे या आगे हर database का नाम देता है। वही command हर database में queue tables भी install करता है, क्योंकि worker उस pinned tenant के jobs वहीं से लेता है जहाँ वे लिखे गए थे।

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

हर समर्पित database को उसके registered नाम से पाया जाता है। env:QUIRE_DB_NORTHWIND_URL के रूप में registered database को चाहिए:

_MIGRATOR connection के बिना registered database को विफल बताया जाता है, कभी छोड़ा नहीं जाता। Control database पूरा हो तो web tier क्रमशः बदल सकता है। एक घंटे पीछे tenant database चेतावनी देता है; एक दिन पीछे हो तो पेजर बजता है।

pgvector

Migration 0264 से जहाँ server में extension है वहाँ grounding corpus pgvector HNSW index इस्तेमाल करता है; Compose की postgres service उसी के साथ बनी है (docker/postgres.Dockerfile)। Images बदलने के बाद पहला migrate superuser bootstrap से extension बनाता है और 0264 generated vector column जोड़कर index बनाता है। Column जोड़ना exclusive lock में app.ai_chunk को एक बार फिर लिखता है, इसलिए grounding requests प्रतीक्षा करती हैं; वह table कोई और नहीं छूता।

pgvector के बिना server पर 0264 सूचना log करके कुछ नहीं बदलता और retrieval सटीक रहता है। 0.8 से पुराने pgvector में column और index बनते हैं, मगर extension अपडेट होने तक retrieval सटीक रहता है (alter extension vector update), क्योंकि filter वाले HNSW scan में 0.8 के iterative scans चाहिए। बाद में ऐसे server पर इसे चालू करने के लिए 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 लौटाता है। हर समर्पित tenant database पर भी चलाएँ।

वापस लौटना

Code वापस करना हमेशा उपलब्ध है: QUIRE_RELEASE को पिछला tag देकर फिर up -d चलाएँ। यह काम करता है क्योंकि रिलीज़ के भीतर दोनों दिशाओं में schema संगत है।

Schema वापस करने का विकल्प नहीं है। क्या पूर्ववत नहीं हो सकता और उससे कैसे उबरें:

इसीलिए contract migration अकेली भेजी जाती है: restore की सीमा साफ़ रहती है।

अपग्रेड जाँचना

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