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

# Aggiornare PostgreSQL

> Come compose.yaml porta un'installazione da PostgreSQL 17 a 18, come verificarlo e come tornare indietro.

Dalla versione 44.0, `compose.yaml` esegue PostgreSQL 18. Un'installazione creata con un `compose.yaml` precedente esegue PostgreSQL 17, e il suo primo `docker compose up -d` sulla 44.0 la aggiorna da solo. Notifuse funziona ancora su PostgreSQL 17 (e rifiuta un server più vecchio), quindi niente ti obbliga a passare alla 18: vedi [Restare su PostgreSQL 17](#staying-on-postgresql-17).

Un'installazione con un database esterno (`DB_HOST` che punta a un PostgreSQL gestito) non è interessata: Notifuse si limita a connettersi.

## Cosa fa `docker compose up -d`

1. Compose ferma Notifuse e PostgreSQL 17.
2. Il servizio `pg-upgrade` copia i dati di PostgreSQL 17 nel volume `postgres-upgrade-backup`, sostituendo un'eventuale copia precedente. Se il disco di quel volume ha meno spazio libero dei dati più il 10 %, si ferma senza cambiare nulla e lo stack non si avvia: `docker compose logs pg-upgrade` dice quanto spazio serve. Liberane un po', poi esegui di nuovo `docker compose up -d`.
3. Aggiorna i dati a PostgreSQL 18 sul posto, con [pgautoupgrade](https://github.com/pgautoupgrade/docker-pgautoupgrade) (`pg_upgrade --link`).
4. PostgreSQL 18 si avvia sui dati aggiornati, poi si avvia Notifuse.

Nel frattempo Notifuse non è disponibile. La durata dipende più dal numero di workspace che dal volume di dati, perché ogni workspace ha il proprio database: secondi per pochi workspace, minuti per centinaia. Seguila con `docker compose logs -f pg-upgrade`.

Ogni `docker compose up -d` successivo trova i dati sulla 18 e non fa nulla.

Se l'aggiornamento si interrompe a metà (un errore, o il server che si spegne), lo stack non si avvia; il `docker compose up -d` successivo rimette la copia e ricomincia l'aggiornamento. `docker compose logs pg-upgrade` mostra l'errore del tentativo fallito.

> [!WARNING]
>
> La copia è una via di ritorno sullo stesso disco, non un backup. [Fai un backup](https://www.notifuse.com/it/docs/self-hosting/backups.md) prima di aggiornare, e conserva `SECRET_KEY` insieme al backup.

## Prima di aggiornare

- **Fai il backup** di ogni database, come spiega [Backup](https://www.notifuse.com/it/docs/self-hosting/backups.md).

- **Controlla lo spazio libero**: la copia occupa quanto i dati. Con lo stack in esecuzione sulla 17:

  ```bash
  docker compose exec postgres du -sh /var/lib/postgresql/data
  df -h /var/lib/docker
  ```

- **Imposta `DB_EXPECT_EXISTING=true`** in `.env`. Se qualcosa andasse storto e Notifuse trovasse un database vuoto, si fermerebbe invece di avviarci sopra una nuova installazione.

## Verificare il risultato

```bash
docker compose logs pg-upgrade | grep -i copy      # "Copying the PostgreSQL 17 data ..." then "Copy done"
docker compose exec postgres psql -U postgres -d postgres -Atc "SELECT version()"    # PostgreSQL 18.x
docker compose exec postgres psql -U postgres -d postgres -Atc "SELECT datname FROM pg_database ORDER BY 1"
```

L'ultimo comando elenca `notifuse_system` e un database `notifuse_ws_…` per ogni workspace (sostituisci `postgres` con il tuo `DB_USER` se l'hai cambiato). Poi accedi e apri i tuoi workspace.

## Eliminare la copia

Quando l'installazione aggiornata funziona, elimina la copia per recuperare il suo spazio. Il suo nome inizia con il progetto Compose, cioè il nome della directory che contiene `compose.yaml`:

```bash
docker volume ls | grep postgres-upgrade-backup
docker volume rm notifuse_postgres-upgrade-backup
```

## Tornare indietro

Finché la copia esiste, puoi tornare a PostgreSQL 17 e ai dati com'erano prima dell'aggiornamento. Tutto ciò che è stato scritto dopo l'aggiornamento va perso.

```bash
docker compose down
# Put back the compose.yaml of your previous release, for example 43.0:
curl -fsSL https://raw.githubusercontent.com/Notifuse/notifuse/v43.0/compose.yaml -o compose.yaml
# Replace the PostgreSQL 18 data with the copy (project "notifuse": adjust both volume names)
docker run --rm -v notifuse_postgres-upgrade-backup:/from -v notifuse_postgres-data:/to alpine \
  sh -c 'find /to -mindepth 1 -delete && cp -a /from/pg17/. /to/'
docker compose up -d
```

## Restare su PostgreSQL 17

Nel tuo `compose.yaml`, tieni insieme l'immagine e il percorso di montaggio, e togli l'aggiornamento:

- `image: postgres:17-alpine` sul servizio `postgres`;
- il suo volume montato su `/var/lib/postgresql/data` (`- postgres-data:/var/lib/postgresql/data`);
- il servizio `pg-upgrade` eliminato, insieme al `depends_on` di `postgres` su di esso.

Il tag e il percorso vanno in coppia: PostgreSQL 18 tiene i suoi dati in `/var/lib/postgresql/18/docker`, la 17 in `/var/lib/postgresql/data`.

## Con un tuo file Compose

Se esegui PostgreSQL da un tuo file, aggiorna allo stesso modo: ferma lo stack, fai il backup, copia il volume, poi esegui pgautoupgrade una volta su di esso, montato su `/var/lib/postgresql`:

```bash
docker run --rm -v <your volume>:/var/lib/postgresql \
  -e POSTGRES_USER=<your user> -e POSTGRES_PASSWORD=<your password> \
  -e PGAUTO_ONESHOT=yes -e PGAUTO_REINDEX=no pgautoupgrade/pgautoupgrade:18-alpine
```

Poi usa `postgres:18-alpine` con il volume montato su `/var/lib/postgresql`. `PGAUTO_REINDEX=no` è sicuro solo quando entrambe le immagini sono Alpine; partendo da un `postgres:17` basato su Debian, usa `pgautoupgrade:18-trixie` senza questa variabile, così gli indici vengono ricostruiti.

> [!WARNING]
>
> Non impostare mai `PGDATA` per aggirare un errore di avvio di PostgreSQL 18. Con un `PGDATA` esplicito, l'immagine non cerca più dati di una versione precedente e inizializza un database vuoto accanto al tuo invece di rifiutarsi di partire. Quando PostgreSQL si rifiuta di avviarsi, quel rifiuto protegge i tuoi dati.

## Da sapere

- `docker compose down -v` e `docker volume prune` eliminano il database e la copia.
- Un database aggiornato mantiene disattivati i checksum dei dati, come li aveva creati PostgreSQL 17; una nuova installazione di PostgreSQL 18 li ha attivi.
- Aggiorna sulla stessa architettura CPU su cui è stato creato il database: non abbinare all'aggiornamento un passaggio tra server x86 e ARM.
- pgautoupgrade non supporta server PostgreSQL con SSL attivo o con tablespace su volumi separati, e `compose.yaml` non usa nessuna delle due cose. In questi casi, sposta i dati con un [backup e un ripristino](https://www.notifuse.com/it/docs/self-hosting/backups.md).
