PostgreSQL
Migraciones seguras mediante expand-contract, cambios compatibles, índices concurrentes, backfills por lotes y control de locks durante despliegues.
Una migración de producción no es solo DDL correcto: debe convivir temporalmente con aplicaciones viejas y nuevas, controlar locks, backfills, WAL y una ruta de recuperación.
El cambio seguro suele seguir expand → migrate → contract:
expand: añadir forma compatible
migrate: mover lecturas/escrituras y datos
contract: retirar lo antiguo despuésEn un rolling deploy, un rename directo rompe procesos viejos. Estrategia:
total_amount nullable.total.Dual write necesita duración corta, observabilidad y una fuente de verdad definida.
Patrón:
CHECK (column IS NOT NULL) NOT VALID cuando la estrategia/versión lo justifique.VALIDATE CONSTRAINT.NOT NULL mediante ruta compatible.Validar y cambiar catálogo tienen locks distintos; revisa versión y tabla.
ALTER TABLE order_items
ADD CONSTRAINT order_items_order_fk
FOREIGN KEY (order_id) REFERENCES orders(id)
NOT VALID;
ALTER TABLE order_items
VALIDATE CONSTRAINT order_items_order_fk;Filas nuevas se comprueban; la validación histórica se ejecuta después con menor bloqueo que un alta inmediata ordinaria.
CREATE INDEX CONCURRENTLY orders_customer_idx
ON orders(customer_id);La herramienta debe permitir migraciones no transaccionales. Después verifica indisvalid y limpia/reintenta conscientemente.
DDL aparentemente instantáneo puede esperar detrás de una transacción larga. Mientras espera, puede formar una cola.
Usa:
SET lock_timeout = '2s';
SET statement_timeout = '30s';y reintenta en ventana controlada. No dejes una migración esperando indefinidamente.
El comportamiento de ADD COLUMN ... DEFAULT mejoró en versiones modernas para defaults constantes, pero expresiones volátiles, cambios de tipo y otras operaciones pueden reescribir la tabla. Comprueba la major version y prueba con volumen real.
Características:
Ejemplo:
UPDATE orders
SET total_amount = total
WHERE id > $1 AND id <= $2
AND total_amount IS NULL;No uses OFFSET para progreso mutable. Registra last key y cuenta pendientes.
Algunos casts son metadata-only; otros reescriben toda la tabla:
ALTER TABLE events
ALTER COLUMN payload TYPE jsonb USING payload::jsonb;Para tablas grandes puede convenir columna paralela + backfill + cutover.
No toda migración es reversible:
DROP COLUMN pierde datos.Rollback puede significar:
No confíes en un down() generado automáticamente.
Migration role posee o asume owner. Runtime no debe ejecutar DDL. Las migraciones deben aplicar grants/default privileges y calificar schemas.
Nunca edites una migración ya aplicada. Crea una nueva corrección. El mismo identificador con SQL distinto rompe reproducibilidad entre entornos.
Prueba desde snapshot representativo:
schema expand
→ app compatible
→ backfill
→ verificación
→ app usa nuevo contrato
→ contract posteriorNo mezcles eliminación destructiva con el primer deploy consumidor.
CREATE INDEX normal sobre tabla activa grande.down no garantiza rollback?CREATE INDEX CONCURRENTLY fallido?Seeds, fixtures y datos de prueba separa referencia, pruebas y demostración sin contaminar producción.