¿Por qué una aplicación autoalojada ejecuta la misma migración de base de datos dos veces después de volver a implementarla?

Eva Wong es la redactora técnica y manitas residente en ZimaSpace. Es una geek de toda la vida apasionada por los laboratorios domésticos y el software de código abierto, y se especializa en traducir conceptos técnicos complejos en guías prácticas y fáciles de seguir. Eva cree que alojar servicios propios debería ser divertido, no intimidante. A través de sus tutoriales, ayuda a la comunidad a desmitificar la configuración del hardware, desde montar su primer NAS hasta dominar los contenedores Docker.

Una migración de base de datos puede ejecutarse dos veces cuando más de una ruta de inicio, contenedor o programador cree que es responsable del mismo paso de actualización.

Las aplicaciones autoalojadas suelen iniciar migraciones desde un punto de entrada, un proceso web, un worker, un sidecar, una unidad systemd o un hook de despliegue. Tras volver a desplegar, un contenedor antiguo puede solaparse con uno nuevo, una política de reinicio puede volver a ejecutar un migrador fallido o dos réplicas pueden acceder a la base de datos antes de que una registre que la migración se ha completado. El diagnóstico debe identificar todos los procesos que podrían ejecutarla y confirmar si el framework de migraciones utiliza un bloqueo persistente o un registro del historial del esquema antes de iniciar cualquier reparación de datos.

Identifica todos los procesos que pueden iniciar la migración

Busca el comando de migración en el punto de entrada de la imagen, el comando de Compose, el comando del worker, la unidad systemd, la tarea cron, el script de despliegue y el registro de inicio de la aplicación. Anota los ID de proceso y los nombres de los contenedores en los dos momentos de ejecución.

Docker Compose puede iniciar los servicios según las dependencias declaradas, pero el orden de inicio por sí solo no hace que la migración a nivel de aplicación tenga un único responsable. La guía oficial sobre el orden de inicio explica por qué que una base de datos esté disponible y que la migración tenga un único responsable son condiciones distintas.

Si el mismo comando aparece tanto en el punto de entrada web como en un servicio de migración dedicado, elimina uno de los responsables. Si solo existe un comando, continúa comprobando las réplicas, los bucles de reinicio y los registros del estado de la migración.

Comprueba si se solapan contenedores antiguos y nuevos

Enumera los contenedores en ejecución, reiniciándose, detenidos y huérfanos durante el despliegue. Compara los nombres de los proyectos y servicios, los ID de los contenedores y las marcas de tiempo de creación.

Systemd documenta que la política de reinicio de un servicio puede volver a ejecutar un comando fallido según la configuración de la unidad. Su modelo de reinicio de servicios ayuda a explicar por qué un lanzador del host puede volver a ejecutar la migración después de que el intento dentro del contenedor termine con un código distinto de cero.

Elimina los procesos huérfanos cuya condición se haya confirmado solo después de conservar sus registros. Una segunda marca de tiempo de migración poco después de la primera suele indicar un reintento y no un trabajo programado por separado.

Usa un bloqueo de base de datos antes de aplicar cambios al esquema

Determina si la aplicación adquiere un bloqueo a nivel de base de datos antes de leer el estado de la migración y aplicar cambios. Prueba dos intentos de inicio simultáneos en un entorno desechable.

PostgreSQL ofrece bloqueos consultivos para la coordinación definida por la aplicación, que permiten que un proceso de migración excluya a otro incluso si ambos se inician casi al mismo tiempo.

Un bloqueo debe cubrir todo el período de decisión y ejecución. Comprobar la versión actual del esquema antes de adquirir el bloqueo sigue permitiendo que dos procesos elijan la misma migración pendiente.

Verifica la semántica de los bloqueos en MySQL o MariaDB

En aplicaciones compatibles con MySQL, comprueba si la herramienta de migración utiliza un bloqueo con nombre, una transacción o una tabla de bloqueos, y si la conexión permanece activa durante toda la migración.

MySQL documenta los bloqueos con nombre vinculados a la conexión, que se liberan cuando termina la sesión propietaria y, por lo tanto, deben adquirirse de nuevo de forma segura tras un fallo o reinicio.

Una conexión fallida puede liberar el bloqueo antes de que el marco de migraciones registre la finalización. Compara los registros de la base de datos con las marcas de tiempo de reinicio del contenedor para identificar esta secuencia.

Inspecciona la tabla del historial del marco de migraciones

Enumera los identificadores de migración, el orden de ejecución, los indicadores de éxito, las sumas de comprobación y las marcas de tiempo. Compara las dos ejecuciones registradas con los registros que realmente se confirmaron en la base de datos.

Flyway usa una tabla del historial del esquema para hacer un seguimiento de las migraciones aplicadas y sus estados.

Si la primera ejecución modificó el esquema pero falló antes de registrar el éxito, la segunda puede volver a intentar una migración que no se diseñó para ser idempotente. Repara el historial solo después de comparar el esquema real con el resultado esperado de la migración.

Comprueba los cambios en la identidad del registro de cambios y en las sumas de comprobación

Compara los nombres de archivo, los ID, los autores, las rutas y las sumas de comprobación de las migraciones antes y después de actualizar la imagen. Determina si la imagen contiene entradas de registro de cambios duplicadas o renombradas.

Liquibase registra los cambios ejecutados en la tabla DATABASECHANGELOG, donde la identidad del cambio depende de su ID, autor y ruta del archivo.

Mover un archivo de registro de cambios o volver a generar identificadores puede hacer que el trabajo antiguo parezca nuevo, aunque el SQL sea similar. Restablece una identidad de migración estable en lugar de eliminar manualmente amplios rangos del historial.

Vuelve a implementar con un único responsable de las migraciones y verifica la idempotencia

Elige un único responsable de las migraciones, añade bloqueos persistentes, haz que los servicios web y de trabajo esperen a que se completen correctamente y vuelve a implementar en una copia de prueba de la base de datos.

El artículo de ZimaSpace sobre los límites de programación de contenedores ofrece la regla relacionada: cada tarea de mantenimiento debe tener un único responsable de ejecución comprobado.

El problema se resuelve cuando los arranques simultáneos o repetidos producen una sola migración aplicada, un único registro persistente en el historial y ninguna segunda modificación del esquema tras reiniciar.

Preguntas frecuentes

¿Ejecutar una migración dos veces siempre daña la base de datos?

No. Las migraciones idempotentes pueden detectar de forma segura los objetos existentes, pero las transformaciones de datos no idempotentes, la creación de índices o los cambios en columnas pueden fallar o duplicar datos.

¿Debería permitirse que todas las réplicas web ejecuten migraciones?

Solo cuando el framework proporciona una coordinación fiable a nivel de base de datos. En una implementación de servidor doméstico, es más fácil auditar si un proceso de migración dedicado se ejecuta una sola vez.

¿Puedo marcar la migración como completada manualmente?

Solo después de comprobar que el esquema activo y los datos coinciden con el resultado esperado de la migración. Editar primero el historial puede ocultar un cambio aplicado parcialmente.

Soporte y consejos

Más para leer

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.