Definición
Una migración es un cambio en la estructura de la base de datos —añadir una tabla, una columna, un índice— escrito como un paso versionado que se aplica una sola vez y queda registrado.
La idea es tratar el esquema como se trata el código: bajo control de versiones, con historial, reproducible. Si alguien clona el proyecto y ejecuta las migraciones, acaba con exactamente la misma estructura que hay en producción.
Sin migraciones, el esquema es un conocimiento que vive en la cabeza de quien lo montó y en un servidor concreto. Con migraciones, es un hecho comprobable.
Cómo funciona
El mecanismo básico es siempre el mismo:
- La base guarda en qué versión está. Puede ser una tabla de migraciones aplicadas o un simple número.
- Al arrancar (o al desplegar), el código compara esa versión con la que espera.
- Si va por detrás, aplica en orden las migraciones que faltan.
- Actualiza el número.
Cada migración es un paso hacia delante. Algunas herramientas piden también el paso hacia atrás para poder revertir, aunque en la práctica revertir un cambio de esquema en producción con datos dentro rara vez es tan limpio como suena.
Ejemplo práctico
En el panel de AEWorks el esquema va por la versión 18, y el mecanismo es deliberadamente simple: SQLite guarda un número entero interno, PRAGMA user_version. Al arrancar se lee ese número; si es menor que la versión que espera el código, se aplican las migraciones que falten y se actualiza.
Eso significa que en cada petición solo se lee un entero. No se lanza un solo ALTER TABLE.
Lo digo así de explícito porque el antipatrón contrario me lo encontré en el CRM de IMDICA: allí había secciones que ejecutaban un ALTER TABLE ... ADD COLUMN IF NOT EXISTS en cada carga de página, para asegurarse de que la columna existía. Funciona, y a cambio: cada visita hace trabajo de esquema, cualquier error de permisos aparece en producción a mitad de una operación normal, y nadie sabe cuál es el esquema real sin leer todo el código buscando ALTER.
La versión 18 del panel, en cambio, se lee entera en un fichero: qué tablas hay, cuándo se añadió cada una y por qué. Eso es lo que da una migración y no da el otro método.
Reglas para no romper producción
Los cambios aditivos son seguros; los destructivos no. Añadir una tabla o una columna que admite nulos no rompe nada. Borrar una columna o renombrarla rompe el código que todavía la usa.
Renombrar se hace en tres pasos, no en uno:
- Añadir la columna nueva y escribir en las dos a la vez.
- Desplegar el código que lee de la nueva.
- En un despliegue posterior, borrar la vieja.
Es más lento y es la diferencia entre un cambio tranquilo y un rato de caída.
Cuidado con las tablas grandes. Un ALTER TABLE sobre millones de filas puede bloquear la tabla varios minutos. Hay que mirar cómo lo hace tu motor y, si hace falta, usar herramientas de cambio en línea.
Copia de seguridad antes de una migración destructiva. Y comprobada, no supuesta.
Prueba la migración con datos de verdad, no con una base vacía. Muchos fallos solo aparecen cuando hay filas que no cumplen la nueva restricción.
Errores comunes
- Editar una migración ya aplicada. Los entornos donde ya corrió no la volverán a ejecutar y acabarás con esquemas distintos. Se corrige creando una migración nueva.
- Cambiar el esquema a mano en producción. A partir de ahí, tu historial miente.
- Meter datos en la migración de estructura. Sepáralas: una cosa es crear la columna y otra rellenarla.
- Añadir una columna
NOT NULLsin valor por defecto a una tabla con filas. Falla al instante. - No probar el orden. Si dos personas crean migraciones a la vez, el orden en que se aplican importa.
- Olvidar que los índices también son esquema. Un volcado restaurado sin índices convierte producción en un lugar muy lento.
Cuándo usarlas
Desde el primer día de cualquier proyecto que vaya a durar. El coste de montarlo al principio son diez minutos; el de introducirlo dos años después, cuando hay tres entornos con esquemas divergentes, es un fin de semana.
Incluso en un proyecto de una sola persona compensa. Sobre todo en un proyecto de una sola persona: dentro de un año no te vas a acordar de por qué esa columna se llama así.
