Fundamentos de Gestión de Cambios

8 ejemplos para empezar con la gestión de cambios en Postgres: 5 básicos y 3 intermedios.

Prerrequisitos

# Las migraciones se ejecutan a través de tu herramienta estándar con revisión
flyway -url="$DATABASE_URL" info
# o
liquibase --changelog-file=db/changelog.xml status

• Una matriz de riesgo de DDL escrita en el repositorio docs/ o runbooks/.
• Volumen de datos en staging dentro de 10 veces el número de filas de producción para pruebas de bloqueo realistas.
• Aprobación de CAB o asíncrona para cambios de alto riesgo según tu nivel de cumplimiento.

Ejemplos Básicos

1. Matriz de Niveles de Riesgo de DDL

Asigna un nivel a cada migración antes de fusionarla.

• Etiqueta los scripts de Flyway/Liquibase con -- risk: medium en los comentarios del encabezado.
• Bloquea el despliegue si el nivel excede la política de ventana actual.

Relacionado: Mejores Prácticas de Gestión de Cambios - lista de verificación de aplicación

2. Protección de Tiempo de Espera de Bloqueo en Migraciones

Evita que las migraciones esperen indefinidamente por bloqueos.

-- Establecer al inicio de la sesión de migración (callback de Flyway o pre-sql de Liquibase)
SET lock_timeout = '5s';
SET statement_timeout = '30min';
SET idle_in_transaction_session_timeout = '5min';
 
ALTER TABLE orders ADD COLUMN IF NOT EXISTS priority smallint;

• El fallo del tiempo de espera de bloqueo aborta rápidamente en lugar de congelar el proceso de pago.
• Reintenta las migraciones de riesgo medio en una ventana más tranquila.
• Registra los fallos de tiempo de espera de bloqueo en el ticket de cambio automáticamente.

3. Fase de Expansión: Añadir Columna Nullable

Primer paso seguro de expandir/contraer.

-- Expandir: añadir columna (instantáneo en PostgreSQL 11+ para valor nulo por defecto)
ALTER TABLE customers ADD COLUMN IF NOT EXISTS tier text;
 
-- Despliegue de la aplicación escribe el nivel solo en las nuevas filas (con flag de funcionalidad)
-- Relleno en lotes
UPDATE customers SET tier = 'standard' WHERE tier IS NULL AND id BETWEEN 1 AND 10000;

• Nunca añadas NOT NULL sin un valor por defecto en un solo paso en tablas grandes.
• Lote UPDATE con rangos de claves primarias para evitar bloqueos largos.
• Monitoriza el retraso de la replicación durante el relleno.

4. Fase de Contracción: Eliminar Columna No Utilizada

Solo después de que el código ya no lea la columna.

-- Verifica cero lecturas en pg_stat_user_tables (aproximado) y métricas de la aplicación
SELECT relname, seq_scan, idx_scan FROM pg_stat_user_tables WHERE relname = 'customers';
 
-- Contraer
ALTER TABLE customers DROP COLUMN IF EXISTS legacy_code;

• Regla de dos lanzamientos: despliega código que ignora la columna, luego elimina la columna.
• Realiza una copia de seguridad lógica o asegúrate de tener PITR antes de eliminaciones de alto riesgo.

5. Plantilla de Ticket de Cambio

Cada DDL de producción vincula la evidencia.

## CHG-2044 Añadir orders.priority
- Nivel de riesgo: Medio
- Migración: V2044__orders_priority.sql
- Radio de explosión: tabla orders (42M filas), servicio de checkout
- Reversión: DROP COLUMN priority (después de revertir la aplicación)
- Prueba de bloqueo: pasada en staging 2026-07-08
- Consciente del personal de guardia: sí

• Adjunta EXPLAIN para cualquier índice nuevo.
• Anota la duración esperada del cronómetro de staging.

Relacionado: Ventanas de Mantenimiento - cuándo programar

Ejemplos Intermedios

6. Patrón de Clave Externa NOT VALID

Añade la aplicación de restricciones sin bloquear escrituras en filas existentes.

ALTER TABLE line_items
  ADD CONSTRAINT line_items_order_id_fkey
  FOREIGN KEY (order_id) REFERENCES orders(id)
  NOT VALID;
 
-- Valida más tarde en una ventana más pequeña (todavía toma ShareUpdateExclusiveLock)
ALTER TABLE line_items VALIDATE CONSTRAINT line_items_order_id_fkey;

• NOT VALID solo añade metadatos; las filas incorrectas existentes permanecen hasta la validación.
• Ejecuta la limpieza de datos antes de VALIDATE CONSTRAINT.
• Documenta la consulta de filas huérfanas en el ticket.

7. Adición de Índice sin Tiempo de Inactividad Cero

Construcción concurrente para tablas OLTP.

CREATE INDEX CONCURRENTLY IF NOT EXISTS orders_customer_id_idx
  ON orders (customer_id);
 
-- Flyway: desactiva el envoltorio de transacción para este script

# Verifica que el índice sea válido
psql -c "SELECT indisvalid FROM pg_index WHERE indexrelid = 'orders_customer_id_idx'::regclass;"

• Los índices concurrentes inválidos requieren REINDEX CONCURRENTLY (ver solución de problemas).
• No envuelvas CREATE INDEX CONCURRENTLY en un bloque de transacción.

8. Cambio Digno de Sev: Actualización de Versión Principal

Trata pg_upgrade como un lanzamiento de producto, no como un parche.

## Pre-vuelo
- [ ] Copia de seguridad lógica + punto de control PITR verificado
- [ ] Matriz de compatibilidad de extensiones (pgvector, PostGIS)
- [ ] Reversión = mantener el clúster antiguo detenido, revertir DNS
- [ ] Cadena de conexión de la aplicación probada en PG 18.4 staging

• Ejecuta pg_upgrade --check en un clon primero.
• Reserva 2 veces la ventana esperada para la primera actualización principal en el equipo.

Relacionado: Antes/Después: Actualización de Versión Principal - referencia narrativa

Versiones de la pila: 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+.