n8n com Docker Compose e PostgreSQL: passo a passo

Resposta curta: coloque um serviço postgres:18 no mesmo compose.yaml do n8n e aponte o n8n para ele com DB_TYPE=postgresdb e as variáveis DB_POSTGRESDB_*. O n8n cria as tabelas sozinho na primeira subida.

O padrão do n8n é SQLite, que serve bem para uso pessoal. O PostgreSQL vale a pena quando o volume de execuções cresce, quando você quer fazer backup com as ferramentas do próprio banco ou quando pretende usar queue mode, que não é recomendado com SQLite. A documentação suporta as versões 16, 17 e 18 do PostgreSQL (docs).

1Crie o .env

Numa pasta nova (por exemplo ~/n8n), crie o arquivo .env:

POSTGRES_USER=n8n
POSTGRES_PASSWORD=troque-esta-senha
POSTGRES_DB=n8n
N8N_ENCRYPTION_KEY=troque-por-uma-chave-longa-e-aleatoria

Gere a chave com openssl rand -hex 32 e guarde uma cópia fora do servidor. Ela criptografa as credenciais salvas no banco: sem ela, um backup do PostgreSQL não serve para recuperar as credenciais (veja o guia de backup).

2Crie o compose.yaml

services:
  postgres:
    image: postgres:18
    restart: always
    environment:
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - POSTGRES_DB
      - PGDATA=/var/lib/postgresql/data
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: n8nio/n8n:stable
    restart: always
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - GENERIC_TIMEZONE=America/Sao_Paulo
      - TZ=America/Sao_Paulo
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  db_data:
  n8n_data:

Os pontos que importam:

• O healthcheck com pg_isready e o condition: service_healthy fazem o n8n esperar o banco ficar pronto antes de subir.
• O PGDATA fixo mantém o volume no mesmo caminho entre versões do PostgreSQL. O postgres:18 mudou o diretório padrão, e o exemplo oficial do n8n também fixa esse caminho (n8n-hosting).
• A porta 5678 fica presa em 127.0.0.1. Para acesso externo com HTTPS, use um proxy reverso, como o Traefik do guia de Docker Compose.
• O PostgreSQL não publica porta nenhuma: só o n8n fala com ele, pela rede interna do Compose.

3Suba e confira

docker compose up -d
docker compose ps
docker compose logs n8n --tail 20

Em cerca de 30 a 40 segundos o log mostra Editor is now accessible via: http://localhost:5678. Para confirmar que o n8n está usando o PostgreSQL:

docker compose exec postgres psql -U n8n -d n8n -c "\dt" | head

A lista deve trazer tabelas como workflow_entity, execution_entity e credentials_entity.

Quanto de memória reservar

Parados, logo depois de subir, o n8n ficou em torno de 370 MiB e o PostgreSQL em torno de 60 MiB. O banco de uma instância nova ocupa cerca de 16 MB. Ou seja, o PostgreSQL acrescenta pouco: uma VPS de 2 GB atende bem uso leve a moderado. Para dimensionar com folga, veja os requisitos de RAM e CPU e a calculadora.

Já uso SQLite. Como migro?

A documentação indica os comandos de exportação e importação da CLI do n8n para levar os dados de um banco para outro (docs). Exporte workflows e credenciais com n8n export:workflow --backup e n8n export:credentials --backup, suba a instância nova com PostgreSQL e a mesma chave de criptografia, e importe com n8n import:workflow --separate e n8n import:credentials --separate. O passo a passo dos comandos está no guia de backup.

Próximos passos

• Faça backup do banco com pg_dump.
• Para atualizar com segurança, siga como atualizar o n8n.
• Para escalar, veja n8n em queue mode com Redis.

Perguntas frequentes

Quais versões do PostgreSQL o n8n suporta?

Segundo a documentação, as versões 16, 17 e 18.

Preciso criar as tabelas do n8n no PostgreSQL?

Não. Basta criar o banco e o usuário; o n8n cria as tabelas sozinho na primeira subida.

Quanta memória o PostgreSQL usa junto com o n8n?

Numa instância nova, parada, o PostgreSQL fica em torno de 60 MiB e o n8n em torno de 370 MiB.