Métodos de migración: cuándo usar cada uno

Cada método tiene un perfil diferente de riesgo, tiempo de inactividad y complejidad operativa.

  • pg_upgrade: el método más rápido. Convierte los archivos del cluster in-place. Con --link usa hard links y evita copiar datos. Requiere ventana de mantenimiento completa (minutos a pocos horas). El más usado para migraciones planificadas.
  • Dump/restore (pg_dump + pg_restore): el más simple conceptualmente pero con mayor downtime proporcional al tamaño de la base. Útil para bases pequeñas o cuando hay cambios de schema significativos.
  • Replicación lógica (zero-downtime): permite migrar con downtime mínimo (segundos) replicando datos al nuevo servidor PG16 mientras PG14 sigue en producción. Es el método más complejo y requiere compatibilidad de todas las tablas con replicación lógica.

Cambios importantes entre PostgreSQL 14 y 16

  • PG15: MERGE SQL añadido, cambios en permisos por defecto de public schema, pg_wal_summary
  • PG16: pg_stat_io view nueva, mejoras en logical replication (suscripción desde standby, filtro por columna y fila), vacuum_buffer_usage_limit, mejoras en paralelismo de VACUUM
  • Parámetro eliminado: wal_keep_segments fue reemplazado por wal_keep_size en PG13. Si tienes ese parámetro en tu postgresql.conf, PG16 no arrancará
  • Permisos en public schema (PG15+): ya no se otorgan permisos CREATE por defecto al rol PUBLIC. Aplicaciones que crean tablas en el schema public pueden fallar

Checklist previo a la migración

  • 1. Verificar extensiones instaladas y su compatibilidad con PG16
  • 2. Ejecutar pg_upgrade en modo --check primero Esto detecta incompatibilidades sin modificar nada. Es obligatorio antes de ejecutar la migración real.
  • 3. Listar y revisar objetos inválidos Objetos inválidos pueden causar errores post-migración en funciones dependientes.
  • 4. Revisar parámetros deprecated o eliminados en postgresql.conf
  • 5. Verificar que el driver de la aplicación soporta PG16 Psycopg2 >= 2.9.3, JDBC PostgreSQL >= 42.5, libpq >= 16 son compatibles. Drivers muy antiguos pueden fallar.
  • 6. Tener backup completo y verificado de PG14 El backup es el plan de reversa definitivo. Debe estar hecho y probado antes de iniciar.
  • 7. Acordar ventana de mantenimiento y comunicar a stakeholders Definir: inicio, fin esperado, criterio de rollback (si en X minutos no funciona, se revierte), y quién tiene autoridad para aprobar el rollback.
  • 8. Preparar el plan de reversa documentado paso a paso El plan de reversa con pg_upgrade es arrancar el PG14 original (que no se borró). Con dump/restore, restaurar el dump previo. Con replicación lógica, redirigir el tráfico al primario PG14.
  • 9. Validar el nuevo servidor PG16 antes de la migración Instalar las mismas extensiones, verificar que el sistema operativo tiene los paquetes necesarios, y confirmar espacio en disco suficiente (al menos 1.5x el tamaño del cluster PG14).
  • 10. Ejecutar la migración con pg_upgrade (modo real)
  • 11. Validación post-migración: conteo de objetos Compara el número de tablas, funciones, índices y secuencias antes y después.
  • 12. Ejecutar ANALYZE en todas las bases después de pg_upgrade pg_upgrade no transfiere las estadísticas del planificador. Sin ANALYZE, el planificador tomará decisiones subóptimas.

Cuándo escalar o no ejecutar la migración sin acompañamiento experto

  • La base de datos tiene extensiones con código C no mantenido o desarrolladas internamente
  • El sistema no tiene ventana de mantenimiento disponible (operación 24/7 sin tolerancia a downtime)
  • No existe un backup válido y probado previo a la migración
  • La aplicación no tiene suite de pruebas para validar comportamiento post-migración
  • pg_upgrade --check reporta incompatibilidades no documentadas
  • Hay réplicas de streaming o suscriptores lógicos que deben migrarse coordinadamente

Preguntas frecuentes

¿Cuánto tiempo tarda una migración con pg_upgrade --link?

Con --link, la migración usa hard links en vez de copiar archivos, por lo que el tiempo es casi independiente del tamaño de la base: generalmente entre 5 y 30 minutos. La mayor parte del tiempo es el proceso de verificación de objetos y la ejecución del ANALYZE posterior. Sin --link, el tiempo es proporcional al tamaño de la base.

¿pg_upgrade es seguro para producción?

Sí, cuando se ejecuta después de una verificación con --check, con un backup completo previo y en una ventana de mantenimiento acordada. Lleva años de uso en producción y es el método recomendado por la comunidad PostgreSQL para migraciones de versión mayor. El riesgo principal es no tener un plan de reversa documentado si se descubre un problema post-migración.

¿Qué extensiones pueden causar problemas al migrar a PG16?

Las extensiones más frecuentes con incompatibilidades son versiones antiguas de PostGIS (requiere versión específica por cada versión de PG), TimescaleDB (tiene su propio proceso de migración), pg_partman y extensiones desarrolladas internamente con código C que referencian estructuras internas de PostgreSQL. Siempre verificar la matriz de compatibilidad en el repositorio oficial de cada extensión antes de iniciar.

¿Necesito migrar también las réplicas de streaming?

Con pg_upgrade, sí: las réplicas de streaming son incompatibles entre versiones mayores. Debes crear nuevas réplicas de PG16 con pg_basebackup desde el nuevo primario PG16. Con replicación lógica (zero-downtime), puedes mantener réplicas de lectura en PG14 temporalmente durante la transición, pero eventualmente deben migrar. Coordinar la migración de réplicas es parte del plan general y no un paso opcional.

Recursos relacionados