Corrigir "a foreign key constraint fails" ao importar um dump SQL

Exporta uma base de dados, tenta carregá-la numa instância nova e o MySQL devolve:

Ou, no PostgreSQL:

Porque é que isto acontece

Uma chave estrangeira diz “cada orders.user_id tem de apontar para um users.id existente.” Quando o dump insere orders antes de users, a linha pai referenciada ainda não existe e a base de dados rejeita a linha.

A maioria das ferramentas de dump escreve as tabelas por ordem alfabética ou por ordem de criação — não por ordem de dependência das chaves estrangeiras. Por isso orders (filha) fica frequentemente antes de users (pai) e a importação falha.

Solução 1: reordenar os INSERTs por dependência (a correção certa)

A solução limpa é inserir cada tabela pai antes das suas filhas. Isso significa resolver as chaves estrangeiras num grafo de dependências e carregar as tabelas por ordem topológica: users → orders → order_items.

Fazer isto à mão num ficheiro de vários gigabytes é penoso — tem de seguir cada FOREIGN KEY ao longo das instruções CREATE TABLE e ALTER TABLE e cortar/colar enormes blocos INSERT na sequência certa.

Solução 2: desativar a verificação de chaves estrangeiras durante a importação

Para um dump completo e já consistente, pode ignorar a validação com segurança durante o carregamento. No MySQL, envolva o ficheiro:

-- MySQL
SET FOREIGN_KEY_CHECKS = 0;
-- ... todas as suas instruções INSERT ...
SET FOREIGN_KEY_CHECKS = 1;

No PostgreSQL, adie as restrições dentro de uma transação:

-- PostgreSQL
BEGIN;
SET CONSTRAINTS ALL DEFERRED;
-- ... todas as suas instruções INSERT ...
COMMIT;

Reative as verificações depois, para que as escritas futuras continuem validadas. Isto funciona, mas só disfarça o problema da ordem — se o dump for parcial, pode ainda acabar com linhas órfãs.

Solução 3: faça as duas automaticamente com o DumpCleaner

O DumpCleaner lê o dump, extrai cada chave estrangeira de CREATE TABLE e ALTER TABLE, constrói o grafo de dependências e exporta um ficheiro limpo que simplesmente importa:

1. Arraste o seu dump .sql para o DumpCleaner (MySQL, MariaDB, PostgreSQL, SQLite ou MS SQL).
2. Escolha Ordem dos INSERT → Por dependências (com reconhecimento de FK). Os pais são colocados antes das filhas automaticamente, por ordenação topológica.
3. Opcionalmente, marque Desativar a verificação de chaves estrangeiras — o DumpCleaner envolve a saída com a instrução correta para a sua base de dados.
4. Exporte. Importe o novo ficheiro — o erro de restrição desapareceu.

Deteta até chaves estrangeiras circulares e avisa-o, em vez de produzir uma ordem impossível.

Perguntas frequentes