Postgresql pg_upgrade

pg_upgrade: actualiza una instancia de servidor PostgreSQL

Sinopsis

pg_upgrade-boldbindir-Bnewbindir-doldconfigdir-Dnewconfigdir [option…]

Descripción

pg_upgrade (anteriormente llamado pg_migrator) permite que los datos almacenados en archivos de datos de PostgreSQL se actualicen a una versión principal de PostgreSQL posterior sin el volcado / recarga de datos que normalmente se requiere para las actualizaciones de versiones principales, por ejemplo, de 9.5.8 a 9.6.4 o de 10.7 a 11.2 . No es necesario para actualizaciones de versiones menores, por ejemplo, de 9.6.2 a 9.6.3 o de 10.1 a 10.2.

Las principales versiones de PostgreSQL agregan regularmente nuevas características que a menudo cambian el diseño de las tablas del sistema, pero el formato de almacenamiento de datos interno rara vez cambia. pg_upgrade usa 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 importante futura cambia el formato de almacenamiento de datos de una manera que hace que el formato de datos antiguo sea ilegible, pg_upgrade no se podrá utilizar para tales actualizaciones. (La comunidad intentará evitar tales situaciones).

pg_upgrade hace todo lo posible para asegurarse de que los clústeres nuevos y antiguos sean compatibles con los binarios, por ejemplo, comprobando la configuración de tiempo de compilación compatible, incluidos los binarios de 32/64 bits. Es importante que todos los módulos externos también sean compatibles con binarios, aunque pg_upgrade no puede comprobarlo.

pg_upgrade admite actualizaciones desde 8.4.X y posteriores a la versión principal actual de PostgreSQL, incluidas las versiones instantáneas y beta.

Opciones

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

-bbindir--old-bindir=bindir

el antiguo directorio ejecutable de PostgreSQL; Variable ambiental PGBINOLD

-Bbindir--new-bindir=bindir

el nuevo directorio ejecutable de PostgreSQL; por defecto es el directorio donde reside pg_upgrade; Variable ambiental PGBINNEW

-c--check

verifique solo los clústeres, no cambie ningún dato

-dconfigdir--old-datadir=configdir

el directorio de configuración del clúster de base de datos antiguo; Variable ambiental PGDATAOLD

-Dconfigdir--new-datadir=configdir

el nuevo directorio de configuración del clúster de base de datos; Variable ambiental PGDATANEW

-j njobs--jobs=njobs

número de procesos o subprocesos simultáneos a utilizar

-k--link

utilizar enlaces físicos en lugar de copiar archivos al nuevo clúster

-ooptions--old-optionsoptions

opciones que se pasarán directamente al antiguo postgres mando; se añaden múltiples invocaciones de opciones

-Ooptions--new-optionsoptions

opciones que se pasarán directamente al nuevo postgres mando; se añaden múltiples invocaciones de opciones

-pport--old-port=port

el antiguo número de puerto del clúster; Variable ambiental PGPORTOLD

-Pport--new-port=port

el nuevo número de puerto del clúster; Variable ambiental PGPORTNEW

-r--retain

conservar los archivos de registro y SQL incluso después de completarlos correctamente

-sdir--socketdir=dir

directorio que se utilizará para los sockets de postmaster durante la actualización; el predeterminado es el directorio de trabajo actual; Variable ambiental PGSOCKETDIR

-Uusername--username=username

nombre de usuario de instalación del clúster; Variable ambiental PGUSER

-v--verbose

habilitar el registro interno detallado

-V--version

mostrar la información de la versión, luego salir

--clone

Utilice la clonación de archivos eficiente (también conocida como “enlaces de retorno“ 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, lo que brinda las ventajas de velocidad de -k/--link dejando intacto el antiguo cúmulo.

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

-?--help

mostrar ayuda, luego salir

Uso

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

1. Opcionalmente, mueva el clúster antiguo

   Si está utilizando un directorio de instalación específico de la versión, por ejemplo, /opt/PostgreSQL/13, no es necesario mover el clúster anterior. Todos los instaladores gráficos utilizan directorios de instalación específicos de la versión.

   Si su 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 se apaga el servidor PostgreSQL actual, es seguro cambiar el nombre del directorio de instalación de PostgreSQL; asumiendo que el directorio antiguo es /usr/local/pgsql, tu puedes hacer:

   mv /usr/local/pgsql /usr/local/pgsql.old
   

   para cambiar el nombre del directorio.

2. Para instalaciones de código fuente, compile la nueva versión

   Cree la nueva fuente de PostgreSQL con configure banderas que son 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.

3. Instale los nuevos binarios de PostgreSQL

   Instale los archivos binarios y de soporte del nuevo servidor. pg_upgrade se incluye en una instalación predeterminada.

   Para instalaciones de origen, si desea instalar el nuevo servidor en una ubicación personalizada, utilice el prefix variable:

   make prefix=/usr/local/pgsql.new install
   

4. Inicializar el nuevo clúster de PostgreSQL

   Inicialice el nuevo clúster usando initdb. Nuevamente, use compatible initdb banderas que coinciden con el clúster antiguo. Muchos instaladores prediseñados realizan este paso automáticamente. No es necesario iniciar el nuevo clúster.

5. Instalar archivos de objetos compartidos personalizados

   Instale cualquier archivo de objeto compartido personalizado (o DLL) utilizado por el clúster antiguo en el nuevo clúster, por ejemplo, pgcrypto.so, ya sean de contrib o alguna otra fuente. No instale las definiciones de esquema, por ejemplo, CREATE EXTENSION pgcrypto, porque se actualizarán desde el clúster anterior. Además, cualquier archivo de búsqueda de texto completo personalizado (diccionario, sinónimo, diccionario de sinónimos, palabras vacías) también debe copiarse en el nuevo clúster.

6. Ajustar la autenticación

   pg_upgrade se conectará a los servidores nuevos y antiguos varias veces, por lo que es posible que desee configurar la autenticación para peer en pg_hba.conf o usa un ~/.pgpass archivo (ver Sección 33.15).

7. Detenga ambos servidores

   Asegúrese de que ambos servidores de bases de datos se dejen de usar, en Unix, por ejemplo:

   pg_ctl -D /opt/PostgreSQL/9.6 stop
   pg_ctl -D /opt/PostgreSQL/13 stop
   

   o en Windows, utilizando los nombres de servicio adecuados:

   NET STOP postgresql-9.6
   NET STOP postgresql-13

   Los servidores en espera de transmisión de replicación y envío de registros pueden seguir funcionando hasta un paso posterior.

8. Prepárese para las actualizaciones del servidor en espera

   Si está actualizando servidores en espera mediante los métodos descritos en la sección Paso 10, verifique que los servidores en espera antiguos estén actualizados ejecutando pg_controldata en los clústeres primarios y en espera antiguos. Verifique que el “Última ubicación del punto de control“ los valores coinciden en todos los grupos. (Habrá una discrepancia si los servidores en espera antiguos se apagan antes que el primario antiguo o si los servidores en espera antiguos aún están en ejecución). wal_level no está configurado para minimal en el postgresql.conf archivo en el nuevo clúster principal.

9. Ejecute pg_upgrade

   Ejecute siempre el binario pg_upgrade del nuevo servidor, no el antiguo. pg_upgrade requiere la especificación de los datos y ejecutables del clúster antiguo y nuevo (bin) directorios. También puede especificar valores de usuario y puerto, y si desea que los archivos de datos se vinculen o clonen en lugar del comportamiento de copia predeterminado.

   Si usa el modo de enlace, la actualización será mucho más rápida (sin copiar archivos) y usará menos espacio en disco, pero no podrá acceder a su clúster anterior una vez que inicie el nuevo clúster después de la actualización. El modo de enlace también requiere que los directorios de datos del clúster nuevos y antiguos estén en el mismo sistema de archivos. (Espacios de tabla y pg_wal puede estar en diferentes sistemas de archivos). El modo de clonación 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. El modo de clonación también requiere que los directorios de datos nuevos y antiguos estén en el mismo sistema de archivos. Este modo solo está disponible en ciertos sistemas operativos y sistemas de archivos.

   los --jobs la opción permite usar múltiples núcleos de CPU para copiar / vincular archivos y para volcar y recargar esquemas de base de datos en paralelo; un buen lugar para comenzar es el número máximo de núcleos de CPU y espacios de tabla. Esta opción puede reducir drásticamente el tiempo necesario para actualizar un servidor de bases de datos múltiples que se ejecuta en una máquina con varios procesadores.

   Para los usuarios de Windows, debe iniciar sesión en una cuenta administrativa y luego iniciar un shell como el postgres usuario y establezca la ruta adecuada:

   RUNAS /USER:postgres "CMD.EXE"SET PATH=%PATH%;C:Program FilesPostgreSQL13bin;

   y luego ejecute pg_upgrade con directorios citados, por ejemplo:

   pg_upgrade.exe
           --old-datadir "C:/Program Files/PostgreSQL/9.6/data"--new-datadir "C:/Program Files/PostgreSQL/13/data"--old-bindir "C:/Program Files/PostgreSQL/9.6/bin"--new-bindir "C:/Program Files/PostgreSQL/13/bin"

   Una vez iniciado, pg_upgrade Verificará que los dos clústeres sean compatibles y luego realizará la actualización. Puedes usar pg_upgrade --check para realizar solo las comprobaciones, incluso si el servidor antiguo todavía se está ejecutando. pg_upgrade --check también describirá los ajustes manuales que deberá realizar después de la actualización. Si va a usar el modo de enlace o clonación, debe usar la opción --link o --clone con --check para habilitar comprobaciones específicas del modo. pg_upgrade requiere permiso de escritura en el directorio actual.

   Obviamente, nadie debería acceder a los clústeres durante la actualización. pg_upgrade toma de forma predeterminada los servidores en ejecución en el puerto 50432 para evitar conexiones de cliente no deseadas. Puede 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 saldrá y tendrá que volver al clúster anterior como se describe en el Paso 16 a continuación. Intentar pg_upgrade nuevamente, deberá modificar el clúster anterior para que la restauración del esquema pg_upgrade sea exitosa. Si el problema es un contrib módulo, es posible que deba desinstalar el contrib módulo del clúster anterior e instálelo 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.

10. Actualizar los servidores en espera de replicación de transmisión y envío de registros

    Si usó el modo de enlace y tiene servidores en espera de Streaming Replication (consulte la Sección 26.2.5) o Log-Shipping (consulte la Sección 26.2), puede seguir estos pasos para actualizarlos rápidamente. No ejecutará pg_upgrade en los servidores en espera, sino rsync en el principal. No inicie ningún servidor todavía.

    Si lo hiciste no use el modo de enlace, no tenga o no quiera usar rsync, o quiera una solución más fácil, omita las instrucciones en esta sección y simplemente vuelva a crear los servidores en espera una vez que pg_upgrade se complete y el nuevo primario se esté ejecutando.

    1. Instale los nuevos binarios de PostgreSQL en servidores en espera

       Asegúrese de que los nuevos archivos binarios y de soporte estén instalados en todos los servidores en espera.

    2. Asegúrese de que los nuevos directorios de datos en espera no existe

       Asegúrese de que los nuevos directorios de datos en espera no existen o están vacíos. Si se ejecutó initdb, elimine el modo de espera los nuevos directorios de datos de los servidores.

    3. Instalar archivos de objetos compartidos personalizados

       Instale los mismos archivos de objetos compartidos personalizados en los nuevos recursos en espera que instaló en el nuevo clúster principal.

    4. Detener servidores en espera

       Si los servidores en espera aún se están ejecutando, deténgalos ahora siguiendo las instrucciones anteriores.

    5. Guardar archivos de configuración

       Guarde los archivos de configuración de los directorios de configuración antiguos que necesita conservar, por ejemplo, postgresql.conf (y cualquier archivo incluido por él), postgresql.auto.conf, pg_hba.conf, porque estos se sobrescribirán o eliminarán en el siguiente paso.

    6. Ejecute rsync

       Cuando se usa el modo de enlace, los servidores en espera se pueden actualizar rápidamente usando rsync. Para lograr esto, desde un directorio en el servidor primario que está por encima de los directorios del clúster de base de datos nuevo y antiguo, ejecute 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

       dónde old_cluster y new_cluster son relativas al directorio actual en el primario, y remote_dir es encima los directorios del clúster antiguo y nuevo en el modo de espera. La estructura del directorio en los directorios especificados en el primario y en espera debe coincidir. Consulte 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/9.5 /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL
       

       Puede verificar lo que hará el comando usando rsync’s --dry-run opción. Si bien rsync debe ejecutarse en el primario durante al menos un modo de espera, es posible ejecutar rsync en un modo de espera actualizado para actualizar otros en espera, siempre que no se haya iniciado el modo de espera actualizado.

       Lo que hace esto es registrar los enlaces creados por el modo de enlace de pg_upgrade que conectan archivos en los clústeres nuevos y antiguos en el servidor principal. Luego, encuentra los archivos coincidentes en el clúster antiguo del modo de espera y crea enlaces para ellos en el nuevo clúster del modo de espera. Los archivos que no estaban vinculados en el primario se copian del primario al modo de espera. (Suelen ser pequeños). Esto proporciona actualizaciones rápidas en espera. Desafortunadamente, rsync copia innecesariamente archivos asociados con tablas temporales y no registradas porque estos archivos normalmente no existen en servidores en espera.

       Si tiene espacios de tabla, deberá ejecutar un comando rsync similar para cada directorio de espacio de tabla, por ejemplo:

       rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
       

       Si te has mudado pg_wal fuera de los directorios de datos, rsync también debe ejecutarse en esos directorios.

    7. Configurar servidores en espera de replicación de transmisión y envío de registros

       Configure los servidores para el trasvase de registros. (No necesitas correr pg_start_backup() y pg_stop_backup() o realizar una copia de seguridad del sistema de archivos, ya que los recursos en espera aún están sincronizados con el primario).

11. Restaurar pg_hba.conf

    Si modificó pg_hba.conf, restaure su configuración original. También puede ser necesario ajustar otros archivos de configuración en el nuevo clúster para que coincidan con el antiguo, por ejemplo, postgresql.conf (y cualquier archivo incluido por él), postgresql.auto.conf.

12. Inicie el nuevo servidor

    El nuevo servidor ahora se puede iniciar de forma segura, y luego cualquier servidor en espera rsync’ed.

13. Procesamiento posterior a la actualización

    Si se requiere algún procesamiento posterior a la actualización, pg_upgrade emitirá advertencias a medida que se complete. También generará archivos de secuencia de comandos que debe ejecutar el administrador. Los archivos de secuencia de comandos se conectarán a cada base de datos que necesite procesamiento posterior a la actualización. Cada script debe ejecutarse usando:

    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.

    Precaución

    En general, no es seguro acceder a las tablas a las que se hace referencia en los scripts de reconstrucción hasta que los scripts de reconstrucción se hayan completado; hacerlo podría producir resultados incorrectos o un rendimiento deficiente. Se puede acceder de inmediato a las tablas a las que no se hace referencia en los scripts de reconstrucción.

14. Estadísticas

    Dado que las estadísticas del optimizador no se transfieren pg_upgrade, se le indicará que ejecute un comando para volver a generar esa información al final de la actualización. Es posible que deba establecer parámetros de conexión para que coincidan con su nuevo clúster.

15. Eliminar clúster antiguo

    Una vez que esté satisfecho con la actualización, puede eliminar los directorios de datos del clúster antiguo ejecutando el script mencionado cuando pg_upgrade completa. (La eliminación automática no es posible si tiene espacios de tabla definidos por el usuario dentro del directorio de datos antiguo). También puede eliminar los directorios de instalación antiguos (por ejemplo, bin, share).

16. Volviendo al clúster antiguo

    Si, despues de correr pg_upgrade, desea volver al clúster anterior, hay varias opciones:

    • Si el --check se utilizó la opción, el clúster antiguo no se modificó; se puede reiniciar.

    • Si el --link la opción era no utilizado, el grupo antiguo no se modificó; se puede reiniciar.

    • Si el --link se utilizó la opción, los archivos de datos podrían compartirse entre el clúster nuevo y antiguo:

      • Si pg_upgrade abortado antes de que comenzara la vinculación, el clúster antiguo no se modificó; se puede reiniciar.

      • Si lo hiciste no iniciar el nuevo clúster, el antiguo clúster no se modificó, excepto que, cuando se inició la vinculación, .old el sufijo se agregó a $PGDATA/global/pg_control. Para reutilizar el clúster antiguo, elimine el .old sufijo de $PGDATA/global/pg_control; A continuación, puede reiniciar el clúster anterior.

      • Si inició el nuevo clúster, se ha escrito en archivos compartidos y no es seguro utilizar el clúster anterior. En este caso, será necesario restaurar el clúster antiguo desde la copia de seguridad.

Notas

pg_upgrade crea varios archivos de trabajo, como volcados de esquema, en el directorio de trabajo actual. Por motivos de seguridad, asegúrese de que ningún otro usuario pueda leer ni escribir en ese directorio.

pg_upgrade lanza postmasters de corta duración en los directorios de datos nuevos y antiguos. Los archivos de socket temporales de Unix para la comunicación con estos administradores de correos se crean, de forma predeterminada, en el directorio de trabajo actual. En algunas situaciones, el nombre de la ruta del directorio actual puede ser demasiado largo para ser un nombre de socket válido. En ese caso, puede utilizar el -s opción para poner los archivos de socket en algún directorio con un nombre de ruta más corto. Por motivos de seguridad, asegúrese de que ningún otro usuario pueda leer ni escribir en ese directorio. (Esto no es compatible con Windows).

Pg_upgrade informará de todos los casos de falla, reconstrucción y reindexación si afectan su instalación; Los scripts posteriores a la actualización para reconstruir tablas e índices se generarán automáticamente. Si está intentando automatizar la actualización de muchos clústeres, debería encontrar que los clústeres con esquemas de base de datos idénticos requieren los mismos pasos posteriores a la actualización para todas las actualizaciones de clústeres; esto se debe a que los pasos posteriores a la actualización se basan en los esquemas de la base de datos y no en los datos del usuario.

Para las pruebas de implementación, cree una copia de solo esquema del clúster anterior, inserte datos ficticios y actualícelos.

pg_upgrade no admite la actualización de bases de datos que contienen columnas de tabla utilizando estos reg* Tipos de datos del sistema de referencia OID:

(regclass, regrole, y regtype se puede actualizar.)

Si está actualizando un clúster anterior a PostgreSQL 9.2 que usa un directorio de solo archivo de configuración, debe pasar la ubicación del directorio de datos real a pg_upgrade y pasar la ubicación del directorio de configuración al servidor, por ejemplo, -d /real-data-directory -o '-D /configuration-directory'.

Si usa un servidor anterior a 9.1 que usa un directorio de socket de dominio Unix no predeterminado o un predeterminado que difiere del predeterminado del nuevo clúster, configure PGHOST para apuntar a la ubicación del socket del servidor antiguo. (Esto no es relevante en Windows).

Si desea utilizar el modo de enlace y no desea que se modifique su antiguo clúster cuando se inicie el nuevo, considere utilizar el modo de clonación. Si no está disponible, haga una copia del clúster anterior y actualícelo en modo de enlace. Para hacer una copia válida del clúster anterior, use rsync para crear una copia sucia del clúster anterior mientras el servidor está en ejecución, luego apague el servidor anterior y ejecute rsync --checksum nuevamente para actualizar la copia con cualquier cambio para que sea consistente. (--checksum es necesario porque rsync solo tiene una granularidad de tiempo de modificación de archivo de un segundo). Es posible que desee excluir algunos archivos, por ejemplo, postmaster.pid, como se documenta en la Sección 25.3.3. Si su sistema de archivos admite instantáneas del sistema de archivos o copias de archivos de copia en escritura, puede usar eso para hacer una copia de seguridad del clúster y los espacios de tabla antiguos, aunque la instantánea y las copias deben crearse simultáneamente o mientras el servidor de la base de datos está inactivo.

Ver también

initdb, pg_ctl, pg_dump, postgres