---
title: "Aghjurnà senza interruzzione"
description: "Aghjurnate Quire autugestionatu senza interruzzione."
image: "https://docs.quirelms.com/og.png"
---

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

# Aghjurnà senza interruzzione

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

E regule si trovanu in a sezzione 7 di `docs/architecture/23-ops.md` è
in a sezzione 4.1 di `docs/architecture/07-data.md`. Eccu a prucedura.

## A garanzia chì rende sicuru l'aghjurnamentu <!--quire:the-guarantee-that-makes-it-safe-->

**A versione R funziona currettamente cù u schema R è u schema R menu unu.** Ogni
cambiamentu di schema hè spartutu in espansione, transizione è cuntrazione:

1. **Espansione**: aghjunghje a nova culonna, tavula o indice. U codice vechju ùn ne tene contu.
2. **Transizione**, per almenu una versione: u codice novu scrive e duie forme è
   leghje a nova; un travagliu ripigliabile riempie i filari vechji.
3. **Cuntrazione**: sguassà a forma vechja, in una versione dopu, da sola.

Cusì in ogni mumentu d'un aghjurnamentu progressivu, i prucessi vechji è novi ponu sparte una
basa di dati. Ùn ci sò micca migrazioni di ritornu: una migrazione chì hà sguassatu una culonna
un'ora fà ùn pò restituisce i filari scritti in quell'ora.

U travagliu CI `schema-compat` verifica sta garanzia à ogni versione eseguendu
i testi di a versione precedente contr'à u schema novu.

## Nanzu di principià <!--quire:before-you-start-->

1. Leghjite e note di versione. Una versione chì hà bisognu d'una finestra di mantenimentu l'indica,
   cù a stima; à u più una per versione.
2. Eseguite a prova generale di risturazione, o cunfirmate ch'ella hè passata per sta versione
   ([backup-restore.md](/co/ops/backup-restore/)). Una prova fallita impedisce l'
   aghjurnamentu.
3. Fate una copia di salvezza di basa: `docker compose -f docker/compose.yaml --profile backup
   run --rm backup`.

## Docker Compose, un 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
```

L'ordine hè intenzionale:

1. **Migrà prima**, mentre a versione vechja serve u trafficu. E migrazioni d'espansione
   ùn li sò visibili.
2. **Dopu u nivellu web.** À SIGTERM ogni prucessu web mette `/readyz` à
   `draining`, compie e dumande in corsu in 30 seconde, chjude i flussi
   cù una indicazione di ricunnessione, è esce. `stop_grace_period` hè 40 seconde cusì
   Compose ùn interrompe mai una chjusura sana.
3. **I worker à a fine**, affinchì a forma nova di l'avvenimentu sia prodotta prima chì u novu
   cunsumatore l'aspetti. I worker smettenu subitu di piglià travagli è anu 120 seconde;
   un travagliu chì ùn si pò compie hè ripigliatu in un altru locu, ciò chì hè sicuru perchè
   ogni travagliu hè idempotente. U scheduler cede a direzzione à a so prossima
   battuta.

Nant'à un host, Compose rimpiazza ogni cuntainer à turnu, dunque ci hè una corta interruzzione
per serviziu. Per ùn avè nisuna interruzzione, eseguite u nivellu web cum'è dui cuntainer daretu à
u vostru proxy (un schedariu di override chì aghjusta un secondu serviziu web senza
portu publicatu), è ricreate li unu à volta, aspettendu chì ognunu indichi ch'ellu hè
sanu prima di passà à u prossimu.

## Parechji host o un orchestratore <!--quire:several-hosts-or-an-orchestrator-->

Aduprate u listessu ordine: migrà una volta da un travagliu unicu, dopu aghjurnà u nivellu web
cù un surplus di unu è zero indisponibili, dopu i worker. Puntate e sonde di prontezza
à `/readyz` è quelle di salute à `/healthz`.

Cù basi di dati dedicate à tenant, u passu `migrate` face tramindui: migra
prima a basa di cuntrollu, dopu ogni basa elencata in
`ops.tenant_database`, una per volta, ognuna cù u so propiu serrame. Un fallimentu in
una basa di tenant ùn impedisce micca l'altre. Quandu tutte e basi sò pronte, paraguneghja i registri di migrazione è esce cù un codice micca zeru à menu chì ogni basa abbia
applicatu esattamente e stesse migrazioni chè a basa di cuntrollu, indicendu ognuna chì hè
in ritardu o in anticipu. U listessu cumandu installa e tavule di fila in ogni
basa, perchè u worker cunsuma i travagli di un tenant fissatu in u locu induve sò
stati scritti.

```sh
bun apps/worker/src/migrate.ts   # what the Compose step runs
bun run db:migrate:all                            # the same, from a checkout
```
A migrazione nurmale è a prima installazione mettenu dinù i ducumenti ghjuridichi inglesi canonichi di l'operatore Quire in `ops.platform_policy_version`. L'installatore hè idempotente: solu i testi inglesi mancanti è i testi provvisori sementati da a migrazione sò rimpiazzati. E sementi sò archiviate è una nova versione publicata hè aghjunta; i riferimenti storichi d'accettazione è i testi fermanu. Ogni versione scritta da l'operatore, ancu una bozza, hè cunservata è deve esse gestita da a console Pulitiche di a piattaforma. I ducumenti, e versione è u cunsensu di e pulitiche di i tenant ùn cambianu mai cù stu passaghju. Hè a publicazione di u testu di l'operatore, micca una certificazione ghjuridica nè l'esecuzione automatica di e so prumesse.


Ogni basa dedicata hè accessuta per mezu di u nome cù u quale hè registrata.
Una basa registrata cum'è `env:QUIRE_DB_NORTHWIND_URL` hà bisognu di:

| Variabile | Aduprata per |
| --- | --- |
| `QUIRE_DB_NORTHWIND_URL` | U rollu di l'applicazione, per u nivellu web è u worker |
| `QUIRE_DB_NORTHWIND_URL_MIGRATOR` | U rollu di migratore, per stu cumandu è per i spiazzamenti |
| `QUIRE_DB_NORTHWIND_URL_SUPERUSER` | Facultativu: riapplica l'inizializazione (rolli, schemi, aiuti) prima di migrà |

Una basa registrata senza cunnessione `_MIGRATOR` hè signalata cum'è fallimentu,
mai saltata. U nivellu web pò esse aghjurnatu una volta chì a basa di cuntrollu hè pronta. Una
basa di tenant in ritardu d'un'ora avverte; d'un ghjornu manda una alerta urgente.

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

Da a migrazione 0264, u corpus di fundamentazione usa un indice HNSW di pgvector induve
u servitore hà l'estensione; u serviziu Compose `postgres` hè custruitu cù
ella (`docker/postgres.Dockerfile`). U primu `migrate` dopu à cambià
l'imagine crea l'estensione via l'inizializazione di superuser, è dopu 0264
aghjusta una culonna vettoriale generata è custruisce l'indice. L'aghjunta di a culonna
riscrive `app.ai_chunk` una volta sottu à un serrame esclusivu, dunque e dumande di
fundamentazione aspettanu; nunda altru tocca quella tavula.

Nant'à un servitore senza pgvector, 0264 scrive un avvisu è ùn cambia nunda, è
u recuperu ferma esattu. Cù una versione di pgvector più vechja chè 0.8, a culonna è l'indice sò creati ma u recuperu ferma esattu finu à aghjurnà
l'estensione (`alter extension vector update`), perchè e ricerche HNSW filtrate anu bisognu di e ricerche iterative di 0.8. Per attivà la dopu nant'à un servitore senza ella, installate l'
estensione, rieseguite l'inizializazione (o `create extension vector` cum'è
superuser), dopu cum'è `quire_migrator`:

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

Hè idempotente è restituisce `enabled` o `unavailable`. Eseguite lu ancu nant'à ogni
basa di dati dedicata à tenant.

## Ritornu à a versione precedente <!--quire:rolling-back-->

U ritornu **di codice** hè sempre pussibule: stabilite `QUIRE_RELEASE` à a
etichetta precedente è eseguite torna `up -d`. Funziona perchè u schema hè cumpatibile
in e duie direzzioni dentru una versione.

U ritornu **di schema** ùn hè micca prupostu. Ciò chì ùn si pò annullà, è cumu
ricuperà ne:

| Micca riversibile | Ripresa |
| --- | --- |
| Una migrazione di cuntrazione chì hà sguassatu una culonna | Risturà à un puntu in u tempu prima di a cancellazione in una nova basa, estrarre, unisce |
| Un cambiamentu di dati in u locu | Listessu, dopu cuncilià e scritture successive |
| Webhooks è avvenimenti mandati | Avvenimenti di compensazione, mai cancellazione |
| Email mandatu | Una persona scrive u seguitu |
| Catena di hash d'audit | Ùn si riscrive mai; aghjunghje una voce di currezzione |

Hè per quessa chì una migrazione di cuntrazione hè distribuita sola: una risturazione hà tandu una
fruntiera chjara.

## Verificà l'aghjurnamentu <!--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/co/ops/upgrade/index.mdx