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

# Atualizar o PostgreSQL

> Como o compose.yaml move uma instalação do PostgreSQL 17 para o 18, como verificar o resultado e como reverter.

A partir da versão 44.0, o `compose.yaml` roda o PostgreSQL 18. Uma instalação feita com um `compose.yaml` anterior roda o PostgreSQL 17, e o primeiro `docker compose up -d` dela na 44.0 a atualiza sozinho. O Notifuse continua funcionando no PostgreSQL 17 (e recusa um servidor mais antigo), então nada obriga você a mudar: veja [Ficar no PostgreSQL 17](#staying-on-postgresql-17).

Uma instalação com banco de dados externo (`DB_HOST` apontando para um PostgreSQL gerenciado) não é afetada: o Notifuse apenas se conecta a ele.

## O que o `docker compose up -d` faz

1. O Compose para o Notifuse e o PostgreSQL 17.
2. O serviço `pg-upgrade` copia os dados do PostgreSQL 17 para o volume `postgres-upgrade-backup`, substituindo qualquer cópia anterior. Se o disco desse volume tiver menos espaço livre do que os dados mais 10%, ele para sem alterar nada e a stack não inicia: `docker compose logs pg-upgrade` informa quanto espaço é necessário. Libere espaço e rode `docker compose up -d` de novo.
3. Ele atualiza os dados para o PostgreSQL 18 no próprio lugar, com o [pgautoupgrade](https://github.com/pgautoupgrade/docker-pgautoupgrade) (`pg_upgrade --link`).
4. O PostgreSQL 18 inicia sobre os dados atualizados, e depois o Notifuse.

Enquanto isso, o Notifuse fica indisponível. A duração depende mais do número de workspaces do que do volume de dados, já que cada workspace tem o seu próprio banco de dados: segundos para alguns workspaces, minutos para centenas. Acompanhe com `docker compose logs -f pg-upgrade`.

Todo `docker compose up -d` seguinte encontra os dados no 18 e não faz nada.

Se a atualização parar no meio (um erro ou uma queda do servidor), a stack não inicia; o próximo `docker compose up -d` recoloca a cópia e começa a atualização de novo. `docker compose logs pg-upgrade` mostra o erro da tentativa que falhou.

> [!WARNING]
>
> A cópia é um caminho de volta no mesmo disco, e não um backup. [Faça backup](https://www.notifuse.com/pt/docs/self-hosting/backups.md) antes de atualizar e guarde a `SECRET_KEY` junto com o backup.

## Antes de atualizar

- **Faça backup** de todos os bancos de dados, como mostra [Backups](https://www.notifuse.com/pt/docs/self-hosting/backups.md).

- **Verifique o espaço livre**: a cópia precisa de tanto espaço quanto os dados ocupam. Com a stack rodando no 17:

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

- **Defina `DB_EXPECT_EXISTING=true`** no `.env`. Se algo desse errado e o Notifuse encontrasse um banco de dados vazio, ele pararia em vez de iniciar uma nova instalação nele.

## Verificar o resultado

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

O último comando lista `notifuse_system` e um banco de dados `notifuse_ws_…` por workspace (substitua `postgres` pelo seu `DB_USER` se você o alterou). Depois, entre e abra os seus workspaces.

## Excluir a cópia

Quando a instalação atualizada estiver funcionando, exclua a cópia para recuperar o espaço. O nome dela começa com o do projeto Compose, que é o nome do diretório que contém o `compose.yaml`:

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

## Reverter

Enquanto a cópia existir, você pode voltar ao PostgreSQL 17 e aos dados como estavam antes da atualização. Tudo o que foi gravado depois da atualização se perde.

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

## Ficar no PostgreSQL 17

No seu `compose.yaml`, mantenha a imagem e o caminho de montagem juntos e remova a atualização:

- `image: postgres:17-alpine` no serviço `postgres`;
- o volume dele montado em `/var/lib/postgresql/data` (`- postgres-data:/var/lib/postgresql/data`);
- o serviço `pg-upgrade` e o `depends_on` de `postgres` nele, excluídos.

A tag e o caminho andam juntos: o PostgreSQL 18 guarda os dados em `/var/lib/postgresql/18/docker`, e o 17 em `/var/lib/postgresql/data`.

## Com o seu próprio arquivo Compose

Se você roda o PostgreSQL a partir do seu próprio arquivo, atualize do mesmo jeito: pare a stack, faça backup, copie o volume e rode o pgautoupgrade uma vez sobre ele, montado em `/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
```

Depois, use `postgres:18-alpine` com o volume montado em `/var/lib/postgresql`. `PGAUTO_REINDEX=no` só é seguro quando as duas imagens são Alpine; a partir de um `postgres:17` baseado em Debian, use `pgautoupgrade:18-trixie` sem essa variável, para que os índices sejam reconstruídos.

> [!WARNING]
>
> Nunca defina `PGDATA` para contornar um erro de inicialização do PostgreSQL 18. Com um `PGDATA` explícito, a imagem deixa de procurar dados de uma versão anterior e inicializa um banco de dados vazio ao lado do seu em vez de se recusar a iniciar. Quando o PostgreSQL se recusa a iniciar, essa recusa protege os seus dados.

## Bom saber

- `docker compose down -v` e `docker volume prune` excluem o banco de dados e a cópia.
- Um banco de dados atualizado mantém os checksums de dados desativados, como o PostgreSQL 17 o criou; uma nova instalação do PostgreSQL 18 os tem ativados.
- Faça a atualização na mesma arquitetura de CPU em que o banco de dados foi criado: não troque de servidor x86 para ARM (ou o contrário) junto com a atualização.
- O pgautoupgrade não suporta servidores PostgreSQL com SSL ativado nem tablespaces em volumes separados, e o `compose.yaml` não usa nenhum dos dois. Nesses casos, mova os dados com um [backup e uma restauração](https://www.notifuse.com/pt/docs/self-hosting/backups.md).
