Migrar PostgreSQL 15 a 17 en una stack Docker

Por qué migrar ahora — EOL de PG 15 y la señal Supabase

docker exec <container> psql -U postgres -c 'SELECT version();'

Qué cambia realmente entre PG 15 y PG 17

• search_path reforzado desde PG 15.1 (ADV-2022-00007): el esquema public ya no está en el search_path por defecto para roles no-superuser. Cualquier consulta que asumiera public.mi_tabla puede devolver silenciosamente 0 filas en lugar de un error.
• pg_dump produce dumps incompatibles hacia abajo: un dump de PG 17 no puede restaurarse en PG 15. Lo inverso sí es posible. Conserva los dumps de PG 15 durante al menos 30 días después del cambio.
• wal_level predeterminado elevado a logical en PG 16+: si tu postgresql.conf forzaba wal_level = minimal, el comportamiento cambia tras la migración.
• Eliminación de funciones obsoletas: lo_import, lo_export y ciertas funciones de pg_catalog eliminadas o renombradas entre PG 15 y PG 17 — verificar las funciones usadas en extensiones propias.
• pg_stat_statements modifica la normalización de consultas: los dashboards de Grafana/PgHero que agregan por query fingerprint verán sus series reiniciadas tras la migración.
• pg_partman (gestión de particionamiento) requiere versión ≥ 5.x para PG 17 — la versión 4.x no es compatible.
• timescaledb requiere versión ≥ 2.13 para PG 17; las versiones anteriores rechazan cargar y bloquean el inicio del contenedor.

Inventario de extensiones: qué pasa y qué se rompe

docker exec <pg15_container> psql -U postgres -c \
  "SELECT datname, extname, extversion FROM pg_extension e JOIN pg_database d ON d.oid = e.extnamespace ORDER BY datname, extname;"

docker exec <pg17_container> psql -U postgres -d mydb \
  -c 'SELECT extname, extversion FROM pg_extension ORDER BY extname;'

Procedimiento de migración sin tiempo de inactividad: pg_dump/pg_restore

1. 01

   Fijar la versión de la imagen PG 15

   Antes de cualquier operación, fija la imagen actual en tu docker-compose.yml con su tag exacto:

   docker inspect <pg15_container> --format '{{.Config.Image}}'
   # ej: postgres:15.7

   Confirma este cambio en tu VCS antes de continuar. La migración no puede hacerse en el mismo volumen: PG 17 rechaza iniciar en un PGDATA de PG 15.

2. 02

   Capturar el dump global y los dumps de bases de datos

   Exporta primero los objetos globales (roles, tablespaces), luego cada base de datos individualmente:

   docker exec <pg15_container> pg_dumpall \
     -U postgres \
     --globals-only \
     > backup_globals.sql
   
   docker exec <pg15_container> pg_dump \
     -U postgres \
     --no-owner \
     --no-acl \
     --format=custom \
     --file=/tmp/mydb_pg15.dump \
     mydb
   
   docker cp <pg15_container>:/tmp/mydb_pg15.dump ./mydb_pg15.dump

   Verifica la integridad del dump:

   pg_restore --list mydb_pg15.dump | head -20

3. 03

   Iniciar el contenedor PG 17 en paralelo en un puerto diferente

   Añade un segundo servicio en docker-compose.yml para PG 17, en un puerto distinto (ej. 5433), con un volumen de datos nuevo:

     postgres17:
       image: postgres:17
       environment:
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
         POSTGRES_DB: ${POSTGRES_DB}
       volumes:
         - pg17_data:/var/lib/postgresql/data
       ports:
         - "5433:5432"
       shm_size: 256mb
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
         interval: 5s
         timeout: 3s
         retries: 5
   
   volumes:
     pg17_data:

   Inicia solo este servicio:

   docker compose up -d postgres17
   docker compose exec postgres17 pg_isready

4. 04

   Restaurar en PG 17 y verificar extensiones

   Restaura los objetos globales primero, luego la base de datos:

   docker exec -i <pg17_container> psql -U postgres < backup_globals.sql
   
   docker cp mydb_pg15.dump <pg17_container>:/tmp/mydb_pg15.dump
   
   docker exec <pg17_container> pg_restore \
     -U postgres \
     --no-owner \
     --no-acl \
     -d mydb \
     /tmp/mydb_pg15.dump

   Si pg_restore reporta errores en extensiones:

   docker exec <pg17_container> psql -U postgres -d mydb \
     -c 'CREATE EXTENSION IF NOT EXISTS pgvector;'

5. 05

   Cambiar las aplicaciones y validar

   Pon tus aplicaciones en modo mantenimiento o solo-lectura, luego actualiza la variable DATABASE_URL de cada servicio para apuntar al contenedor PG 17 en el puerto 5432. Reinicia los servicios de aplicación:

   curl -sf http://localhost/api/health | jq .database

   Si la validación pasa, detén el contenedor PG 15 y remapea el puerto 5432 a postgres17.

El caso Supabase: postgres:17 sin advertencia

docker logs <supabase_db_container> 2>&1 | head -20
# FATAL: database files are incompatible with server
# DETAIL: The data directory was initialized by PostgreSQL version 15, which is not compatible with this version 17.

  db:
    image: supabase/postgres:15.8.1.040
    # o la última 17.x una vez completada la migración
    # image: supabase/postgres:17.4.1.016

Estrategias de migración: pg_dump/restore vs pg_upgrade vs replicación lógica

Desplace la tabla

Resolución de problemas: errores frecuentes y sus causas

Checklist de conmutación — validar en orden antes de cada paso

• Antes de comenzar: lista de extensiones activas extraída (pg_extension), versión PG 15 fijada en Compose, dump completo validado (pg_restore --list sin errores).
• Tras restaurar en PG 17: todas las extensiones presentes en la versión correcta, search_path verificado via rol de aplicación (no superuser), recuentos de filas comparados en las 5 tablas críticas.
• Antes del cambio de aplicación: ventana de mantenimiento anunciada, modo solo-lectura activado si es posible, último dump de coherencia capturado desde PG 15.
• Tras el cambio de aplicación: endpoint /health devuelve 200 con database: ok, logs de aplicación sin errores relation does not exist.
• Retención PG 15: volumen PG 15 conservado 30 días mínimo, dump conservado 90 días, procedimiento de rollback documentado.
• Post-migración: ANALYZE VERBOSE; ejecutado en todas las bases, autovacuum confirmado activo, monitoreo actualizado para PG 17.

Gestionar la migración en un portfolio de clientes

docker ps --format '{{.Names}}' | xargs -I{} sh -c \
  'docker exec {} psql -U postgres -qtAX -c "SELECT current_setting(\"server_version\")" 2>/dev/null && echo " <- {}"'