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

# PostgreSQL aktualisieren

> Wie compose.yaml eine Installation von PostgreSQL 17 auf 18 umstellt, wie Sie das Ergebnis prüfen und wie Sie zurückkehren.

Ab Version 44.0 startet `compose.yaml` PostgreSQL 18. Eine Installation, die mit einer früheren `compose.yaml` angelegt wurde, läuft auf PostgreSQL 17, und ihr erstes `docker compose up -d` auf 44.0 aktualisiert sie selbstständig. Notifuse läuft weiterhin auf PostgreSQL 17 (und lehnt ältere Server ab), Sie müssen also nicht umsteigen: siehe [Bei PostgreSQL 17 bleiben](#staying-on-postgresql-17).

Eine Installation mit externer Datenbank (`DB_HOST` zeigt auf ein verwaltetes PostgreSQL) ist nicht betroffen: Notifuse verbindet sich nur mit ihr.

## Was `docker compose up -d` tut

1. Compose hält Notifuse und PostgreSQL 17 an.
2. Der Dienst `pg-upgrade` kopiert die Daten von PostgreSQL 17 in das Volume `postgres-upgrade-backup` und ersetzt dabei eine frühere Kopie. Hat die Festplatte dieses Volumes weniger freien Platz als die Daten plus 10 %, hält er an, ohne etwas zu ändern, und der Stack startet nicht: `docker compose logs pg-upgrade` nennt den benötigten Platz. Schaffen Sie Platz und führen Sie dann `docker compose up -d` erneut aus.
3. Er aktualisiert die Daten an Ort und Stelle auf PostgreSQL 18, mit [pgautoupgrade](https://github.com/pgautoupgrade/docker-pgautoupgrade) (`pg_upgrade --link`).
4. PostgreSQL 18 startet auf den aktualisierten Daten, danach Notifuse.

Notifuse ist währenddessen nicht erreichbar. Die Dauer hängt mehr von der Zahl der Arbeitsbereiche ab als von der Datenmenge, weil jeder Arbeitsbereich eine eigene Datenbank hat: Sekunden für eine Handvoll Arbeitsbereiche, Minuten für Hunderte. Verfolgen Sie den Vorgang mit `docker compose logs -f pg-upgrade`.

Jedes spätere `docker compose up -d` findet die Daten auf 18 vor und tut nichts.

Bricht das Update auf halbem Weg ab (ein Fehler oder ein Ausfall des Servers), startet der Stack nicht; das nächste `docker compose up -d` spielt die Kopie zurück und beginnt das Update von vorn. `docker compose logs pg-upgrade` zeigt den Fehler des gescheiterten Versuchs.

> [!WARNING]
>
> Die Kopie ist ein Rückweg auf derselben Festplatte, keine Sicherung. [Erstellen Sie eine Sicherung](https://www.notifuse.com/de/docs/self-hosting/backups.md), bevor Sie aktualisieren, und bewahren Sie `SECRET_KEY` mit der Sicherung auf.

## Vor dem Update

- **Sichern** Sie jede Datenbank, wie unter [Sicherungen](https://www.notifuse.com/de/docs/self-hosting/backups.md) beschrieben.

- **Prüfen Sie den freien Platz**: Die Kopie braucht so viel Platz, wie die Daten belegen. Bei laufendem Stack auf 17:

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

- **Setzen Sie `DB_EXPECT_EXISTING=true`** in `.env`. Sollte etwas schiefgehen und Notifuse eine leere Datenbank vorfinden, hält es dann an, statt darauf eine neue Installation zu beginnen.

## Ergebnis prüfen

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

Der letzte Befehl listet `notifuse_system` und eine Datenbank `notifuse_ws_…` pro Arbeitsbereich auf (ersetzen Sie `postgres` durch Ihren `DB_USER`, falls Sie ihn geändert haben). Melden Sie sich danach an und öffnen Sie Ihre Arbeitsbereiche.

## Kopie löschen

Sobald die aktualisierte Installation funktioniert, löschen Sie die Kopie, um ihren Platz freizugeben. Ihr Name beginnt mit dem Compose-Projekt, also dem Namen des Verzeichnisses, das `compose.yaml` enthält:

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

## Zurückkehren

Solange die Kopie existiert, können Sie zu PostgreSQL 17 und den Daten im Zustand vor dem Update zurückkehren. Alles, was seit dem Update geschrieben wurde, geht verloren.

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

## Bei PostgreSQL 17 bleiben

Behalten Sie in Ihrer `compose.yaml` Image und Mount-Pfad gemeinsam bei und entfernen Sie das Update:

- `image: postgres:17-alpine` im Dienst `postgres`;
- sein Volume unter `/var/lib/postgresql/data` eingehängt (`- postgres-data:/var/lib/postgresql/data`);
- den Dienst `pg-upgrade` und das `depends_on` von `postgres` darauf gelöscht.

Tag und Pfad gehören zusammen: PostgreSQL 18 legt seine Daten in `/var/lib/postgresql/18/docker` ab, 17 in `/var/lib/postgresql/data`.

## Mit Ihrer eigenen Compose-Datei

Wenn Sie PostgreSQL aus Ihrer eigenen Datei starten, aktualisieren Sie auf dieselbe Weise: Stack anhalten, Sicherung erstellen, Volume kopieren und dann pgautoupgrade einmal darauf ausführen, eingehängt unter `/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
```

Verwenden Sie danach `postgres:18-alpine` mit dem Volume unter `/var/lib/postgresql`. `PGAUTO_REINDEX=no` ist nur sicher, wenn beide Images auf Alpine basieren; von einem Debian-basierten `postgres:17` aus verwenden Sie `pgautoupgrade:18-trixie` ohne diese Option, damit die Indizes neu aufgebaut werden.

> [!WARNING]
>
> Setzen Sie nie `PGDATA`, um einen Startfehler von PostgreSQL 18 zu umgehen. Mit einem ausdrücklich gesetzten `PGDATA` prüft das Image nicht mehr auf Daten einer älteren Version und legt neben Ihrer eine leere Datenbank an, statt den Start zu verweigern. Wenn PostgreSQL den Start verweigert, schützt diese Weigerung Ihre Daten.

## Gut zu wissen

- `docker compose down -v` und `docker volume prune` löschen die Datenbank und die Kopie.
- Eine aktualisierte Datenbank behält die Datenprüfsummen ausgeschaltet, so wie PostgreSQL 17 sie angelegt hat; eine neue Installation von PostgreSQL 18 hat sie eingeschaltet.
- Aktualisieren Sie auf derselben CPU-Architektur, auf der die Datenbank angelegt wurde: Verbinden Sie einen Umzug zwischen x86- und ARM-Servern nicht mit dem Update.
- pgautoupgrade unterstützt keine PostgreSQL-Server mit aktiviertem SSL oder mit Tablespaces auf separaten Volumes; `compose.yaml` verwendet beides nicht. Verschieben Sie die Daten in diesen Fällen stattdessen mit einer [Sicherung und Wiederherstellung](https://www.notifuse.com/de/docs/self-hosting/backups.md).
