---
title: "Mmelite na-enweghị nkwụsị"
description: "Melite Quire ị na-elekọta n'onwe gị na-enweghị nkwụsị."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ig/llms.txt
> Use this file to discover all available pages before exploring further.

# Mmelite na-enweghị nkwụsị

<span id="upgrading-without-downtime"></span>

Iwu dị na `docs/architecture/23-ops.md` ngalaba 7 na
`docs/architecture/07-data.md` ngalaba 4.1. Nke a bụ usoro.

## Nkwa na-eme ka ọ dị nchebe <!--quire:the-guarantee-that-makes-it-safe-->

**Mwepụta R na-agba nke ọma megide schema R na schema R mwepu otu.**
A na-ekewa mgbanwe schema ọ bụla na expand, transition na contract:

1. **Expand**: tinye kọlụm, tebụl ma ọ bụ index ọhụrụ. Koodu ochie
   na-eleghara ya anya.
2. **Transition**, ma ọ dịkarịa ala otu mwepụta: koodu ọhụrụ na-ede ụdị
   abụọ ma na-agụ nke ọhụrụ; ọrụ a ga-aga n'ihu na-ejupụta ahịrị ochie.
3. **Contract**: tufuo ụdị ochie, na mwepụta ọzọ, naanị ya.

Ya mere n'oge ọ bụla nke mmelite na-aga n'ihu, usoro ochie na nke ọhụrụ
nwere ike ịkekọrịta otu nchekwa data. Enweghị mbugharị ala: mbugharị tufuru
kọlụm otu awa gara aga enweghị ike iweghachi ahịrị e dere n'awa ahụ.

Ọrụ CI `schema-compat` na-enyocha nkwa ahụ na mwepụta ọ bụla site n'ịgba ule
mwepụta gara aga megide schema ọhụrụ.

## Tupu ị malite <!--quire:before-you-start-->

1. Gụọ ndetu mwepụta. Mwepụta chọrọ windo mmezi na-ekwu ya, na ọnụ ọgụgụ;
   karịa otu kwa mwepụta adịghị.
2. Gbaa mmega ahụ iweghachi, ma ọ bụ kwado na ọ gara nke ọma maka mwepụta a
   ([backup-restore.md](/ig/ops/backup-restore/)). Mmega ahụ dara na-egbochi
   mmelite.
3. Were mbipụta ndabere mbụ: `docker compose -f docker/compose.yaml --profile backup
   run --rm backup`.

## Docker Compose, otu họst <!--quire:docker-compose-one-host-->

```sh
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
```

Usoro ahụ ezubere:

1. **Bugharịa nke mbụ**, mgbe mwepụta ochie na-enye okporo ụzọ. Mbugharị
   expand adịghị ahụ ya anya.
2. **Ọkwa weebụ na-esote.** Na SIGTERM usoro weebụ ọ bụla na-atụgharị
   `/readyz` na `draining`, na-emecha arịrịọ na-aga n'ime 30 sekọnd,
   na-emechi iyi na ntụnye ịjikọta ọzọ, wee pụọ. `stop_grace_period` bụ 40
   sekọnd ka Compose ghara ịbepụ mmiri dị mma.
3. **Workers n'ikpeazụ**, ka e mepụta ụdị ihe omume kachasị ọhụrụ tupu onye
   na-eri kachasị ọhụrụ atụ anya ya. Workers na-akwụsị iweta n'otu oge ma
   nweta 120 sekọnd; a na-eweta ọrụ na-enweghị ike ịgwụ ọzọ n'ebe ọzọ,
   nke dị nchebe n'ihi na ọrụ ọ bụla bụ idempotent. Onye nhazi oge
   na-enyefe iduzi na tick ya na-esote.

Na otu họst, Compose na-edochi akpa ọ bụla n'aka, ya mere enwere obere oghere
kwa ọrụ. Ka oghere ghara ịdị ma ọlị, gbaa ọkwa weebụ dịka akpa abụọ n'azụ
proxy nke gị (faịlụ override na-agbakwunye ọrụ weebụ nke abụọ na-enweghị
ọdụ ụgbọ ebipụtara), megharịakwa ha otu n'otu oge, na-echere ka nke ọ bụla
kọọ ahụike tupu nke na-esote.

## Ọtụtụ họst ma ọ bụ onye nhazi <!--quire:several-hosts-or-an-orchestrator-->

Jiri otu usoro: bugharịa otu ugboro site n'otu ọrụ, gbanweekwa ọkwa weebụ
na surge otu na unavailable efu, emesịa workers. Tụọ nyocha njikere na
`/readyz` na ndụ na `/healthz`.

Na nchekwa data tenant raara onwe ha, nzọụkwụ `migrate` na-eme ha abụọ: ọ
na-ebugharị nchekwa data njikwa nke mbụ, emesịa nchekwa data ọ bụla edepụtara
na `ops.tenant_database`, otu n'otu oge, nke ọ bụla n'okpuru mkpọchi nke ya.
Ọdịda na otu nchekwa data tenant anaghị akwụsị ndị ọzọ. Mgbe nchekwa data
ọ bụla gwụsịrị ọ na-atụnyere akwụkwọ mbugharị wee pụọ na-abụghị efu ma ọ
bụrụ na nchekwa data ọ bụla etinyeghị kpọmkwem mbugharị nchekwa data njikwa
tinyere, na-akpọ nke ọ bụla dị n'azụ ma ọ bụ n'ihu. Otu iwu ahụ na-etinye
tebụl queue na nchekwa data ọ bụla, n'ihi na worker na-eri ọrụ tenant a
tụkwasịrị ebe e dere ha.

```sh
bun apps/worker/src/migrate.ts   # what the Compose step runs
bun run db:migrate:all                            # the same, from a checkout
```
Mbugharị nkịtị na nhazi mbụ na-etinyekwa akwụkwọ iwu Bekee nke onye ọrụ Quire na `ops.platform_policy_version`. Onye nrụnye bụ idempotent: naanị ahụ Bekee na-efu na kpọmkwem ahụ nkwụnye nke mbugharị ahụ kụrụ ka a na-edochi. A na-edebe mkpụrụ ma tinye ụdị ọhụrụ e bipụtara; a na-echekwa nrụtụaka nnabata akụkọ ihe mere eme na ahụ. A na-echekwa ụdị ọ bụla ezigbo onye ọrụ dere, gụnyere draft, a ga-ejikwa ya site na console Amụma nke platform. Anaghị agbanwe akwụkwọ, ụdị na nkwenye nke amụma onye mgbazinye site na cutover a. Nke a bụ mbipụta ederede onye ọrụ, ọ bụghị asambodo iwu ma ọ bụ mezue nkwa ya na akpaghị aka.


A na-eru nchekwa data ọ bụla raara onwe ya site na aha edebanyere ya
n'okpuru. Nchekwa data edebanyere dịka `env:QUIRE_DB_NORTHWIND_URL` chọrọ:

| Mgbanwe | Eji maka |
| --- | --- |
| `QUIRE_DB_NORTHWIND_URL` | Ọrụ ngwa, maka ọkwa weebụ na worker |
| `QUIRE_DB_NORTHWIND_URL_MIGRATOR` | Ọrụ migrator, maka iwu a na maka mbugharị |
| `QUIRE_DB_NORTHWIND_URL_SUPERUSER` | Nhọrọ: na-etinye bootstrap ọzọ (roles, schemas, helpers) tupu ịbugharị |

A na-akọ nchekwa data edebanyere na-enweghị njikọ `_MIGRATOR` dịka ọdịda, a
naghị awụli ya. Ọkwa weebụ nwere ike ịgbanwe ozugbo nchekwa data njikwa
gwụsịrị. Nchekwa data tenant dị n'azụ otu awa na-adọ aka ná ntị; site n'otu
ụbọchị ọ na-akpọ.

## pgvector <!--quire:pgvector-->

Site na mbugharị 0264 corpus grounding na-eji index pgvector HNSW ebe sava
nwere extension; ọrụ Compose `postgres` e ji ya wuo
(`docker/postgres.Dockerfile`). `migrate` mbụ mgbe ịgbanwechara images
na-emepụta extension site na bootstrap superuser, 0264 emesịa tinye kọlụm
vector emepụtara wee wuo index. Ịtinye kọlụm na-edegharị `app.ai_chunk` otu
ugboro n'okpuru mkpọchi naanị ya, ya mere arịrịọ grounding na-echere ya;
ọ dịghị ihe ọzọ na-emetụ tebụl ahụ aka.

Na sava na-enweghị pgvector, 0264 na-edekọ ọkwa ma ọ dịghị agbanwe ihe,
nwetaghachi na-anọgide kpọmkwem. Na pgvector ochie karịa 0.8 a na-ewu kọlụm
na index mana nwetaghachi na-anọgide kpọmkwem ruo mgbe e melitere extension
(`alter extension vector update`), n'ihi na nyocha HNSW a nyochara chọrọ
nyocha iterative nke 0.8. Iji mee ya ma e mesịrị na sava na-enweghị ya,
wụnye extension, gbaa bootstrap ọzọ (ma ọ bụ `create extension vector` dịka
superuser), emesịa dịka `quire_migrator`:

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

Ọ bụ idempotent ma na-alaghachi `enabled` ma ọ bụ `unavailable`. Gbaa ya na
nchekwa data tenant ọ bụla raara onwe ya.

## Ịlaghachi azụ <!--quire:rolling-back-->

Ịlaghachi **koodu** dị mgbe niile: tọọ `QUIRE_RELEASE` na tag gara aga na
`up -d` ọzọ. Nke ahụ na-arụ ọrụ n'ihi na schema dabara n'ụzọ abụọ n'ime
mwepụta.

A naghị enye ịlaghachi **schema**. Ihe a na-enweghị ike ịmegharị, na otu
esi agbake na ya:

| Ihe na-agaghị agbanwe agbanwe | Mgbake |
| --- | --- |
| Mbugharị contract tufuru kọlụm | Iweghachi point-in-time tupu ntufu na nchekwa data ọhụrụ, wepụ, jikọta |
| Mgbanwe data n'ebe ya | Otu ihe ahụ, emesịa mezie ederede kemgbe |
| Webhook na ihe omume ezigara | Ihe omume nkwụghachi, ọ dịghị mgbe ihichapụ |
| Email ezigara | Mmadụ na-ede ihe na-esote |
| Agbụ hash nyocha | A naghị edegharị ya; tinye ndenye mmezi |

Ọ bụ ya mere mbugharị contract ji ebupu naanị ya: iweghachi emesịa nwere
oke dị ọcha.

## Inyocha mmelite <!--quire:checking-the-upgrade-->

```sh
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
```

Source: https://docs.quirelms.com/ig/ops/upgrade/index.mdx