pg_upgrade

pg_upgrade
Prev	Up	Aplicaciones de servidor de PostgreSQL	Home	Next

pg_upgrade — actualiza una instancia del servidor de PostgreSQL

Synopsis

pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D newconfigdir [option...]

Descripción

pg_upgrade (anteriormente conocido como pg_migrator) permite que los datos almacenados en los archivos de datos de PostgreSQL se actualicen a una versión mayor posterior de PostgreSQL sin necesidad de la exportación/restauración de datos que típicamente se requiere para las actualizaciones de versiones mayores, por ejemplo, de la 12.14 a la 13.10 o de la 14.9 a la 15.5. No es necesario para las actualizaciones de versiones menores, por ejemplo, de la 12.7 a la 12.8 o de la 14.1 a la 14.5.

Las versiones mayores de PostgreSQL agregan regularmente nuevas características que a menudo cambian el diseño de las tablas del sistema, pero el formato interno de almacenamiento de datos rara vez cambia. pg_upgrade utiliza este hecho para realizar actualizaciones rápidas creando nuevas tablas del sistema y simplemente reutilizando los archivos de datos de usuario antiguos. Si una versión mayor futura cambia el formato de almacenamiento de datos de tal manera que haga que el formato antiguo sea ilegible, pg_upgrade no se podrá utilizar para tales actualizaciones. (La comunidad intentará evitar tales situaciones).

pg_upgrade hace todo lo posible por asegurarse de que los clústeres antiguo y nuevo sean binariamente compatibles, por ejemplo, comprobando configuraciones compatibles en tiempo de compilación, incluyendo binarios de 32/64 bits. Es importante que cualquier módulo externo también sea binariamente compatible, aunque esto no puede ser comprobado por pg_upgrade.

pg_upgrade admite actualizaciones desde la versión 9.2.X y posteriores hasta la versión mayor actual de PostgreSQL, incluyendo versiones de desarrollo (snapshot) y beta.

Warning

Actualizar un clúster hace que el destino ejecute código arbitrario de la elección de los superusuarios del origen. Asegúrate de que los superusuarios del origen sean de confianza antes de realizar la actualización.

Opciones

pg_upgrade acepta los siguientes argumentos de línea de comandos:

-b bindir --old-bindir=bindir

el directorio de ejecutables antiguo de PostgreSQL; variable de entorno PGBINOLD

-B bindir --new-bindir=bindir

el directorio de ejecutables nuevo de PostgreSQL; el valor predeterminado es el directorio donde reside pg_upgrade; variable de entorno PGBINNEW

-c --check

comprueba únicamente los clústeres, sin modificar ningún dato

-d configdir --old-datadir=configdir

el directorio de configuración del antiguo clúster de base de datos; variable de entorno PGDATAOLD

-D configdir --new-datadir=configdir

el directorio de configuración del nuevo clúster de base de datos; variable de entorno PGDATANEW

-j njobs --jobs=njobs

número de conexiones y procesos/hilos simultáneos a utilizar

-k --link

utiliza enlaces duros (hard links) en lugar de copiar archivos al nuevo clúster

-N --no-sync

Por defecto, pg_upgrade esperará a que todos los archivos del clúster actualizado se escriban de forma segura en el disco. Esta opción hace que pg_upgrade retorne sin esperar, lo cual es más rápido, pero significa que una caída posterior del sistema operativo puede dejar el directorio de datos corrupto. Generalmente, esta opción es útil para pruebas pero no debe usarse en una instalación de producción.

-o options --old-options options

opciones que se pasarán directamente al comando postgres antiguo; múltiples invocaciones de opciones se concatenan

-O options --new-options options

opciones que se pasarán directamente al comando postgres nuevo; múltiples invocaciones de opciones se concatenan

-p port --old-port=port

el número de puerto del antiguo clúster; variable de entorno PGPORTOLD

-P port --new-port=port

el número de puerto del nuevo clúster; variable de entorno PGPORTNEW

-r --retain

conserva los archivos SQL y de registro incluso después de una finalización exitosa

-s dir --socketdir=dir

directorio a utilizar para los sockets del postmaster durante la actualización; el valor predeterminado es el directorio de trabajo actual; variable de entorno PGSOCKETDIR

-U username --username=username

nombre de usuario de instalación del clúster; variable de entorno PGUSER

-v --verbose

habilita el registro interno detallado

-V --version

muestra la información de versión y termina

--clone

Utiliza la clonación eficiente de archivos (también conocida como “reflinks” en algunos sistemas) en lugar de copiar archivos al nuevo clúster. Esto puede resultar en una copia casi instantánea de los archivos de datos, ofreciendo las ventajas de velocidad de -k/--link al tiempo que deja el clúster antiguo intacto.

La clonación de archivos solo se admite en algunos sistemas operativos y sistemas de archivos. Si se selecciona pero no es compatible, la ejecución de pg_upgrade fallará con un error. En la actualidad, se admite en Linux (kernel 4.5 o posterior) con Btrfs y XFS (en sistemas de archivos creados con soporte para reflink), y en macOS con APFS.

--copy

Copia los archivos al nuevo clúster. Este es el comportamiento predeterminado. (Véase también --link, --clone, --copy-file-range y --swap).

--copy-file-range

Utiliza la llamada al sistema copy_file_range para una copia eficiente. En algunos sistemas de archivos, esto ofrece resultados similares a --clone, compartiendo bloques físicos de disco, mientras que en otros puede seguir copiando bloques, pero haciéndolo a través de una ruta optimizada. En la actualidad, se admite en Linux y FreeBSD.

--no-statistics

No restaura las estadísticas del antiguo clúster en el nuevo clúster.

--set-char-signedness=option

Establece manualmente el signo predeterminado de los caracteres (char signedness) de los nuevos clústeres. Los valores posibles son signed y unsigned.

En el lenguaje C, el signo predeterminado del tipo char (cuando no se especifica explícitamente) varía según la plataforma. Por ejemplo, char es por defecto signed char en CPU x86 pero es unsigned char en CPU ARM.

A partir de PostgreSQL 18, los clústeres de bases de datos mantienen su propia configuración de signo de caracteres predeterminado, la cual se puede utilizar para garantizar un comportamiento consistente en plataformas con diferentes valores predeterminados. Por defecto, pg_upgrade preserva esta configuración al actualizar desde un clúster existente. Sin embargo, al actualizar desde PostgreSQL 17 o anterior, pg_upgrade adopta el signo de caracteres de la plataforma en la que fue compilado.

Esta opción te permite establecer explícitamente el signo predeterminado de los caracteres para el nuevo clúster, anulando cualquier valor heredado. Hay dos escenarios específicos donde esta opción es relevante:

Si estás planeando migrar a una plataforma diferente después de la actualización, no deberías usar esta opción. El comportamiento predeterminado es el correcto en este caso. En su lugar, realiza la actualización en la plataforma original sin este flag, y luego migra el clúster. Este es el enfoque recomendado y más seguro.
Si ya has migrado el clúster a una plataforma con un signo de caracteres diferente (por ejemplo, de un sistema basado en x86 a un sistema basado en ARM), deberías usar esta opción para especificar el signo que coincida con el signo predeterminado de los caracteres de la plataforma original. Adicionalmente, es esencial no modificar ningún archivo de datos entre la migración de los archivos de datos y la ejecución de pg_upgrade. pg_upgrade debe ser la primera operación que inicie el clúster en la nueva plataforma.

--swap

Mueve los directorios de datos del clúster antiguo al clúster nuevo. Luego, reemplaza los archivos del catálogo por aquellos generados para el nuevo clúster. Este modo puede superar el rendimiento de --link, --clone, --copy y --copy-file-range, especialmente en clústeres con muchas relaciones.

Sin embargo, este modo crea muchos archivos basura en el clúster antiguo, lo que puede prolongar el paso de sincronización de archivos si se utiliza --sync-method=syncfs. Por lo tanto, se recomienda utilizar --sync-method=fsync con --swap.

Adicionalmente, una vez que comienza el paso de transferencia de archivos, el clúster antiguo se modificará de manera destructiva y, por lo tanto, ya no será seguro de iniciar. Consulta Step 17 para más detalles.

--sync-method=method

Cuando se establece en fsync, que es el valor predeterminado, pg_upgrade abrirá y sincronizará recursivamente todos los archivos en el directorio de datos del clúster actualizado. La búsqueda de archivos seguirá los enlaces simbólicos para el directorio WAL y cada tablespace configurado.

En Linux, se puede usar en su lugar syncfs para pedir al sistema operativo que sincronice la totalidad de los sistemas de archivos que contienen el directorio de datos del clúster actualizado, sus archivos WAL y cada tablespace. Consulta recovery_init_sync_method para obtener información sobre las advertencias que debes tener en cuenta al usar syncfs.

Esta opción no tiene efecto cuando se utiliza --no-sync.

-? --help

muestra la ayuda y termina

Uso

Estos son los pasos para realizar una actualización con pg_upgrade:

Note

Los pasos para actualizar clústeres de replicación lógica no se cubren aquí; consulta Section 29.13 para más detalles.

Mover opcionalmente el clúster antiguo
Si estás utilizando un directorio de instalación específico de la versión, por ejemplo, /opt/PostgreSQL/18, no necesitas mover el clúster antiguo. Los instaladores gráficos utilizan todos directorios de instalación específicos de la versión.
Si tu directorio de instalación no es específico de la versión, por ejemplo, /usr/local/pgsql, es necesario mover el directorio de instalación actual de PostgreSQL para que no interfiera con la nueva instalación de PostgreSQL. Una vez que el servidor PostgreSQL actual esté apagado, es seguro renombrar el directorio de instalación de PostgreSQL; asumiendo que el directorio antiguo es /usr/local/pgsql, puedes ejecutar:
```
mv /usr/local/pgsql /usr/local/pgsql.old
```
para renombrar el directorio.
Para instalaciones desde código fuente, compilar la nueva versión
Compila el nuevo código fuente de PostgreSQL con las opciones de configure que sean compatibles con el clúster antiguo. pg_upgrade comprobará pg_controldata para asegurarse de que todas las configuraciones sean compatibles antes de iniciar la actualización.
Instalar los nuevos binarios de PostgreSQL
Instala los binarios del nuevo servidor y los archivos de soporte. pg_upgrade se incluye en una instalación predeterminada.
Para instalaciones desde el código fuente, si deseas instalar el nuevo servidor en una ubicación personalizada, utiliza la variable prefix:
```
make prefix=/usr/local/pgsql.new install
```
Inicializar el nuevo clúster de PostgreSQL
Inicializa el nuevo clúster usando initdb. De nuevo, utiliza opciones compatibles de initdb que coincidan con el clúster antiguo. Muchos instaladores preempaquetados realizan este paso automáticamente. No hay necesidad de iniciar el nuevo clúster.
Instalar los archivos de objetos compartidos de extensiones
Muchas extensiones y módulos personalizados, ya sea de contrib o de otra fuente, utilizan archivos de objetos compartidos (o DLLs), por ejemplo, pgcrypto.so. Si el clúster antiguo los utilizaba, se deben instalar archivos de objetos compartidos que coincidan con el binario del nuevo servidor en el nuevo clúster, generalmente mediante comandos del sistema operativo. No cargues las definiciones de esquema, por ejemplo, CREATE EXTENSION pgcrypto, porque estas se duplicarán del clúster antiguo. Si hay actualizaciones de extensiones disponibles, pg_upgrade lo informará y creará un script que se podrá ejecutar más tarde para actualizarlas.
Copiar archivos personalizados de búsqueda de texto completo
Copia cualquier archivo personalizado de búsqueda de texto completo (diccionario, sinónimos, tesauro, palabras vacías o stop words) del clúster antiguo al nuevo.
Ajustar la autenticación
pg_upgrade se conectará a los servidores antiguo y nuevo varias veces, por lo que es posible que desees establecer la autenticación en peer en pg_hba.conf o utilizar un archivo ~/.pgpass (consulta Section 32.16).
Detener ambos servidores
Asegúrate de que ambos servidores de bases de datos estén detenidos utilizando, en Unix, por ejemplo:
```
pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/18 stop
```
o en Windows, utilizando los nombres de servicio adecuados:
```
NET STOP postgresql-12
NET STOP postgresql-18
```
Los servidores en espera de replicación en flujo (streaming replication) y envío de registros (log-shipping) deben estar funcionando durante este apagado para que reciban todos los cambios.
Prepararse para las actualizaciones de servidores en espera (standby)
Si estás actualizando servidores en espera utilizando los métodos descritos en la sección Step 11, verifica que los servidores en espera antiguos estén al día ejecutando pg_controldata contra los clústeres primario y en espera antiguos. Verifica que los valores de “Latest checkpoint location” coincidan en todos los clústeres. Además, asegúrate de que wal_level no esté establecido en minimal en el archivo postgresql.conf del nuevo clúster primario.
Ejecutar pg_upgrade
Ejecuta siempre el binario pg_upgrade del nuevo servidor, no el del antiguo. pg_upgrade requiere la especificación de los directorios de datos y ejecutables (bin) de los clústeres antiguo y nuevo. También puedes especificar valores de usuario y puerto, y si deseas que los archivos de datos se enlacen, clonen o intercambien en lugar del comportamiento predeterminado de copia.
Si utilizas el modo de enlace (link), la actualización será mucho más rápida (sin copia de archivos) y utilizará menos espacio en disco, pero no podrás acceder a tu clúster antiguo una vez que inicies el nuevo clúster después de la actualización. El modo de enlace también requiere que los directorios de datos de los clústeres antiguo y nuevo estén en el mismo sistema de archivos. (Los tablespaces y pg_wal pueden estar en diferentes sistemas de archivos). El modo de clonación (clone) proporciona las mismas ventajas de velocidad y espacio en disco pero no hace que el clúster antiguo quede inutilizable una vez que se inicia el nuevo clúster. El modo de clonación también requiere que los directorios de datos antiguo y nuevo estén en el mismo sistema de archivos. Este modo solo está disponible en ciertos sistemas operativos y sistemas de archivos. El modo de intercambio (swap) puede ser el más rápido si hay muchas relaciones, pero no podrás acceder a tu clúster antiguo una vez que comience el paso de transferencia de archivos. El modo de intercambio también requiere que los directorios de datos de los clústeres antiguo y nuevo estén en el mismo sistema de archivos.
Establecer --jobs en 2 o más permite a pg_upgrade procesar múltiples bases de datos y tablespaces en paralelo. Un buen punto de partida es el número de núcleos de CPU en la máquina. Esta opción puede reducir sustancialmente el tiempo de actualización para servidores con múltiples bases de datos y tablespaces.
Para los usuarios de Windows, deben iniciar sesión en una cuenta administrativa y luego ejecutar pg_upgrade con los directorios entre comillas, por ejemplo:
```
pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/12/data"
        --new-datadir "C:/Program Files/PostgreSQL/18/data"
        --old-bindir "C:/Program Files/PostgreSQL/12/bin"
        --new-bindir "C:/Program Files/PostgreSQL/18/bin"
```
Una vez iniciado, pg_upgrade verifará que los dos clústeres sean compatibles y luego realizará la actualización. Puedes utilizar pg_upgrade --check para realizar únicamente las comprobaciones, incluso si el servidor antiguo sigue en ejecución. pg_upgrade --check también detallará cualquier ajuste manual que debas realizar después de la actualización. Si vas a utilizar el modo link, clone, copy-file-range o swap, deberías usar la opción --link, --clone, --copy-file-range o --swap con --check para habilitar las comprobaciones específicas del modo. pg_upgrade requiere permisos de escritura en el directorio actual.
Obviamente, nadie debería acceder a los clústeres durante la actualización. pg_upgrade ejecuta por defecto los servidores en el puerto 50432 para evitar conexiones de clientes no deseadas. Puedes utilizar el mismo número de puerto para ambos clústeres al realizar una actualización porque los clústeres antiguo y nuevo no se ejecutarán al mismo tiempo. Sin embargo, al comprobar un servidor antiguo en ejecución, los números de puerto antiguo y nuevo deben ser diferentes.
Si ocurre un error al restaurar el esquema de la base de datos, pg_upgrade terminará y tendrás que revertir al clúster antiguo como se describe en Step 17 más adelante. Para intentar pg_upgrade de nuevo, deberás modificar el clúster antiguo para que la restauración del esquema de pg_upgrade tenga éxito. Si el problema es un módulo de contrib, es posible que debas desinstalar el módulo de contrib del clúster antiguo e instalarlo en el nuevo clúster después de la actualización, asumiendo que el módulo no se está utilizando para almacenar datos de usuario.
Actualizar servidores en espera de replicación en flujo y envío de registros
Si utilizaste el modo de enlace y tienes servidores en espera de replicación en flujo (consulta Section 26.2.5) o de envío de registros (consulta Section 26.2), puedes seguir estos pasos para actualizarlos rápidamente. No ejecutarás pg_upgrade en los servidores en espera, sino rsync en el primario. No inicies ningún servidor todavía.
Si no utilizaste el modo de enlace, no tienes o no deseas utilizar rsync, o deseas una solución más sencilla, omite las instrucciones de esta sección y simplemente recrea los servidores en espera una vez que se complete pg_upgrade y el nuevo primario esté en ejecución.
1. Instalar los nuevos binarios de PostgreSQL en los servidores en espera
  Asegúrate de que los nuevos binarios y archivos de soporte estén instalados en todos los servidores en espera.
2. Asegurarse de que los nuevos directorios de datos de los servidores en espera no existan
  Asegúrate de que los nuevos directorios de datos de los servidores en espera no existan o estén vacíos. Si se ejecutó initdb, elimina los nuevos directorios de datos de los servidores en espera.
3. Instalar los archivos de objetos compartidos de extensiones
  Instala los mismos archivos de objetos compartidos de extensiones en los nuevos servidores en espera que instalaste en el nuevo clúster primario.
4. Detener los servidores en espera
  Si los servidores en espera siguen en ejecución, deténlos ahora utilizando las instrucciones anteriores.
5. Guardar los archivos de configuración
  Guarda cualquier archivo de configuración de los directorios de configuración de los antiguos servidores en espera que necesites conservar, por ejemplo, postgresql.conf (y cualquier archivo incluido por este), postgresql.auto.conf, pg_hba.conf, porque estos se sobrescribirán o eliminarán en el siguiente paso.
6. Ejecutar rsync
  Al utilizar el modo de enlace, los servidores en espera se pueden actualizar rápidamente utilizando rsync. Para lograr esto, desde un directorio en el servidor primario que esté por encima de los directorios de los clústeres de bases de datos antiguo y nuevo, ejecuta esto en el primario para cada servidor en espera:
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
```
  donde old_cluster and new_cluster son relativos al directorio actual en el primario, y remote_dir está por encima de los directorios de los clústeres antiguo y nuevo en el servidor en espera. La estructura de directorios bajo los directorios especificados en el primario y en los servidores en espera debe coincidir. Consulta la página del manual de rsync para obtener detalles sobre cómo especificar el directorio remoto, por ejemplo:
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/12 \
      /opt/PostgreSQL/18 standby.example.com:/opt/PostgreSQL
```
  Puedes verificar qué hará el comando utilizando la opción --dry-run de rsync. Aunque rsync debe ejecutarse en el primario para al menos un servidor en espera, es posible ejecutar rsync en un servidor en espera actualizado para actualizar otros servidores en espera, siempre y cuando el servidor en espera actualizado no se haya iniciado.
  Lo que esto hace es registrar los enlaces creados por el modo de enlace de pg_upgrade que conectan archivos en los clústeres antiguo y nuevo en el servidor primario. Luego busca archivos coincidentes en el clúster antiguo del servidor en espera y crea enlaces para ellos en el nuevo clúster del servidor en espera. Los archivos que no se enlazaron en el primario se copian desde el primario al servidor en espera. (Suelen ser pequeños). Esto proporciona actualizaciones rápidas de los servidores en espera. Desafortunadamente, rsync copia innecesariamente archivos asociados con tablas temporales y unlogged porque estos archivos normalmente no existen en los servidores en espera.
  Si tienes tablespaces, deberás ejecutar un comando de rsync similar para cada directorio de tablespace, por ejemplo:
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
      /vol1/pg_tblsp/PG_18_202307071 standby.example.com:/vol1/pg_tblsp
```
  Si has reubicado pg_wal fuera de los directorios de datos, también se debe ejecutar rsync en esos directorios.
7. Configurar los servidores en espera de replicación en flujo y envío de registros
  Configura los servidores para el envío de registros. (No es necesario ejecutar pg_backup_start() y pg_backup_stop() ni realizar una copia de seguridad del sistema de archivos, ya que los servidores en espera siguen sincronizados con el primario). Si el antiguo primario es anterior a la versión 17.0, no se copian slots del primario al nuevo servidor en espera, por lo que todos los slots en el antiguo servidor en espera deben recrearse manualmente. Si el antiguo primario es la versión 17.0 o posterior, únicamente se copian los slots lógicos del primario al nuevo servidor en espera, pero los demás slots del antiguo servidor en espera no se copian, por lo que deben recrearse manualmente.
Restaurar pg_hba.conf
Si modificaste pg_hba.conf, restaura su configuración original. También podría ser necesario ajustar otros archivos de configuración en el nuevo clúster para que coincidan con el clúster antiguo, por ejemplo, postgresql.conf (y cualquier archivo incluido por este), postgresql.auto.conf.
Iniciar el nuevo servidor
Ahora se puede iniciar de forma segura el nuevo servidor, y luego cualquier servidor en espera sincronizado mediante rsync.
Procesamiento posterior a la actualización
Si se requiere algún procesamiento posterior a la actualización, pg_upgrade emitirá advertencias al finalizar. También generará archivos de script que deben ser ejecutados por el administrador. Los archivos de script se conectarán a cada base de datos que necesite procesamiento posterior a la actualización. Cada script debe ejecutarse utilizando:
```
psql --username=postgres --file=script.sql postgres
```
Los scripts se pueden ejecutar en cualquier orden y se pueden eliminar una vez que se hayan ejecutado.
Caution
En general, no es seguro acceder a las tablas a las que se hace referencia en los scripts de reconstrucción hasta que estos hayan terminado de ejecutarse por completo; hacerlo podría producir resultados incorrectos o un rendimiento deficiente. Las tablas a las que no se hace referencia en los scripts de reconstrucción se pueden acceder de inmediato.
Estadísticas
A menos que se especifique la opción --no-statistics, pg_upgrade transferirá la mayoría de las estadísticas del optimizador del clúster antiguo al nuevo clúster. Esto no transfiere todas las estadísticas, como aquellas creadas explícitamente con CREATE STATISTICS, las estadísticas personalizadas agregadas por una extensión o las estadísticas recopiladas por el sistema de estadísticas acumulativas.
Debido a que no todas las estadísticas son transferidas por pg_upgrade, se te indicará que ejecutes comandos para regenerar esa información al final de la actualización. Es posible que debas configurar parámetros de conexión para que coincidan con tu nuevo clúster.
Primero, utiliza vacuumdb --all --analyze-in-stages --missing-stats-only para generar rápidamente estadísticas mínimas del optimizador para las relaciones que no tengan ninguna. Luego, utiliza vacuumdb --all --analyze-only para asegurarte de que todas las relaciones tengan estadísticas acumulativas actualizadas para activar vacuum y analyze. Para ambos comandos, el uso de --jobs puede acelerar el proceso. Si vacuum_cost_delay está configurado con un valor distinto de cero, esto se puede anular para acelerar la generación de estadísticas utilizando PGOPTIONS, por ejemplo, PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ....
Eliminar el clúster antiguo
Una vez que estés satisfecho con la actualización, puedes eliminar los directorios de datos del clúster antiguo ejecutando el script mencionado cuando pg_upgrade finalice. (La eliminación automática no es posible si tienes tablespaces definidos por el usuario dentro del antiguo directorio de datos). También puedes eliminar los antiguos directorios de instalación (por ejemplo, bin, share).
Revertir al clúster antiguo
Si, después de ejecutar pg_upgrade, deseas revertir al clúster antiguo, existen varias opciones:
- Si se utilizó la opción --check, el clúster antiguo no fue modificado; se puede reiniciar.
- Si no se utilizó ni --link ni --swap, el clúster antiguo no fue modificado; se puede reiniciar.
- Si se utilizó la opción --link, los archivos de datos podrían estar compartidos entre el clúster antiguo y el nuevo:
  - Si pg_upgrade abortó antes de que comenzara el enlace, el clúster antiguo no fue modificado; se puede reiniciar.
  - Si no iniciaste el nuevo clúster, el clúster antiguo no fue modificado excepto que, cuando comenzó el enlace, se añadió un sufijo .old a $PGDATA/global/pg_control. Para reutilizar el clúster antiguo, elimina el sufijo .old de $PGDATA/global/pg_control; luego podrás reiniciar el clúster antiguo.
  - Si iniciaste el nuevo clúster, este ha escrito en archivos compartidos y ya no es seguro utilizar el clúster antiguo. En este caso, el clúster antiguo deberá restaurarse desde una copia de seguridad.
- Si se utilizó la opción --swap, el clúster antiguo podría haber sido modificado destructivamente:
  - Si pg_upgrade aborta antes de informar que el clúster antiguo ya no es seguro de iniciar, el clúster antiguo no fue modificado; se puede reiniciar.
  - Si pg_upgrade ha informado que el clúster antiguo ya no es seguro de iniciar, el clúster antiguo fue modificado destructivamente. En este caso, el clúster antiguo deberá ser restaurado desde una copia de seguridad.

Entorno

Se pueden utilizar algunas variables de entorno para proporcionar valores predeterminados para las opciones de línea de comandos:

PGBINOLD: El directorio de ejecutables antiguo de PostgreSQL; opción -b/--old-bindir.
PGBINNEW: El directorio de ejecutables nuevo de PostgreSQL; opción -B/--new-bindir.
PGDATAOLD: El directorio de configuración del antiguo clúster de base de datos; opción -d/--old-datadir.
PGDATANEW: El directorio de configuración del nuevo clúster de base de datos; opción -D/--new-datadir.
PGPORTOLD: El número de puerto del antiguo clúster; opción -p/--old-port.
PGPORTNEW: El número de puerto del nuevo clúster; opción -P/--new-port.
PGSOCKETDIR: Directorio a utilizar para los sockets del postmaster durante la actualización; opción -s/--socketdir.
PGUSER: Nombre de usuario de instalación del clúster; opción -U/--username.

Notas

pg_upgrade crea varios archivos de trabajo, como volcados de esquemas (schema dumps), almacenados dentro de pg_upgrade_output.d en el directorio del nuevo clúster. Cada ejecución crea un nuevo subdirectorio nombrado con una marca de tiempo formateada según la norma ISO 8601 (%Y%m%dT%H%M%S), donde se almacenan todos los archivos generados. pg_upgrade_output.d y sus archivos contenidos se eliminarán automáticamente si pg_upgrade finaliza con éxito; pero en caso de problemas, los archivos allí pueden proporcionar información útil para la depuración.

pg_upgrade inicia postmasters de corta duración en los directorios de datos antiguo y nuevo. Los archivos de socket Unix temporales para la comunicación con estos postmasters se crean, por defecto, en el directorio de trabajo actual. En algunas situaciones, la ruta del directorio actual puede ser demasiado larga para ser un nombre de socket válido. En ese caso, puedes utilizar la opción -s para colocar los archivos de socket en algún directorio con una ruta más corta. Por seguridad, asegúrate de que ese directorio no sea legible ni escribible por ningún otro usuario. (Esto no se admite en Windows).

Todos los casos de falla, reconstrucción y reindexación serán reportados por pg_upgrade si afectan a tu instalación; los scripts posteriores a la actualización para reconstruir tablas e índices se generarán automáticamente. Si estás intentando automatizar la actualización de muchos clústeres, deberías notar que los clústeres con esquemas de base de datos idénticos requieren los mismos pasos posteriores a la actualización; esto se debe a que los pasos posteriores a la actualización se basan en los esquemas de base de datos y no en los datos del usuario.

Para pruebas de despliegue, crea una copia únicamente del esquema del clúster antiguo, inserta datos de prueba y actualiza eso.

pg_upgrade no admite la actualización de bases de datos que contengan columnas de tablas que utilicen estos tipos de datos del sistema que hacen referencia a OID reg*:

regcollation

regconfig

regdictionary

regnamespace

regoper

regoperator

regproc

regprocedure

(Se pueden actualizar regclass, regrole y regtype).

Si deseas utilizar el modo de enlace y no quieres que tu clúster antiguo se modifique cuando se inicie el nuevo clúster, considera utilizar el modo clone. Si este no está disponible, realiza una copia del clúster antiguo y actualiza esa copia en modo de enlace. Para hacer una copia válida del clúster antiguo, utiliza rsync para crear una copia sucia del clúster antiguo mientras el servidor está en ejecución, luego apaga el servidor antiguo y ejecuta rsync --checksum de nuevo para actualizar la copia con cualquier cambio y hacerla consistente. (--checksum es necesario porque rsync solo tiene una granularidad de tiempo de modificación de un segundo). Es posible que desees excluir algunos archivos, por ejemplo, postmaster.pid, como se documenta en Section 25.3.4. Si tu sistema de archivos admite instantáneas de sistema de archivos o copias de archivos copy-on-write, puedes utilizar eso para hacer una copia de seguridad del clúster antiguo y de los tablespaces, aunque la instantánea y las copias deben crearse simultáneamente o mientras el servidor de base de datos esté apagado.

Véase también

initdb, pg_ctl, pg_dump, postgres