PostgreSQL¶

O PostgreSQL armazena os dados persistentes do n8n.

Informações desta VPS¶

Item	Valor
Stack	`/opt/stacks/n8n/compose.yml`
Serviço Compose	`postgres`
Container	`n8n-postgres-1`
Imagem	`postgres:16`
Banco	`n8n`
Usuário	`n8n`
Porta interna	`5432`
Volume Docker	`n8n_pgdata`
Diretório no host	`/var/lib/docker/volumes/n8n_pgdata/_data`
Diretório no container	`/var/lib/postgresql/data`

Status¶

Ver o status do serviço¶

docker compose -f /opt/stacks/n8n/compose.yml ps postgres

Ver somente o container¶

docker ps --filter name=n8n-postgres-1

Verificar se o PostgreSQL está pronto¶

docker exec n8n-postgres-1 pg_isready

Resultado esperado:

/var/run/postgresql:5432 - accepting connections

Ver a versão instalada¶

docker exec n8n-postgres-1 postgres --version

Ver a imagem utilizada¶

docker inspect n8n-postgres-1 --format '{{.Config.Image}}'

Logs¶

Ver os últimos 100 registros¶

docker logs n8n-postgres-1 --tail 100

Acompanhar os logs em tempo real¶

docker logs -f n8n-postgres-1

Procurar erros¶

docker logs n8n-postgres-1 2>&1 | grep -i error

Procurar conexões recusadas¶

docker logs n8n-postgres-1 2>&1 | grep -Ei "refused|failed|fatal"

Operação¶

Reiniciar somente o PostgreSQL¶

docker compose -f /opt/stacks/n8n/compose.yml restart postgres

Interrupção do n8n

Reiniciar o PostgreSQL interrompe temporariamente o acesso do n8n ao banco.

Parar somente o PostgreSQL¶

docker compose -f /opt/stacks/n8n/compose.yml stop postgres

Iniciar o PostgreSQL parado¶

docker compose -f /opt/stacks/n8n/compose.yml start postgres

Recriar somente o PostgreSQL¶

docker compose -f /opt/stacks/n8n/compose.yml up -d --force-recreate postgres

Acesso com psql¶

Entrar no banco n8n¶

docker exec -it n8n-postgres-1 psql -U n8n -d n8n

Sair do psql¶

\q

Listar bancos¶

Dentro do psql:

\l

Listar tabelas¶

Dentro do psql:

\dt

Listar schemas¶

Dentro do psql:

\dn

Ver conexões ativas¶

Dentro do psql:

SELECT pid, usename, datname, client_addr, state
FROM pg_stat_activity
ORDER BY pid;

Ver tamanho do banco¶

Dentro do psql:

SELECT pg_size_pretty(pg_database_size('n8n'));

Ver tamanho das tabelas¶

Dentro do psql:

SELECT
    schemaname,
    relname,
    pg_size_pretty(pg_total_relation_size(relid)) AS tamanho
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

Ver quantidade de conexões¶

Dentro do psql:

SELECT count(*) AS conexoes
FROM pg_stat_activity;

Consultas diretas pelo terminal¶

Listar bancos sem entrar no psql¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n -c '\l'

Listar tabelas¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n -c '\dt'

Ver tamanho do banco¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT pg_size_pretty(pg_database_size('n8n'));"

Ver conexões ativas¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT pid, usename, datname, client_addr, state FROM pg_stat_activity ORDER BY pid;"

Backup¶

Criar diretório de backups¶

mkdir -p /opt/backups/postgres

Criar backup lógico do banco n8n¶

docker exec n8n-postgres-1 \
  pg_dump -U n8n -d n8n -Fc \
  > /opt/backups/postgres/n8n-$(date +%Y%m%d-%H%M%S).dump

O formato -Fc cria um backup compactado no formato custom do PostgreSQL.

Criar backup em SQL puro¶

docker exec n8n-postgres-1 \
  pg_dump -U n8n -d n8n \
  > /opt/backups/postgres/n8n-$(date +%Y%m%d-%H%M%S).sql

Listar backups¶

ls -lh /opt/backups/postgres

Verificar o conteúdo de um backup custom¶

pg_restore --list /opt/backups/postgres/NOME_DO_BACKUP.dump

Caso pg_restore não esteja instalado no host:

docker exec -i n8n-postgres-1 \
  pg_restore --list \
  < /opt/backups/postgres/NOME_DO_BACKUP.dump

Restauração¶

Operação destrutiva

Uma restauração pode sobrescrever dados existentes. Faça backup do estado atual antes de restaurar.

Restaurar backup custom¶

docker exec -i n8n-postgres-1 \
  pg_restore \
  -U n8n \
  -d n8n \
  --clean \
  --if-exists \
  < /opt/backups/postgres/NOME_DO_BACKUP.dump

Restaurar backup SQL¶

docker exec -i n8n-postgres-1 \
  psql -U n8n -d n8n \
  < /opt/backups/postgres/NOME_DO_BACKUP.sql

Volume persistente¶

Ver o volume¶

docker volume inspect n8n_pgdata

Ver o diretório usado no host¶

docker inspect n8n-postgres-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

Ver o uso de espaço do volume¶

du -sh /var/lib/docker/volumes/n8n_pgdata/_data

Listar os arquivos do volume¶

ls -lah /var/lib/docker/volumes/n8n_pgdata/_data

Não editar diretamente

Não altere manualmente os arquivos dentro de /var/lib/postgresql/data. O PostgreSQL controla esses arquivos internamente. Edição manual é uma receita bastante eficiente para fabricar um banco corrompido.

Manutenção¶

Ver bancos e respectivos tamanhos¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT datname, pg_size_pretty(pg_database_size(datname)) FROM pg_database ORDER BY pg_database_size(datname) DESC;"

Executar VACUUM ANALYZE¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "VACUUM ANALYZE;"

O VACUUM ANALYZE atualiza estatísticas e ajuda o otimizador de consultas.

Ver transações longas¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT pid, now() - xact_start AS duracao, state, query FROM pg_stat_activity WHERE xact_start IS NOT NULL ORDER BY xact_start;"

Ver bloqueios¶

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT pid, locktype, mode, granted FROM pg_locks ORDER BY granted, pid;"

Atualização da imagem¶

Criar backup antes da atualização¶

docker exec n8n-postgres-1 \
  pg_dump -U n8n -d n8n -Fc \
  > /opt/backups/postgres/n8n-pre-update-$(date +%Y%m%d-%H%M%S).dump

Ver a versão atual¶

docker exec n8n-postgres-1 postgres --version

Baixar a imagem configurada¶

docker compose -f /opt/stacks/n8n/compose.yml pull postgres

Recriar o serviço¶

docker compose -f /opt/stacks/n8n/compose.yml up -d postgres

Verificar a saúde¶

docker compose -f /opt/stacks/n8n/compose.yml ps postgres

Verificar os logs¶

docker logs n8n-postgres-1 --tail 100

Mudança de versão principal

Atualizar de PostgreSQL 16 para 17, por exemplo, não é uma simples troca de imagem. Mudanças de versão principal exigem migração planejada, geralmente com pg_dump e pg_restore ou pg_upgrade.

Troubleshooting¶

PostgreSQL não inicia¶

Verificar:

docker compose -f /opt/stacks/n8n/compose.yml ps postgres

docker logs n8n-postgres-1 --tail 200

docker volume inspect n8n_pgdata

df -h

df -i

PostgreSQL aparece como unhealthy¶

Verificar o healthcheck:

docker inspect n8n-postgres-1 \
  --format '{{json .State.Health}}'

Testar manualmente:

docker exec n8n-postgres-1 pg_isready -U n8n -d n8n

n8n não conecta ao banco¶

Verificar o PostgreSQL:

docker exec n8n-postgres-1 pg_isready -U n8n -d n8n

Verificar os logs do banco:

docker logs n8n-postgres-1 --tail 100

Verificar os logs do n8n:

docker logs n8n-n8n-1 --tail 100

Verificar as variáveis do n8n sem mostrar a senha:

docker inspect n8n-n8n-1 \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep -E '^DB_POSTGRESDB_(HOST|PORT|DATABASE|USER)='

Banco sem espaço em disco¶

Verificar:

df -h

docker system df

du -sh /var/lib/docker/volumes/n8n_pgdata/_data

Muitas conexões¶

Verificar:

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SELECT count(*) FROM pg_stat_activity;"

docker exec n8n-postgres-1 \
  psql -U n8n -d n8n \
  -c "SHOW max_connections;"

Boas práticas¶

Fazer backup antes de atualizações.
Testar periodicamente a restauração dos backups.
Não publicar a porta 5432 diretamente na internet.
Não editar os arquivos internos do volume.
Não remover o volume n8n_pgdata.
Monitorar espaço em disco.
Evitar mudanças automáticas de versão principal.
Verificar logs após reinícios e atualizações.