Mejores Prácticas para Migraciones

Reglas para el cambio de esquema versionado que sobrevive al despliegue continuo, tablas grandes y reversiones a las 3 AM.

Cómo Usar Esta Lista

• Bloquea cada PR de migración con las secciones A, B y C.
• Requiere revisión de DBA para los ítems D en tablas con más de 10M de filas o rutas críticas de SLA.
• Revisa la sección E después de cada incidente relacionado con migraciones.

A - Proceso y Git

• Historial de migraciones ordenado en git. Sin DDL manual en producción fuera del pipeline.
• Revisa las migraciones como código de aplicación. Mínimo dos pares de ojos.
• Nunca edites archivos de migración aplicados. Corrige hacia adelante solo con una nueva versión.
• CI aplica la cadena completa a una base de datos vacía en cada PR. Detecta errores de ordenamiento y permisos.
• Empareja la versión principal de PostgreSQL en CI con el objetivo de producción. El comportamiento de extensiones y DDL difiere.

B - Roles y Seguridad

• Las migraciones se ejecutan como app_migrator, los objetos pertenecen a app_owner. El rol de tiempo de ejecución no tiene DDL.
• Establece lock_timeout en el SQL de la migración. Falla rápido en lugar de bloquear el tráfico de la aplicación.
• Establece statement_timeout sensato por tipo de sentencia. Alto para CONCURRENTLY, bajo para DDL de prueba.
• Otorga privilegios en la migración o privilegios predeterminados. Éxito del despliegue sin errores de permisos en tiempo de ejecución.
• Documenta migraciones no transaccionales. CREATE INDEX CONCURRENTLY en un archivo separado con la transacción del runner deshabilitada.

C - Diseño de Cero Tiempo de Inactividad

• Expande antes de contraer; nullable antes de NOT NULL. Cambios disruptivos en múltiples lanzamientos.
• Usa CREATE INDEX CONCURRENTLY en tablas grandes. Verifica indisvalid después de la ejecución.
• ADD CONSTRAINT NOT VALID y luego VALIDATE por separado. Evita escaneos largos de ACCESS EXCLUSIVE.
• Rellena en bloques con monitoreo del lag de replicación. Ninguna transacción UPDATE de mil millones de filas.
• Analiza tablas después de grandes cambios de datos. Las estadísticas del planificador quedan obsoletas después del relleno.

D - Reversión y Recuperación

• ADR: esquema solo hacia adelante en producción. La aplicación se revierte; el esquema avanza con la migración de corrección.
• Prueba la compatibilidad de la reversión de la aplicación con el esquema de fase de expansión. El binario antiguo debe ejecutarse en las nuevas columnas nulas.
• Copia de seguridad o punto de restauración (PITR) antes de las migraciones de contracción. DROP COLUMN es irreversible sin restauración.
• Scripts de reversión de Liquibase/Flyway solo en clones. No se ejecutan automáticamente en producción.
• Flags de características coordinan las fases del esquema. Interruptor de emergencia sin migración de contracción.

E - Observabilidad

• Registra la duración de la migración y las esperas de bloqueo en el pipeline de despliegue. Identifica los que tardan mucho antes de que bloqueen la producción.
• Alerta sobre índices inválidos después del despliegue. CONCURRENTLY fallido deja minas terrestres.
• Consultas de humo post-despliegue en CI/CD. psql -f assert_schema.sql con ON_ERROR_STOP.
• Rastrea la propiedad de las migraciones en CODEOWNERS. El equipo de datos revisa db/migration/**.
• Incluye estimaciones del recuento de filas en la descripción del PR para DDL grandes. Establece las expectativas del revisor.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Migraciones - fundamentos
• DDL de Cero Tiempo de Inactividad - patrones concurrentes
• Reglas de Seguridad para Migraciones - lista de reglas

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.