Corregir «a foreign key constraint fails» al importar un volcado SQL

Exportas una base de datos, intentas cargarla en una instancia nueva y MySQL lanza:

O, en PostgreSQL:

Por qué ocurre esto

Una clave foránea dice «cada orders.user_id debe apuntar a un users.id existente». Cuando el volcado inserta orders antes que users, la fila padre referenciada aún no existe y la base de datos rechaza la fila.

La mayoría de las herramientas de volcado escriben las tablas alfabéticamente o en orden de creación, no en orden de dependencia de claves foráneas. Así que orders (hijo) suele aparecer antes que users (padre) y la importación se rompe.

Solución 1: reordenar los INSERT por dependencia (la solución correcta)

La solución limpia consiste en insertar cada tabla padre antes que sus hijas. Eso significa resolver las claves foráneas en un grafo de dependencias y cargar las tablas en orden topológico: users → orders → order_items.

Hacer esto a mano en un archivo de varios gigabytes es una tortura: tienes que rastrear cada FOREIGN KEY a través de las sentencias CREATE TABLE y ALTER TABLE y cortar y pegar enormes bloques INSERT en la secuencia correcta.

Solución 2: desactivar las comprobaciones de claves foráneas durante la importación

Para un volcado completo y ya consistente puedes omitir la validación de forma segura durante la carga. En MySQL, envuelve el archivo:

-- MySQL
SET FOREIGN_KEY_CHECKS = 0;
-- ... todas tus sentencias INSERT ...
SET FOREIGN_KEY_CHECKS = 1;

En PostgreSQL, aplaza las restricciones dentro de una transacción:

-- PostgreSQL
BEGIN;
SET CONSTRAINTS ALL DEFERRED;
-- ... todas tus sentencias INSERT ...
COMMIT;

Vuelve a activar las comprobaciones después para que las escrituras futuras sigan validándose. Esto funciona, pero solo enmascara el problema de orden: si el volcado es parcial, todavía puedes acabar con filas huérfanas.

Solución 3: hacer ambas cosas automáticamente con DumpCleaner

DumpCleaner lee el volcado, extrae cada clave foránea de CREATE TABLE y ALTER TABLE, construye el grafo de dependencias y exporta un archivo limpio que simplemente se importa:

1. Arrastra tu volcado .sql a DumpCleaner (MySQL, MariaDB, PostgreSQL, SQLite o MS SQL).
2. Elige Orden de INSERT → Por dependencias (según claves foráneas). Los padres se colocan antes que los hijos automáticamente mediante ordenación topológica.
3. Opcionalmente marca Desactivar comprobaciones de claves foráneas: envuelve la salida con la sentencia correcta para tu base de datos.
4. Exporta. Importa el nuevo archivo: el error de restricción ha desaparecido.

Incluso detecta claves foráneas circulares y te avisa en lugar de producir un orden imposible.

Preguntas frecuentes