> ## 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.

# Mettre à jour PostgreSQL

> Comment compose.yaml fait passer une installation de PostgreSQL 17 à 18, comment le vérifier et comment revenir en arrière.

À partir de la version 44.0, `compose.yaml` lance PostgreSQL 18. Une installation faite avec un `compose.yaml` antérieur tourne sur PostgreSQL 17, et son premier `docker compose up -d` sur la 44.0 la met à jour d'elle-même. Notifuse fonctionne toujours sur PostgreSQL 17 (et refuse un serveur plus ancien), donc rien ne vous oblige à migrer : voir [Rester sur PostgreSQL 17](#staying-on-postgresql-17).

Une installation avec une base de données externe (`DB_HOST` pointant vers un PostgreSQL managé) n'est pas concernée : Notifuse s'y connecte seulement.

## Ce que fait `docker compose up -d`

1. Compose arrête Notifuse et PostgreSQL 17.
2. Le service `pg-upgrade` copie les données PostgreSQL 17 dans le volume `postgres-upgrade-backup`, en remplaçant une éventuelle copie précédente. Si le disque de ce volume a moins d'espace libre que les données plus 10 %, il s'arrête sans rien modifier et la stack ne démarre pas : `docker compose logs pg-upgrade` indique l'espace nécessaire. Libérez de la place, puis relancez `docker compose up -d`.
3. Il met à jour les données vers PostgreSQL 18 sur place, avec [pgautoupgrade](https://github.com/pgautoupgrade/docker-pgautoupgrade) (`pg_upgrade --link`).
4. PostgreSQL 18 démarre sur les données mises à jour, puis Notifuse.

Notifuse est indisponible pendant ce temps. La durée dépend du nombre d'espaces de travail plus que du volume de données, car chaque espace de travail a sa propre base : quelques secondes pour une poignée d'espaces de travail, quelques minutes pour des centaines. Suivez-la avec `docker compose logs -f pg-upgrade`.

Chaque `docker compose up -d` suivant trouve les données en version 18 et ne fait rien.

Si la mise à jour s'interrompt en cours de route (une erreur, ou le serveur qui tombe), la stack ne démarre pas ; le `docker compose up -d` suivant remet la copie en place et relance la mise à jour. `docker compose logs pg-upgrade` affiche l'erreur de la tentative échouée.

> [!WARNING]
>
> La copie est un moyen de revenir en arrière sur le même disque, pas une sauvegarde. [Sauvegardez](https://www.notifuse.com/fr/docs/self-hosting/backups.md) avant la mise à jour, et conservez `SECRET_KEY` avec la sauvegarde.

## Avant la mise à jour

- **Sauvegardez** chaque base de données, comme l'explique [Sauvegardes](https://www.notifuse.com/fr/docs/self-hosting/backups.md).

- **Vérifiez l'espace libre** : la copie occupe autant que les données. Avec la stack qui tourne en version 17 :

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

- **Définissez `DB_EXPECT_EXISTING=true`** dans `.env`. Si quelque chose tournait mal et que Notifuse trouvait une base vide, il s'arrêterait au lieu d'y démarrer une nouvelle installation.

## Vérifier le résultat

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

La dernière commande liste `notifuse_system` et une base `notifuse_ws_…` par espace de travail (remplacez `postgres` par votre `DB_USER` si vous l'avez changé). Connectez-vous ensuite et ouvrez vos espaces de travail.

## Supprimer la copie

Une fois l'installation mise à jour fonctionnelle, supprimez la copie pour récupérer son espace. Son nom commence par celui du projet Compose, c'est-à-dire le nom du répertoire qui contient `compose.yaml` :

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

## Revenir en arrière

Tant que la copie existe, vous pouvez revenir à PostgreSQL 17 et aux données telles qu'elles étaient avant la mise à jour. Tout ce qui a été écrit depuis la mise à jour est perdu.

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

## Rester sur PostgreSQL 17

Dans votre `compose.yaml`, gardez ensemble l'image et le chemin de montage, et retirez la mise à jour :

- `image: postgres:17-alpine` sur le service `postgres` ;
- son volume monté sur `/var/lib/postgresql/data` (`- postgres-data:/var/lib/postgresql/data`) ;
- le service `pg-upgrade`, et le `depends_on` de `postgres` vers lui, supprimés.

Le tag et le chemin vont de pair : PostgreSQL 18 garde ses données dans `/var/lib/postgresql/18/docker`, la 17 dans `/var/lib/postgresql/data`.

## Avec votre propre fichier Compose

Si vous lancez PostgreSQL depuis votre propre fichier, la mise à jour se fait de la même façon : arrêtez la stack, sauvegardez, copiez le volume, puis lancez pgautoupgrade une fois dessus, monté sur `/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
```

Utilisez ensuite `postgres:18-alpine` avec le volume monté sur `/var/lib/postgresql`. `PGAUTO_REINDEX=no` n'est sûr que si les deux images sont Alpine ; depuis un `postgres:17` basé sur Debian, utilisez `pgautoupgrade:18-trixie` sans cette option, pour que les index soient reconstruits.

> [!WARNING]
>
> Ne définissez jamais `PGDATA` pour contourner une erreur de démarrage de PostgreSQL 18. Avec un `PGDATA` explicite, l'image ne cherche plus de données d'une version antérieure et initialise une base vide à côté de la vôtre au lieu de refuser de démarrer. Quand PostgreSQL refuse de démarrer, ce refus protège vos données.

## Bon à savoir

- `docker compose down -v` et `docker volume prune` suppriment la base de données et la copie.
- Une base mise à jour garde les sommes de contrôle des données désactivées, comme PostgreSQL 17 l'a créée ; une nouvelle installation PostgreSQL 18 les a activées.
- Faites la mise à jour sur la même architecture de processeur que celle où la base a été créée : ne combinez pas un passage entre serveurs x86 et ARM avec la mise à jour.
- pgautoupgrade ne prend pas en charge les serveurs PostgreSQL avec SSL activé ni les tablespaces sur des volumes séparés, que `compose.yaml` n'utilise ni l'un ni l'autre. Dans ces cas, déplacez plutôt les données par une [sauvegarde et une restauration](https://www.notifuse.com/fr/docs/self-hosting/backups.md).
