Reglas de seguridad para migraciones

Los trabajos de despliegue de migraciones deben fallar rápidamente ante la contención de bloqueos y nunca bloquear el tráfico de la aplicación de forma ilimitada. Codifica tiempos de espera y DDL por fases en las reglas del equipo.

Receta

-- Primeras líneas de cada archivo de migración de producción
SET lock_timeout = '5s';
SET statement_timeout = '0';        -- permitir CONCURRENTLY de larga duración
SET idle_in_transaction_session_timeout = '60s';

# Envoltorio del trabajo de despliegue
flyway migrate || { echo "la migración falló - la aplicación NO avanzó"; exit 1; }

Cuándo usar esto: Plantilla CI para migraciones SQL, retroceso de incidentes tras acumulación de bloqueos, estandarización de Flyway/Liquibase.

Ejemplo de trabajo

SET lock_timeout = '3s';
 
BEGIN;
CREATE TABLE app.new_feature (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  name text NOT NULL
);
COMMIT;

-- Archivo separado: executeInTransaction=false (Flyway)
SET lock_timeout = '10s';
SET statement_timeout = '0';
 
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_new_feature_name
  ON app.new_feature (name);

Reglas del pipeline de despliegue:

1. El fallo de la migración bloquea el despliegue de la aplicación (misma etapa del pipeline o anterior)
2. Alerta ante lock timeout en los registros de migración
3. Comprobación de índice inválido post-despliegue:

SELECT indexrelid::regclass
FROM pg_index
WHERE NOT indisvalid;

Análisis detallado

Matriz de tiempos de espera

Orden de DDL consciente de bloqueos

1. ADD COLUMN nullable (rápido)
2. Relleno (en lotes, trabajo separado)
3. CREATE INDEX CONCURRENTLY
4. ADD CONSTRAINT NOT VALID
5. VALIDATE CONSTRAINT fuera de horas pico
6. DROP COLUMN solo después de la fase de contrato de la aplicación

Reglas del trabajo de despliegue

• Conexión única de migración (no Flyway paralelo en la misma base de datos)
• Sin migración durante mantenimiento superpuesto que también reinicie Postgres
• Prueba de humo de diferencia de esquema después de la migración
• Despliegue hacia adelante documentado; sin manipulación de la tabla de historial

Trampas comunes

• Zero lock_timeout - La migración espera horas detrás de una consulta analítica de fin de semana. Solución: Establece siempre lock_timeout explícito.
• Mismo statement_timeout para todo SQL - CONCURRENTLY se interrumpe a los 30s en una tabla enorme. Solución: Divide los archivos; deshabilita txn para procesos largos.
• Éxito de migración + índice inválido - Las consultas de la aplicación ignoran el índice roto, tormenta de escaneo secuencial. Solución: Consulta de validez post-despliegue en CI.
• Despliegue de la aplicación antes de la migración - La aplicación antigua accede a una columna que falta. Solución: Migrar primero o expandir el orden compatible.
• Ejecutar migraciones desde el portátil - Omite la verificación de permisos de CI. Solución: Migración a producción solo a través del pipeline.

Alternativas

Preguntas frecuentes

Relacionado

• DDL sin tiempo de inactividad - DDL por fases
• Mejores prácticas de migraciones - lista completa
• Estrategia de reversión - ADR solo hacia adelante

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