Migrar datos maestros suena trivial — exportar de un lado, importar del otro. En la práctica, en sistemas con años encima, las relaciones rotas aparecen tres semanas después del go-live, cuando alguien intenta facturar a un cliente que perdió su sucursal en el camino.

El problema con la migración “tabla por tabla”

Si exporta clientes y luego importa facturas, las facturas tienen referencias a IDs que ya no existen. Si hace lo inverso, los clientes nuevos no tienen historial. Si lo hace en orden topológico estricto, va a hacer cuatro pases por la base.

El patrón de tres pases

Lo que terminamos haciendo en todos los proyectos grandes:

  1. Pase 1 — estructura: cree todas las entidades (clientes, productos, cuentas) sin relaciones cruzadas. Solo los datos auto-contenidos. Mapee IDs viejos → IDs nuevos en una tabla puente.
  2. Pase 2 — vínculos: pasee transacciones y entidades con foreign keys, traduciendo cada referencia vía la tabla puente. Las FKs ahora apuntan a IDs nuevos válidos.
  3. Pase 3 — derivados: recalcule saldos, totales, agregaciones. Esto NO se migra — se recomputa. Si los datos base están bien, los derivados saldrán bien.
▸ Tabla puente La tabla puente (legacy_id → new_id, por tipo) es la pieza más valiosa y la que más se olvida. Manténgala incluso después del go-live — la va a necesitar cuando alguien pregunte “¿por qué este cliente se llama distinto en el sistema viejo?”.

Validación

Para cada tipo de entidad: count en origen == count en destino. Para FKs: cero registros con referencias nulas que antes no eran nulas. Para saldos: total en origen == total en destino (a la centésima). Si algo no cuadra, no se migra, se investiga.