---
title: "Pag-upgrade nga walay downtime"
description: "I-upgrade ang self-hosted nga Quire nga walay downtime."
image: "https://docs.quirelms.com/og.png"
---

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

# Pag-upgrade nga walay downtime

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

Anaa ang mga lagda sa seksiyon 7 sa `docs/architecture/23-ops.md` ug seksiyon 4.1 sa `docs/architecture/07-data.md`. Mao kini ang pamaagi.

## Ang garantiya nga naghimo niini nga luwas <!--quire:the-guarantee-that-makes-it-safe-->

**Husto ang pagpadagan sa Release R sa schema R ug schema R minus one.** Bahinon ang matag kausaban sa schema ngadto sa expand, transition ug contract:

1. **Expand**: idugang ang bag-ong column, table o index. Dili kini tagdon sa karaang code.
2. **Transition**, sulod sa labing menos usa ka release: mosulat ang bag-ong code sa duha ka porma ug mobasa sa bag-o; pun-on pag-usab sa resumable job ang karaang mga row.
3. **Contract**: tangtangon ang karaang porma sa ulahing release, nga mao ra kini ang kausaban.

Busa sa matag higayon sa rolling upgrade, mahimong mogamit ang karaan ug bag-ong proseso sa usa ka database. Walay down migration: dili na maibalik sa migration nga mitangtang og column usa ka oras ang milabay ang mga row nga nasulat niadtong orasa.

Susiha sa CI job nga `schema-compat` kini nga garantiya sa matag release pinaagi sa pagpadagan sa mga test sa miaging release batok sa bag-ong schema.

## Sa dili pa magsugod <!--quire:before-you-start-->

1. Basaha ang release notes. Kon nagkinahanglan og maintenance window ang release, ipahibalo niini ang gibanabanang gidugayon; labing usa ra kada release.
2. Padagana ang restore drill, o pamatud-i nga malampuson kini niining release ([backup-restore.md](/ceb/ops/backup-restore/)). Makababag sa upgrade ang napakyas nga drill.
3. Paghimo og base backup: `docker compose -f docker/compose.yaml --profile backup run --rm backup`.

## Docker Compose, usa ka host <!--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
```

Tinuyo ang han-ay:

1. **Una ang migration**, samtang nagserbisyo pa sa trapiko ang karaang release. Dili makita niini ang expand migration.
2. **Sunod ang web tier.** Sa SIGTERM, usbon sa matag web process ang `/readyz` ngadto sa `draining`, humanon ang nagdagan nang mga request sulod sa 30 segundos, sirad-an ang stream nga adunay pahibalo sa pag-reconnect, ug mogawas. 40 segundos ang `stop_grace_period` aron dili putlon sa Compose ang himsog nga pag-drain.
3. **Kataposan ang mga worker**, aron mabuhat una ang pinakabag-ong event nga porma sa dili pa kini paabuton sa bag-ong consumer. Mohunong dayon sa pagkuha og trabaho ang mga worker ug adunay 120 segundos; kon dili mahuman ang usa ka job, kuhaon kini pag-usab sa laing worker. Luwas kini kay idempotent ang matag job. Itugyan sa scheduler ang pagpangulo sa sunod nga tick niini.

Sa usa ka host, pulihan sa Compose ang matag container sa tagsa-tagsa, busa adunay mubo nga paghunong kada service. Aron walay hunong, padagana ang web tier isip duha ka container luyo sa kaugalingon nimong proxy (pinaagi sa override file nga magdugang og ikaduhang web service nga walay published port), ug pulihi sila tagsa-tagsa. Hulata nga himsog ang matag usa sa dili pa ilisan ang sunod.

## Daghang host o orchestrator <!--quire:several-hosts-or-an-orchestrator-->

Gamita gihapon ang samang han-ay: padagana kausa ang migration isip usa ka job, dayon i-roll ang web tier nga surge usa ug unavailable zero, unya ang mga worker. Itudlo ang readiness probe sa `/readyz` ug ang liveness sa `/healthz`.

Kon adunay kaugalingong tenant database, buhaton sa lakang nga `migrate` ang duha: una i-migrate ang control database, unya tagsa-tagsa ang tanang database nga gilista sa `ops.tenant_database`, matag usa ubos sa kaugalingong lock. Dili mapahunong sa kapakyasan sa usa ka tenant database ang uban. Kon mahuman na ang tanang database, itandi niini ang migration ledger ug mogawas nga non-zero gawas kon parehas gayod ang mga migration sa matag database ug sa control database; nganlan niini ang matag database nga nahabilin o nauna. I-install usab sa samang command ang mga queue table sa matag database, kay didto kuhaon sa worker ang mga job sa naka-pin nga tenant diin kini gisulat.

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

Maabot ang matag kaugalingong database pinaagi sa ngalan nga girehistro niini. Kinahanglan sa database nga narehistro isip `env:QUIRE_DB_NORTHWIND_URL` ang mosunod:

| Variable | Gigamit para sa |
| --- | --- |
| `QUIRE_DB_NORTHWIND_URL` | Application role, para sa web tier ug worker |
| `QUIRE_DB_NORTHWIND_URL_MIGRATOR` | Migrator role, para niini nga command ug mga pagbalhin |
| `QUIRE_DB_NORTHWIND_URL_SUPERUSER` | Opsyonal: ipatuman pag-usab ang bootstrap (roles, schemas, helpers) sa dili pa mag-migrate |

Kon walay `_MIGRATOR` connection ang narehistrong database, ireport kini nga kapakyasan; dili kini laktawan. Mahimo nang i-roll ang web tier kon nahuman ang control database. Magpasidaan kon usa ka oras nga naulahi ang tenant database; magpage kon usa na ka adlaw.

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

Sugod sa migration 0264, mogamit ang grounding corpus og pgvector HNSW index kon anaa ang extension sa server; gitukod ang Compose `postgres` service uban niini (`docker/postgres.Dockerfile`). Sa unang `migrate` human mag-ilis og image, himoon ang extension pinaagi sa superuser bootstrap, unya magdugang ang 0264 og generated vector column ug magtukod sa index. Usbon kausa sa pagdugang sa column ang `app.ai_chunk` ubos sa exclusive lock, busa maghulat ang grounding request niini; walay laing mogamit sa maong table.

Kon walay pgvector sa server, mag-log og pahibalo ang 0264 ug walay usbon, ug magpabilin nga eksakto ang retrieval. Kon mas karaan sa 0.8 ang pgvector, matukod ang column ug index apan magpabiling eksakto ang retrieval hangtod ma-upgrade ang extension (`alter extension vector update`), kay nagkinahanglan og iterative scan sa 0.8 ang filtered HNSW scan. Aron ma-enable kini unya sa server nga wala pa niini, i-install ang extension, padagana pag-usab ang bootstrap (o `create extension vector` isip superuser), unya isip `quire_migrator`:

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

Idempotent kini ug mobalik og `enabled` o `unavailable`. Padagana usab kini sa matag kaugalingong tenant database.

## Pag-rollback <!--quire:rolling-back-->

Kanunayng mahimo ang pag-rollback sa **code**: itakda ang `QUIRE_RELEASE` sa miaging tag ug padagana pag-usab ang `up -d`. Molihok kini kay magkauyon ang schema sa duha ka direksiyon sulod sa usa ka release.

Dili itanyag ang pag-rollback sa **schema**. Mao kini ang mga dili na mabawi ug paagi sa pag-ayo:

| Dili na mabalik | Pagbawi |
| --- | --- |
| Contract migration nga nagtangtang og column | Point-in-time restore ngadto sa bag-ong database sa wala pa tangtanga, unya kuhaa ug i-merge ang datos |
| Kausaban sa datos nga gihimo diha-diha | Mao gihapon, unya ipahiuyon ang mga nasulat sukad niadto |
| Mga webhook ug event nga gipadala na | Mga event nga mokompensa, ayaw gayod og delete |
| Naipadalang email | Tawo ang mosulat sa tubag |
| Audit hash chain | Ayaw usba; idugang ang corrective entry |

Mao nga mag-inusara ang contract migration sa release: limpyo ang utlanan kon mag-restore.

## Pagsusi sa upgrade <!--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/ceb/ops/upgrade/index.mdx