Por padrão, o n8n armazena dados em SQLite, um banco baseado em arquivo que não exige configuração. Ele funciona bem para testes locais, mas apresenta limitações em produção: bloqueia o arquivo durante gravações, não oferece backups seguros em tempo real e não é compatível com o modo fila (queue mode), necessário para escalar horizontalmente com workers.
O PostgreSQL resolve esses problemas e é a opção recomendada para qualquer instalação self-hosted do n8n além de uso pessoal.
Neste guia, você vai configurar o n8n com PostgreSQL usando Docker Compose e também aprender como migrar uma instância existente em SQLite de forma segura. A configuração leva cerca de 15 minutos e não exige experiência prévia com bancos de dados.
Por que migrar para PostgreSQL?
O SQLite armazena todos os dados em um único arquivo e bloqueia completamente esse arquivo a cada gravação. Quando vários workflows são executados ao mesmo tempo, as operações ficam enfileiradas e podem falhar por timeout. Em casos extremos, o arquivo pode ser corrompido. Além disso, não é possível fazer um backup consistente enquanto o n8n está em execução — copiar o arquivo durante uma gravação pode resultar em dados inconsistentes.
O PostgreSQL utiliza bloqueio em nível de linha (row-level), permitindo execuções paralelas sem conflitos. Ele suporta backups em tempo real com pg_dump, sem necessidade de interromper o n8n. Também é obrigatório para o uso do modo fila (com Redis e múltiplos workers) e para configurações com alta disponibilidade.
Se o seu n8n é usado por uma equipe ou processa mais do que algumas dezenas de workflows por dia, o PostgreSQL é a escolha mais adequada.
Pré-requisitos
- Um servidor Linux (Ubuntu 22.04 ou 24.04) com pelo menos 2 GB de RAM e 20 GB de disco;
- Docker e Docker Compose instalados;
- Acesso via SSH ao servidor;
- Para migração: acesso ao diretório de dados atual do n8n (/home/node/.n8n ou volume do Docker).
Você pode contratar uma VPS na Serverspace e deixá-la pronta em poucos minutos. Se preferir evitar a instalação manual, a Serverspace também oferece uma VPS com n8n pré-instalado como aplicação 1-Click.
Passo 1. Gerar uma chave de criptografia
O n8n criptografa todas as credenciais armazenadas usando esta chave. Se você perdê-la, todas as credenciais salvas ficarão permanentemente inacessíveis.
Gere uma chave e armazene-a em um gerenciador de senhas:
openssl rand -hex 32Passo 2. Criar os arquivos do projeto
Crie um diretório e adicione três arquivos dentro dele:
mkdir ~/n8n-postgres && cd ~/n8n-postgres.env
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_strong_postgres_password
POSTGRES_DB=n8n
POSTGRES_NON_ROOT_USER=n8n_user
POSTGRES_NON_ROOT_PASSWORD=your_strong_n8n_password
N8N_ENCRYPTION_KEY=paste_your_generated_key_here
N8N_HOST=0.0.0.0
N8N_PROTOCOL=http
N8N_PORT=5678
GENERIC_TIMEZONE=UTC
docker-compose.yml
volumes:
db_storage:
n8n_storage:
services:
postgres:
image: postgres:16-alpine
restart: always
environment:
- POSTGRES_USER
- POSTGRES_PASSWORD
- POSTGRES_DB
- POSTGRES_NON_ROOT_USER
- POSTGRES_NON_ROOT_PASSWORD
volumes:
- db_storage:/var/lib/postgresql/data
- ./init-data.sh:/docker-entrypoint-initdb.d/init-data.sh
healthcheck:
test: ['CMD-SHELL', 'pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
interval: 5s
timeout: 5s
retries: 10
n8n:
image: docker.n8n.io/n8nio/n8n
restart: always
environment:
- DB_TYPE=postgresdb
- DB_POSTGRESDB_HOST=postgres
- DB_POSTGRESDB_PORT=5432
- DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
- DB_POSTGRESDB_USER=${POSTGRES_NON_ROOT_USER}
- DB_POSTGRESDB_PASSWORD=${POSTGRES_NON_ROOT_PASSWORD}
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
- GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
ports:
- 5678:5678
volumes:
- n8n_storage:/home/node/.n8n
depends_on:
postgres:
condition: service_healthy
O volume n8n_storage em /home/node/.n8n continua sendo necessário mesmo com PostgreSQL. O n8n ainda armazena metadados da chave de criptografia nesse diretório.
O parâmetro DB_POSTGRESDB_HOST deve corresponder ao nome do serviço no Docker Compose ("postgres"), e não "localhost".
init-data.sh
Este script cria o usuário não-root do banco de dados na primeira inicialização. Crie o arquivo e execute chmod +x init-data.sh:
#!/bin/bash
set -e;
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB"
CREATE USER "$POSTGRES_NON_ROOT_USER" WITH PASSWORD '$POSTGRES_NON_ROOT_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE "$POSTGRES_DB" TO "$POSTGRES_NON_ROOT_USER";
GRANT ALL ON SCHEMA public TO "$POSTGRES_NON_ROOT_USER";
EOSQL
Passo 3. Iniciar a stack
docker compose up -dO Docker irá baixar as imagens, iniciar o PostgreSQL, aguardar a verificação de saúde (health check) ser concluída e, em seguida, iniciar o n8n. O n8n se conecta ao PostgreSQL e cria automaticamente todas as tabelas necessárias.
Acesse http://your-server-ip:5678 e crie sua conta de administrador. O primeiro usuário registrado recebe automaticamente permissões de administrador.
Passo 4. Verificar a configuração
Confirme que o n8n está usando o PostgreSQL listando as tabelas:
docker compose exec postgres psql -U n8n_user -d n8n -c "\dt"Você deve ver tabelas como workflow_entity, credentials_entity e execution_entity.
Crie um workflow de teste com um Manual Trigger e um nó Set, execute-o e verifique se a execução aparece no histórico.
Depois, adicione uma credencial de teste, reinicie o n8n com docker compose restart n8n e confirme que a credencial continua acessível.
Migrando do SQLite para PostgreSQL
Se você já tem uma instância do n8n rodando com SQLite, utilize o comando export:entities da CLI (disponível a partir do n8n v1.67, novembro de 2025). Ele exporta todos os tipos de entidades e permite importação entre bancos de dados diferentes.
- Pare o n8n: docker compose stop n8n
- Exporte os dados:
- Configure o PostgreSQL seguindo os passos 1 a 3 acima. Use a mesma N8N_ENCRYPTION_KEY da sua instância antiga. Isso é essencial: uma chave diferente tornará todas as credenciais ilegíveis.
- Importação:
- Inicie o n8n e verifique se os workflows, credenciais e usuários foram migrados corretamente e continuam intactos.
docker exec -u node -it \
n8n export:entities --outputDir=/home/node/.n8n/backup
Adicione --includeExecutionHistoryDataTables=true caso queira incluir o histórico de execuções (isso pode gerar um volume de dados muito grande).
docker exec -u node -it \
n8n import:entities --inputDir=/home/node/.n8n/backup
Para versões do n8n anteriores à 1.67, que não possuem o comando export:entities, utilize:
- n8n export: workflow --all;
- n8n export: credentials --all --decrypted.
Esses comandos exportam apenas workflows e credenciais, mas não incluem usuários, projetos ou pastas.
Recomendações pós-configuração
Backups
Execute backups regulares do banco de dados usando pg_dump. Diferente do SQLite, esse processo funciona enquanto o n8n está em execução:
docker compose exec postgres pg_dump -U n8n_user -d n8n > backup_$(date +%F).sqlAgende esse comando via cron (por exemplo, diariamente às 3h da manhã). Mantenha vários backups recentes e teste periodicamente a restauração para garantir que estão válidos.
HTTPS
Coloque um reverse proxy (como Nginx ou Caddy) na frente do n8n e configure um certificado TLS via Let’s Encrypt. Evite expor diretamente a porta 5678 na internet.
Sem HTTPS, credenciais de login e dados de workflows podem trafegar em texto puro.
Limpeza de execuções
O n8n salva o resultado de cada execução de workflow. Desde 2025, a limpeza automática (pruning) vem ativada por padrão: 14 dias de histórico e até 10.000 registros.
Esse comportamento pode ser ajustado com as variáveis de ambiente:
- EXECUTIONS_DATA_MAX_AGE (em horas);
- EXECUTIONS_DATA_PRUNE_MAX_COUNT.
Problemas comuns
-
O n8n inicia, mas usa SQLite em vez de PostgreSQL
Verifique se DB_TYPE está definido como postgresdb (não postgres).
Confirme também se todas as variáveis DB_POSTGRESDB_* estão presentes no ambiente. Se alguma estiver ausente, o n8n pode voltar automaticamente para SQLite sem avisar. -
“Connection refused” na inicialização
Certifique-se de que DB_POSTGRESDB_HOST corresponde ao nome do serviço no Docker Compose ("postgres"), e não "localhost". Os containers se comunicam pela rede interna do Docker, não pelo loopback.
Também verifique se o healthcheck do container PostgreSQL está passando antes do n8n tentar se conectar.
-
Credenciais vazias após a migração
A N8N_ENCRYPTION_KEY na nova instância não coincide com a antiga. O n8n não consegue descriptografar credenciais criadas com uma chave diferente. Confirme o valor da chave e repita a importação se necessário.
-
Erro “Column already exists” durante a migração
Isso ocorre quando os dados são importados em um banco onde o n8n já executou migrações anteriormente. O banco de destino deve estar vazio antes da importação. Se necessário, apague e recrie o banco de dados e execute a importação novamente.
Conclusão
Três arquivos e um único comando docker compose up são suficientes para ter uma instância de n8n pronta para produção com PostgreSQL.
Essa configuração permite backups seguros em tempo real, execução simultânea de workflows e um caminho claro para escalar com queue mode quando necessário.
Para começar mais rápido, você também pode implantar o n8n na Serverspace com um ambiente pré-configurado e adicionar o PostgreSQL seguindo os passos deste guia.
