Migração do PostgreSQL 14 para 17 no Docker Swarm

Problema

Ao atualizar o PostgreSQL do Docker Swarm da versão 14 para 17, ocorreu o erro:

FATAL: database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 14, which is not compatible with this version 17.0.

O problema ocorre porque o diretório de dados de uma versão anterior não pode ser usado diretamente em uma versão mais recente.

Solução

1️⃣ Fazer backup do PostgreSQL 14

Antes de iniciar a migração, é fundamental realizar um backup completo dos bancos de dados.

docker exec -it <CONTAINER_ID_POSTGRES14> pg_dumpall -U postgres > backup_full.sql
docker cp <CONTAINER_ID_POSTGRES14>:/backup_full.sql ./backup_full.sql

Se o backup estiver vazio, verifique se o usuário postgres tem as permissões corretas.

2️⃣ Criar um novo volume para o PostgreSQL 17

Como o volume antigo contém dados da versão 14, devemos criar um novo volume para evitar conflitos.

docker volume create postgres_data_17

Verifique se o volume foi criado:

docker volume ls

3️⃣ Subir o PostgreSQL 17

Atualize seu docker-compose.yml:

version: "3.8"

services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      - POSTGRES_PASSWORD=123
      - TZ=America/Sao_Paulo
    networks:
      - traefik_public
    ports:
      - 5432:5432
    volumes:
      - postgres_data_17:/var/lib/postgresql/data
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager
      resources:
        limits:
          cpus: "0.5"
          memory: 1024M

volumes:
  postgres_data_17:
    external: true
    name: postgres_data_17

networks:
  traefik_public:
    external: true
    name: traefik_public

Agora, suba o serviço com:

docker stack deploy -c docker-compose.yml postgres_stack

Se estiver usando docker run diretamente:

docker run -d \
  --name postgres17 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=123 \
  -v postgres_data_17:/var/lib/postgresql/data \
  --network=traefik_public \
  postgres:17

4️⃣ Restaurar o backup no PostgreSQL 17

Com o novo container em execução, copie o backup para dentro dele:

docker cp backup_full.sql <CONTAINER_ID_POSTGRES17>:/backup_full.sql

Acesse o container:

docker exec -it <CONTAINER_ID_POSTGRES17> bash

Dentro do container, restaure o backup:

psql -U postgres -f /backup_full.sql

5️⃣ Verificar se a restauração foi bem-sucedida

Saia do container e conecte-se ao banco para verificar se os dados foram restaurados:

docker exec -it <CONTAINER_ID_POSTGRES17> psql -U postgres

Liste os bancos de dados para conferir:

\l

Se tudo estiver correto, a migração foi concluída com sucesso! 🎉