Meningkatkan versi tanpa waktu henti

Aturannya ada di docs/architecture/23-ops.md bagian 7 dan docs/architecture/07-data.md bagian 4.1. Inilah prosedurnya.

Jaminan yang membuatnya aman

Rilis R berjalan dengan benar terhadap skema R dan skema R dikurangi satu. Setiap perubahan skema dibagi menjadi perluasan, transisi, dan kontraksi:

1. Perluasan: tambahkan kolom, tabel, atau indeks baru. Kode lama mengabaikannya.
2. Transisi, setidaknya selama satu rilis: kode baru menulis kedua bentuk dan membaca bentuk baru; tugas yang dapat dilanjutkan mengisi baris lama.
3. Kontraksi: hapus bentuk lama pada rilis berikutnya, tersendiri.

Dengan demikian, di setiap tahap peningkatan bertahap, proses lama dan baru dapat berbagi satu basis data. Tidak ada migration turun: migration yang menghapus kolom sejam lalu tidak dapat mengembalikan baris yang ditulis selama satu jam itu.

Tugas CI schema-compat memeriksa jaminan ini pada setiap rilis dengan menjalankan pengujian rilis sebelumnya terhadap skema baru.

Sebelum memulai

1. Baca catatan rilis. Rilis yang memerlukan jendela pemeliharaan akan menyatakannya beserta perkiraan waktu; paling banyak satu per rilis.
2. Jalankan uji pemulihan atau pastikan hasilnya berhasil untuk rilis ini (backup-restore.md). Uji yang gagal menghalangi peningkatan.
3. Ambil cadangan dasar: docker compose -f docker/compose.yaml --profile backup run --rm backup.

Docker Compose pada satu 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

Urutan ini disengaja:

1. Jalankan migration terlebih dahulu, saat rilis lama masih melayani trafik. Migration perluasan tidak terlihat olehnya.
2. Berikutnya web tier. Saat SIGTERM, setiap proses web mengubah /readyz menjadi draining, menyelesaikan permintaan aktif dalam 30 detik, menutup stream dengan petunjuk untuk menyambungkan ulang, lalu keluar. stop_grace_period memberi waktu 40 detik agar Compose tidak memotong proses pengurasan yang sehat.
3. Terakhir worker, agar bentuk peristiwa terbaru dihasilkan sebelum consumer terbaru mengharapkannya. Worker langsung berhenti mengambil tugas dan mendapat waktu 120 detik; tugas yang belum selesai diambil lagi oleh worker lain, aman karena setiap tugas idempoten. Scheduler menyerahkan kepemimpinan pada tick berikutnya.

Pada satu host, Compose mengganti container satu per satu sehingga tiap layanan mengalami jeda singkat. Agar tidak ada jeda sama sekali, jalankan dua container web tier di belakang proxy Anda (berkas override menambahkan layanan web kedua tanpa port publik), lalu buat ulang satu per satu dan tunggu masing-masing melaporkan status sehat sebelum melanjutkan.

Beberapa host atau orchestrator

Gunakan urutan yang sama: jalankan migration sekali dari satu tugas, lalu gulir web tier dengan surge satu dan unavailable nol, lalu worker. Arahkan readiness probe ke /readyz dan liveness probe ke /healthz.

Dengan basis data tenant khusus, langkah migrate melakukan dua hal: migrasi basis data kontrol terlebih dahulu, lalu setiap basis data dalam ops.tenant_database, satu per satu di bawah lock masing-masing. Kegagalan di satu basis data tenant tidak menghentikan yang lain. Setelah semua selesai, langkah ini membandingkan ledger migration dan keluar dengan status nonzero kecuali setiap basis data telah menerapkan migration yang persis sama dengan basis data kontrol; basis data yang tertinggal atau lebih maju disebutkan. Perintah yang sama memasang tabel antrean di setiap basis data karena worker mengambil tugas tenant yang dipatok di tempat tugas itu ditulis.

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

Setiap basis data khusus dijangkau melalui nama pendaftarannya. Basis data yang didaftarkan sebagai env:QUIRE_DB_NORTHWIND_URL memerlukan:

Basis data terdaftar tanpa koneksi _MIGRATOR dilaporkan gagal, bukan dilewati. Web tier dapat digulirkan setelah basis data kontrol selesai. Keterlambatan basis data tenant satu jam memicu peringatan; keterlambatan satu hari memicu halaman.

pgvector

Mulai migration 0264, korpus grounding menggunakan indeks HNSW pgvector jika server memiliki ekstensi tersebut; layanan Compose postgres dibangun dengannya (docker/postgres.Dockerfile). migrate pertama setelah image diganti membuat ekstensi melalui bootstrap superuser, lalu 0264 menambahkan kolom vector yang dihasilkan dan membangun indeks. Penambahan kolom menulis ulang app.ai_chunk sekali di bawah exclusive lock sehingga permintaan grounding menunggu; tidak ada proses lain yang menyentuh tabel tersebut.

Pada server tanpa pgvector, 0264 mencatat pemberitahuan tanpa mengubah apa pun dan pengambilan tetap eksak. Dengan pgvector yang lebih lama dari 0.8, kolom dan indeks tetap dibuat tetapi pengambilan tetap eksak sampai ekstensi ditingkatkan (alter extension vector update), karena pemindaian HNSW terfilter membutuhkan pemindaian iteratif versi 0.8. Untuk mengaktifkannya nanti pada server yang belum memilikinya, instal ekstensi, jalankan bootstrap lagi (atau create extension vector sebagai superuser), lalu sebagai quire_migrator:

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

Perintah ini idempoten dan mengembalikan enabled atau unavailable. Jalankan juga pada setiap basis data tenant khusus.

Melakukan rollback

Rollback kode selalu dapat dilakukan: tetapkan QUIRE_RELEASE ke tag sebelumnya lalu jalankan up -d lagi. Ini berfungsi karena skema kompatibel untuk kedua arah dalam satu rilis.

Rollback skema tidak disediakan. Berikut hal yang tidak dapat dibatalkan dan cara memulihkannya:

Itulah sebabnya migration kontraksi dikirim tersendiri: pemulihan memiliki batas yang jelas.

Memeriksa peningkatan

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