Actualización de versión mayor de PostgreSQL (pg_upgrade / logical replication)

Actualización de versión mayor (p. ej., 16 → 17): elección del método (pg_upgrade --link / --copy / --clone o migración casi sin interrupción con logical replication), pg_upgrade --check, compatibilidad de las extensiones, traslado de la configuración, nueva recopilación de estadísticas, reconstrucción de los standby con rsync o pg_basebackup, eliminación del clúster antiguo y runbook de reversión. Servidor único, streaming replication (primary + standby) y clúster Patroni (procedimiento oficial de major upgrade de Patroni: se detiene Patroni, pg_upgrade en el leader, se elimina el registro del DCS y Patroni vuelve a copiar las réplicas). Familia RHEL y Debian/Ubuntu (incluido pg_upgradecluster).

Para una actualización dentro de la misma versión mayor (p. ej., 17.4 → 17.6) no se usa esta guía, sino pg-minor-update. Para replicación continua a nivel de tabla o una migración parcial, pg-logical-repl; para trasladar una base de datos pequeña a otro servidor con un dump, pg-dump-restore.

Topología: In situ en el mismo servidor (pg_upgrade; servidor único, primary + standby o clúster Patroni) o hacia un servidor nuevo (logical)

Escenarios

• Major upgrade — Actualización de versión mayor (p. ej., 16 → 17): comprobaciones previas, copia de seguridad, pg_upgrade o logical replication, verificación y limpieza.
• Reversión (upgrade fallido / abandonado) — El upgrade quedó a medias o la nueva versión da problemas: vuelta a la versión anterior. Con --link, si el nuevo clúster ya se ha iniciado, solo se puede volver desde la copia de seguridad.

Antes de empezar

• El clúster de origen es PostgreSQL …, instalado desde el repositorio PGDG (pg-install). La versión de destino … es superior a la de origen.
• La aplicación y los drivers se han probado con PostgreSQL …; la misma actualización se ha ensayado antes en un entorno de pruebas. Se han leído las secciones "Migration to Version" de las release notes de cada versión mayor hasta … (parámetros eliminados, cambios de comportamiento).
• Existe una versión para … de todas las extensiones instaladas (PostGIS, pg_repack, pgaudit, TimescaleDB…). Si una extensión no existe para …, no se puede hacer el upgrade.
• …Hay espacio libre igual al tamaño actual de los datos para el nuevo directorio de datos.…El directorio de datos antiguo y el nuevo están en el mismo sistema de archivos (requisito de los hard links); hay unos GB libres para WAL y el nuevo catálogo.…El sistema de archivos admite reflink (XFS reflink=1 o Btrfs) y ambos directorios están en el mismo sistema de archivos.…
• Se han listado los logical replication slots / subscriptions, si los hay: …con un origen PostgreSQL 17+, pg_upgrade traslada los slots lógicos, pero todos los cambios deben haberse consumido…con un origen PostgreSQL …, pg_upgrade no traslada los slots lógicos; hay que volver a crearlos tras el upgrade….
• Hay SSH sin contraseña con el usuario postgres desde el primary a cada standby y rsync está instalado en los standby. La estructura del directorio de datos es …/<versión>/data (rsync usa el directorio padre común).
• Los standby están en streaming; el pg_hba.conf del primary permite la conexión de replicación y la contraseña de … está en ~postgres/.pgpass en los standby.
• El clúster Patroni está sano: … es el leader actual, todas las réplicas están en streaming sin retardo y no hay Pending restart. Nombre del clúster …, configuración …, contraseñas de la REST API en /etc/patroni/patroni.env (estructura de pg-patroni). Se ha hecho una copia de seguridad snapshot del DCS (etcd). Durante el upgrade el clúster estará completamente parado: se rechazan las conexiones que llegan por HAProxy/VIP.
• La versión de Patroni admite PostgreSQL … (soporte de la nueva versión mayor en las release notes de Patroni). Un Patroni antiguo puede no reconocer los parámetros ni el archivo de control de la nueva versión; si es necesario, actualice antes Patroni de forma rolling.
• En el servidor de destino PostgreSQL … está instalado con pg-install, vacío y en ejecución; están instaladas las versiones … de las extensiones del origen. El destino puede acceder al puerto … del origen.
• Las tablas que se migran tienen primary key o replica identity (de lo contrario, UPDATE/DELETE fallan en el origen). Añada una PK a las tablas listadas o aplique ALTER TABLE … REPLICA IDENTITY FULL.
• Hay una copia de seguridad reciente con restauración probada… (pgBackRest)…; si es posible, se tomará también un snapshot del servidor o del disco.… Con el método --link es la única vía de vuelta una vez iniciado el nuevo clúster.…

Fases de la guía

• Comprobaciones previas — Comprobar el estado del clúster Patroni · Registrar las propiedades del clúster · Listar los RPM/deb de las extensiones · Comprobar las prepared transactions y las transacciones largas
• Preparación del nuevo clúster — Crear el nuevo directorio de datos · Crear el nuevo clúster con las mismas propiedades (initdb) · Trasladar la configuración al nuevo clúster · Comprobar si hay parámetros no válidos en la nueva versión · Comprobar los parámetros de Patroni frente a la nueva versión
• Copia de seguridad y punto de vuelta atrás — Hacer una copia de seguridad (pgBackRest full) · Hacer una copia de seguridad (pg_dumpall + snapshot)
• Comprobación de compatibilidad (pg_upgrade --check) — pg_upgrade --check
• Interrupción: detener el clúster antiguo — Detener las aplicaciones · Última copia al inicio de la interrupción (pgBackRest incr) · Última copia lógica al inicio de la interrupción · Detener el primary antiguo · Detener Patroni en las réplicas · Detener Patroni en el leader …
• Upgrade — Ejecutar pg_upgrade · Actualizar con pg_upgradecluster · Trasladar los archivos de conf.d al nuevo clúster · Cambiar la configuración de pgBackRest al nuevo clúster · Cambiar bin_dir y data_dir de patroni.yml a la nueva versión · Actualizar la stanza de pgBackRest a la nueva versión …
• Inicio del nuevo clúster — Iniciar el nuevo clúster · Iniciar Patroni en el leader · Iniciar los standby de inmediato
• Tareas posteriores al upgrade — Actualizar las extensiones · Recopilar estadísticas · Comprobación de pgBackRest y nueva copia full
• Verificación — Versión, parámetros y bases de datos · Verificar el clúster Patroni · Comprobar los logs · Pruebas de la aplicación
• Eliminación del clúster antiguo — Borrar el directorio de datos antiguo · Borrar el directorio de datos antiguo en …las réplicas…los standby… · Eliminar el software de la versión antigua
• Preparación del servidor de origen — wal_level = logical · Reiniciar el origen · Crear el usuario de replicación · Añadir el destino a pg_hba.conf · Recargar pg_hba · Crear la publication
• Esquema y subscription en el destino — Escribir las contraseñas del origen en .pgpass · Copiar los roles (globals) · Copiar el esquema · Crear la subscription · Esperar a que termine la copia inicial · Comprobar el retardo
• Cambio final (cutover) — Detener las escrituras en el origen · Verificar que se han transferido los últimos cambios · Transferir los valores de las secuencias · Eliminar la subscription · Recopilar estadísticas · Redirigir las aplicaciones al destino …
• Reversión — Detener el nuevo clúster · Detener Patroni en las réplicas · Detener Patroni en el leader · Restaurar pg_control (--link, nuevo clúster no iniciado) · …Revertir desde la copia de seguridad (--link, nuevo clúster iniciado)…Revertir desde la copia lógica (--link, nuevo clúster iniciado)… · Completar la recovery sin Patroni …