Actualizar la versión principal de la base de datos in situ

En esta página se describe cómo actualizar la versión principal de la base de datos actualizando la instancia de Cloud SQL in situ en lugar de migrando los datos.

Introducción

Los proveedores de software de bases de datos publican periódicamente nuevas versiones principales que contienen nuevas funciones, mejoras de rendimiento y mejoras de seguridad. Cloud SQL incorpora nuevas versiones después de que se publiquen. Cuando Cloud SQL ofrezca compatibilidad con una nueva versión principal, podrás actualizar tus instancias para mantener tu base de datos actualizada.

Puedes actualizar la versión de la base de datos de una instancia in situ o migrando los datos. Las actualizaciones in situ son una forma más sencilla de actualizar la versión principal de tu instancia. No es necesario migrar datos ni cambiar las cadenas de conexión de la aplicación. Con las actualizaciones in situ, puedes conservar el nombre, la dirección IP y otros ajustes de tu instancia actual después de la actualización. Las actualizaciones in situ no requieren que muevas archivos de datos y se pueden completar más rápido. En algunos casos, el tiempo de inactividad es menor que el que implica migrar tus datos.

La operación de actualización in situ de Cloud SQL para PostgreSQL usa la utilidad pg_upgrade.

Planificar una actualización de versión principal

  1. Confirma que tienes el rol necesario para realizar una actualización de versión principal: Propietario de Cloud SQL o Administrador de Cloud SQL.

  2. Elige una versión principal de destino.

    gcloud

    Para obtener información sobre cómo instalar y empezar a usar la CLI de gcloud, consulta el artículo Instalar la CLI de gcloud. Para obtener información sobre cómo iniciar Cloud Shell, consulta el artículo Usar Cloud Shell.

    Para comprobar las versiones de la base de datos a las que puedes actualizar tu instancia sin cambiarla, haz lo siguiente:

    1. Ejecuta el siguiente comando:
      2. gcloud sql instances describe INSTANCE_NAME

      Sustituye INSTANCE_NAME por el nombre de la instancia.

    2. En la salida del comando, busca la sección con la etiqueta upgradableDatabaseVersions.
    3. Cada subsección devuelve una versión de la base de datos que se puede actualizar. En cada subsección, revisa los siguientes campos.
      • majorVersion: la versión principal a la que puedes orientar la actualización in situ.
      • name: cadena de versión de la base de datos que incluye la versión principal.
      • displayName: el nombre visible de la versión de la base de datos.

    REST v1

    Para comprobar qué versiones de la base de datos de destino están disponibles para una actualización in situ de una versión principal, usa el método instances.get de la API Admin de Cloud SQL.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • INSTANCE_NAME: nombre de la instancia.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    REST v1beta4

    Para comprobar qué versiones de la base de datos de destino están disponibles para la actualización in situ de la versión principal de una instancia, usa el método instances.get de la API Admin de Cloud SQL.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • INSTANCE_NAME: nombre de la instancia.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar tu solicitud, despliega una de estas opciones:

    Deberías recibir una respuesta JSON similar a la siguiente:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    Para ver la lista completa de las versiones de la base de datos que admite Cloud SQL, consulta Versiones de la base de datos y políticas de versiones.

  3. Tenga en cuenta las funciones que se ofrecen en cada versión principal de la base de datos y resuelva las incompatibilidades.

    Las nuevas versiones principales introducen cambios incompatibles que pueden requerir que modifiques el código de la aplicación, el esquema o la configuración de la base de datos. Antes de actualizar tu instancia de base de datos, consulta las notas de la versión principal de destino para determinar las incompatibilidades que debes solucionar.

  4. Prueba la actualización con una prueba sin ejecutar.

    Realiza una prueba del proceso de actualización integral en un entorno de prueba antes de actualizar la base de datos de producción. Puedes clonar tu instancia para crear una copia idéntica de los datos en la que probar el proceso de actualización.

    Además de validar que la actualización se completa correctamente, ejecuta pruebas para asegurarte de que la aplicación se comporta como se espera en la base de datos actualizada.

  5. Decide cuándo quieres cambiarte a una versión superior.

    Para actualizar, la instancia debe dejar de estar disponible durante un periodo. Programa la actualización para un periodo en el que la actividad de la base de datos sea baja.

Prepararse para una actualización de versión principal

Antes de cambiar a una edición superior, completa los siguientes pasos.

  1. Comprueba el valor de LC_COLLATE en las bases de datos template y postgres. El conjunto de caracteres de cada base de datos debe ser en_US.UTF8.

    Si el valor de LC_COLLATE de las bases de datos template y postgres no es en_US.UTF8, la actualización de la versión principal fallará. Para solucionar este problema, si alguna de las bases de datos tiene un conjunto de caracteres distinto de en_US.UTF8, cambia el valor de LC_COLLATE a en_US.UTF8 antes de realizar la actualización.

    Para cambiar la codificación de una base de datos, sigue estos pasos:

    1. Volcar tu base de datos.
    2. Elimina tu base de datos.
    3. Crea una base de datos con una codificación diferente (en este ejemplo, en_US.UTF8).
    4. Vuelve a cargar tus datos.

    Otra opción es cambiar el nombre de la base de datos:

    1. Cierra todas las conexiones a la base de datos.
    2. Cambia el nombre de la base de datos.
    3. Actualiza las configuraciones de tu aplicación para que usen el nuevo nombre de la base de datos.
    4. Crea una base de datos vacía con la codificación predeterminada.

    Te recomendamos que sigas estos pasos en una instancia clonada antes de aplicarlos a una instancia de producción.

  2. Gestiona las extensiones de PostgreSQL que te queden.

    La mayoría de las extensiones funcionan en la versión principal actualizada de la base de datos. Elimina las extensiones que ya no sean compatibles con la versión de destino. Por ejemplo, elimina la extensión chkpass si vas a actualizar a PostgreSQL 11 o versiones posteriores.

    Puedes actualizar PostGIS y sus extensiones relacionadas a las últimas versiones compatibles manualmente.

    En ocasiones, al actualizar de las versiones 2.x de PostGIS, se pueden crear objetos de base de datos sobrantes que no estén asociados a la extensión PostGIS. Esto puede bloquear la operación de actualización. Para obtener información sobre cómo solucionar este problema, consulta el artículo Fixing a broken postgis raster install (en inglés).

    A veces, no se puede completar la actualización a la versión 3.1.7 o posterior de PostGIS debido a que los objetos usan funciones obsoletas. Esto puede bloquear la operación de actualización. Para comprobar el estado de la actualización, ejecuta SELECT PostGIS_full_version();. Si hay advertencias, elimina los objetos que usen las funciones obsoletas y actualiza la extensión PostGIS a cualquier versión intermedia o superior. Cuando hayas completado estas acciones, vuelve a ejecutar el comando SELECT PostGIS_full_version();. Comprueba que no aparezcan advertencias. A continuación, realiza la operación de actualización.

    Para obtener más información sobre cómo actualizar las extensiones de PostGIS, consulta Actualizar PostGIS. Si tienes problemas al actualizar PostGIS, consulta Comprobar la versión de la instancia de PostgreSQL.
  3. Gestiona tus marcas de base de datos personalizadas. Comprueba los nombres de las marcas de base de datos personalizadas que hayas configurado en tu instancia de PostgreSQL. Si tienes problemas asociados a estas marcas, consulta Comprobar las marcas personalizadas de tu instancia de PostgreSQL.
  4. Cuando realices una actualización de una versión principal a otra, intenta conectarte a cada base de datos para comprobar si hay algún problema de compatibilidad. Asegúrate de que tus bases de datos puedan conectarse entre sí. Comprueba el campo datallowconn de cada base de datos para asegurarte de que se permite la conexión. El valor t significa que se permite, mientras que el valor f indica que no se puede establecer una conexión.
  5. Si usas la instalación de Datadog para actualizar tu instancia de Cloud SQL a PostgreSQL 10 o versiones posteriores, antes de realizar la actualización, elimina la función pg_stat_activity().

Limitaciones conocidas

Las siguientes limitaciones afectan a las actualizaciones de versión principal in situ de Cloud SQL para PostgreSQL:

  • No puedes realizar una actualización de versión principal in situ en una réplica externa.
  • Actualizar instancias que tengan más de 1000 bases de datos de una versión a otra puede llevar mucho tiempo y agotarse el tiempo de espera.
  • Usa la instrucción select * from pg_largeobject_metadata; para consultar el número de objetos grandes de cada base de datos PostgreSQL de tu instancia de Cloud SQL. Si el resultado de todas tus bases de datos es superior a 10 millones de objetos grandes, la actualización fallará. Cloud SQL vuelve a la versión anterior de tu base de datos.
  • Antes de realizar una actualización in situ de la versión principal a PostgreSQL 16 o versiones posteriores, actualiza la extensión PostGIS de todas tus bases de datos a la versión 3.4.0.
  • Antes de realizar una actualización in situ de la versión principal a PostgreSQL 17, actualiza la extensión rdkit de todas tus bases de datos a la versión 4.6.1.
  • Antes de realizar una actualización in situ de la versión principal a PostgreSQL 16 o 17, actualiza la extensión pg_squeeze de todas tus bases de datos a la versión 1.6 o 1.7, respectivamente.
  • Si usas las versiones 9.6, 10, 11 o 12 de PostgreSQL, no se admite la versión 3.4.0 de la extensión PostGIS. Por lo tanto, para realizar una actualización in situ de la versión principal a PostgreSQL 16 o versiones posteriores, primero debes actualizar a una versión intermedia de PostgreSQL (versiones 13, 14 o 15).

  • Si instalas la extensión pg_ivm en tu instancia, no podrás realizar una actualización de versión principal. Para solucionarlo, desinstala esta extensión y, a continuación, realiza la actualización. Para obtener más información sobre las extensiones, consulta Configurar extensiones de PostgreSQL.

  • Si habilitas las marcas vacuum_defer_cleanup_age y force_parallel_mode, no podrás actualizar la versión principal. Para solucionarlo, elimina estas marcas y, a continuación, realiza la actualización. Para obtener más información sobre las marcas, incluido cómo eliminarlas, consulta Configurar marcas de la base de datos.

Realizar la actualización de la versión principal

Puedes actualizar la versión principal de una sola instancia de Cloud SQL o de una instancia principal e incluir todas sus réplicas en la actualización, incluidas las réplicas en cascada y las réplicas entre regiones.

Actualizar la versión principal de una sola instancia

Cuando inicias una operación de actualización para una sola instancia, Cloud SQL hace lo siguiente:

  1. Comprueba la configuración de tu instancia para asegurarse de que es compatible con una actualización.
  2. Una vez que Cloud SQL verifique la configuración, la instancia dejará de estar disponible.
  3. Crea una copia de seguridad antes de la actualización.
  4. Realiza la actualización en la instancia.
  5. Hace que tu instancia esté disponible.
  6. Crea una copia de seguridad posterior a la actualización.

Consola

  1. En la Google Cloud consola, ve a la página Instancias de Cloud SQL.

    Ir a Instancias de Cloud SQL

  2. Para abrir la página Overview (Resumen) de una instancia, haz clic en su nombre.
  3. Haz clic en Editar.
  4. En la sección Información de la instancia, haz clic en el botón Actualizar y confirma que quieres ir a la página de actualización.
  5. En la página Elige una versión de la base de datos, haz clic en la lista Versión de la base de datos para la actualización y selecciona una de las versiones principales de la base de datos disponibles.
  6. Haz clic en Continuar.
  7. En el cuadro ID de instancia, introduce el nombre de la instancia y, a continuación, haz clic en el botón Iniciar actualización.
La operación tarda varios minutos en completarse.

Comprueba que la versión principal de la base de datos actualizada aparece debajo del nombre de la instancia en la página Resumen de la instancia.

gcloud

  1. Inicia la actualización.

    Usa el comando gcloud sql instances patch con la marca --database-version.

    Antes de ejecutar el comando, sustituye lo siguiente:

    • INSTANCE_NAME: el nombre de la instancia.
    • DATABASE_VERSION: el enum de la versión principal de la base de datos, que debe ser posterior a la versión actual. Especifica una versión de la base de datos para una versión principal que esté disponible como destino de actualización de la instancia. Puedes obtener este enum como primer paso de Plan for upgrade (Plan para el cambio a un plan superior). Si necesitas una lista completa de enums de versiones de bases de datos, consulta SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Las actualizaciones de versiones principales tardan varios minutos en completarse. Es posible que veas un mensaje que indique que la operación está tardando más de lo previsto. Puedes ignorar este mensaje o ejecutar el comando gcloud sql operations wait para cerrarlo.

  2. Obtén el nombre de la operación de actualización.

    Usa el comando gcloud sql operations list con la marca --instance.

    Antes de ejecutar el comando, sustituye la variable INSTANCE_NAME por el nombre de la instancia. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitoriza el estado de la actualización.

    Usa el comando gcloud sql operations describe.

    Antes de ejecutar el comando, sustituye la variable OPERATION por el nombre de la operación de actualización que has obtenido en el paso anterior. 

    gcloud sql operations describe OPERATION

REST v1

  1. Inicia la actualización in situ.

    Usa una solicitud PATCH con el método instances:patch.

    Antes de usar los datos de la solicitud, sustituye estas variables:

    • PROJECT_ID: el ID del proyecto.
    • INSTANCE_NAME: el nombre de la instancia.

    Método HTTP y URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Cuerpo JSON de la solicitud: 

    {
  "databaseVersion": DATABASE_VERSION
}

    Sustituye DATABASE_VERSION por el enum de la versión principal de la base de datos, que debe ser posterior a la versión actual. Especifica una versión de la base de datos para una versión principal que esté disponible como destino de actualización de la instancia. Puedes obtener este enum como primer paso de Plan for upgrade (Plan para el cambio a un plan superior). Si necesitas una lista completa de enumeraciones de versiones de bases de datos, consulta SqlDatabaseVersion.

  2. Obtén el nombre de la operación de actualización.

    Usa una solicitud GET con el método operations.list después de sustituir PROJECT_ID por el ID del proyecto.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitoriza el estado de la actualización.

    Usa una solicitud GET con el método operations.get después de sustituir las siguientes variables:

    • PROJECT_ID: el ID del proyecto.
    • OPERATION_NAME: nombre de la operación de actualización obtenida en el paso anterior.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Para actualizar la versión de la base de datos, usa un recurso de Terraform y el proveedor de Terraform para Google Cloud, versión 4.34.0 o posterior.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Aplica los cambios

Para aplicar la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

  1. Abre Cloud Shell.

  2. Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

    Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

    Copia el código de ejemplo en el archivo main.tf que acabas de crear.

    También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.

  3. Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo tienes que hacerlo una vez por directorio. 
    terraform init

    Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade: 

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas: 
    terraform plan

    Haga las correcciones necesarias en la configuración.

  2. Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición: 
    terraform apply

    Espera hasta que Terraform muestre el mensaje "Apply complete!".

  3. Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

Eliminar los cambios

Para eliminar los cambios, sigue estos pasos:

  1. Para inhabilitar la protección contra la eliminación, en el archivo de configuración de Terraform, asigna el valor false al argumento deletion_protection. 
    deletion_protection =  "false"
  2. Aplica la configuración de Terraform actualizada ejecutando el siguiente comando e introduciendo yes en la petición: 
    terraform apply

  1. Para quitar los recursos que se hayan aplicado anteriormente con tu configuración de Terraform, ejecuta el siguiente comando e introduce yes en la petición:

    terraform destroy

Cuando envías una solicitud de actualización in situ, Cloud SQL primero realiza una comprobación previa a la actualización. Si Cloud SQL determina que tu instancia no está lista para una actualización, tu solicitud de actualización fallará y se mostrará un mensaje con sugerencias para solucionar el problema. Consulta también Solucionar problemas al actualizar una versión principal.

Incluir réplicas en la actualización de la versión principal

Si tu instancia principal tiene réplicas, puedes incluirlas todas en la actualización. Cloud SQL puede actualizar todas las réplicas de la instancia principal, incluidas las réplicas interregionales y las réplicas en cascada.

Cuando incluyes réplicas en una actualización de versión principal, Cloud SQL hace lo siguiente:

  1. Comprueba la configuración de tu instancia principal y de las réplicas para asegurarse de que la instancia y las réplicas son compatibles con una actualización.
  2. Hace que tu instancia principal no esté disponible.
  3. Crea una copia de seguridad previa a la actualización de la instancia principal.
  4. Detiene la replicación de todas las réplicas.
  5. Realiza la actualización en la instancia principal.
  6. Si la actualización de la instancia principal se realiza correctamente, la instancia principal vuelve a estar disponible y se reinicia la replicación.
  7. Cloud SQL crea una copia de seguridad de la instancia principal después de la actualización.
  8. Cloud SQL procede a actualizar todas las réplicas.

Aunque falle la actualización de la versión principal de una réplica, la instancia principal seguirá estando disponible.

Para incluir réplicas en una actualización de versión principal, no puedes usar laGoogle Cloud consola ni Terraform. Solo puedes usar gcloud CLI o la API Admin de Cloud SQL.

gcloud

  1. Inicia la actualización.

    Usa el comando gcloud sql instances patch con las marcas --database-version y --include-replicas-for-major-version-upgrade.

    Antes de ejecutar el comando, sustituye lo siguiente:

    • INSTANCE_NAME: nombre de la instancia principal.
    • DATABASE_VERSION: el enum de la versión principal de la base de datos, que debe ser posterior a la versión actual. Especifica una versión de la base de datos para una versión principal que esté disponible como destino de actualización de la instancia. Puedes obtener este enum como primer paso de Plan for upgrade (Plan para el cambio a un plan superior). Si necesitas una lista completa de enums de versiones de bases de datos, consulta SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --include-replicas-for-major-version-upgrade

    Las actualizaciones de versiones principales tardan varios minutos en completarse. Es posible que veas un mensaje que indique que la operación está tardando más de lo previsto. Puedes ignorar este mensaje o ejecutar el comando gcloud sql operations wait para cerrarlo. La actualización de las réplicas puede tardar varios minutos en completarse. Para comprobar el estado de la actualización, sigue estos pasos:

  2. Obtén el nombre de la operación de actualización.

    Usa el comando gcloud sql operations list con la marca --instance.

    Antes de ejecutar el comando, sustituye la variable INSTANCE_NAME por el nombre de la instancia. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitoriza el estado de la actualización.

    Usa el comando gcloud sql operations describe.

    Antes de ejecutar el comando, sustituye la variable OPERATION por el nombre de la operación de actualización que has obtenido en el paso anterior. 

    gcloud sql operations describe OPERATION

REST

  1. Inicia la actualización in situ.

    Usa una solicitud PATCH con el método instances:patch.

    Antes de usar los datos de la solicitud, sustituye estas variables:

    • PROJECT_ID: el ID del proyecto.
    • INSTANCE_NAME: el nombre de la instancia.

    Método HTTP y URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Cuerpo JSON de la solicitud: 

    {
  "databaseVersion": DATABASE_VERSION
  "includeReplicasForMajorVersionUpgrade": true
}

    • Sustituye DATABASE_VERSION por el enum de la versión principal de la base de datos, que debe ser posterior a la versión actual. Especifica una versión de la base de datos para una versión principal que esté disponible como destino de actualización de la instancia. Puedes obtener este enum como primer paso de Plan for upgrade (Plan para el cambio a un plan superior). Si necesitas una lista completa de enumeraciones de versiones de bases de datos, consulta SqlDatabaseVersion.
    • En el campo includeReplicasForMajorVersionUpgrade, especifica true.

  2. Obtén el nombre de la operación de actualización.

    Usa una solicitud GET con el método operations.list después de sustituir PROJECT_ID por el ID del proyecto.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitoriza el estado de la actualización.

    Usa una solicitud GET con el método operations.get después de sustituir las siguientes variables:

    • PROJECT_ID: el ID del proyecto.
    • OPERATION_NAME: nombre de la operación de actualización obtenida en el paso anterior.

    Método HTTP y URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Copias de seguridad de actualizaciones automáticas

Cuando realizas una actualización de versión principal, Cloud SQL crea automáticamente dos copias de seguridad bajo demanda, llamadas copias de seguridad de actualización:

  • La primera copia de seguridad de la actualización es la copia de seguridad previa a la actualización, que se crea inmediatamente antes de iniciar la actualización. Puedes usar esta copia de seguridad para restaurar tu instancia de base de datos al estado que tenía en la versión anterior.
  • La segunda copia de seguridad es la copia de seguridad posterior a la actualización, que se crea inmediatamente después de que se permitan nuevas escrituras en la instancia de base de datos actualizada.

Cuando consultes tu lista de copias de seguridad, las copias de seguridad de la actualización se mostrarán con el tipo On-demand. Las copias de seguridad de actualización están etiquetadas para que puedas identificarlas rápidamente. Por ejemplo, si vas a actualizar de PostgreSQL 14 a PostgreSQL 15, la copia de seguridad anterior a la actualización se etiquetará como Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. y la posterior como Post-upgrade backup, POSTGRES_14 to POSTGRES_15..

Al igual que con otras copias de seguridad bajo demanda, las copias de seguridad de la actualización se conservan hasta que las elimines o elimines la instancia. Si tienes habilitada la recuperación a un momento dado, no podrás eliminar tus copias de seguridad de la actualización mientras estén en tu periodo de conservación. Si necesitas eliminar las copias de seguridad de la actualización, debes inhabilitar PITR o esperar hasta que las copias de seguridad de la actualización ya no estén en tu ventana de conservación.

Completar la actualización de la versión principal

Una vez que hayas terminado de actualizar tu instancia principal, sigue estos pasos para completar la actualización:

  1. Actualiza las estadísticas de la base de datos.

    Ejecuta ANALYZE en tu instancia principal para actualizar las estadísticas del sistema después de la actualización. Las estadísticas precisas aseguran que el planificador de consultas de PostgreSQL procese las consultas de forma óptima. Si faltan estadísticas, se pueden generar malos planes de consulta, lo que a su vez puede reducir el rendimiento y ocupar demasiada memoria.

  2. Realizar pruebas de aceptación.

    Realiza pruebas para asegurarte de que el sistema actualizado funciona correctamente.

Solucionar problemas al cambiar a una versión principal

Cloud SQL devuelve un mensaje de error si intentas ejecutar un comando de actualización no válido. Por ejemplo, si tu instancia contiene marcas de base de datos no válidas para la nueva versión.

Si tu solicitud de actualización falla, comprueba la sintaxis de la solicitud. Si la solicitud tiene una estructura válida, prueba a seguir estas sugerencias.

Ver los errores de comprobación previa a la actualización

Los errores de comprobación previa a la actualización son problemas o errores que Cloud SQL detecta durante el proceso de verificación o validación previo a la actualización. Estos errores se producen antes de que empiece el proceso de actualización propiamente dicho y tienen como objetivo identificar posibles problemas o incompatibilidades que puedan afectar al éxito de la actualización.

Los errores de comprobación previa a la actualización se muestran en las siguientes categorías:

  • Extensiones incompatibles: detecta las extensiones de PostgreSQL que no son compatibles con la versión de destino de la instancia.
  • Dependencias no admitidas: identifica las dependencias que ya no se admiten o que deben actualizarse.
  • Incompatibilidades de formato de datos: verifica las incoherencias de datos que surgen de varios factores, como las diferencias en las estructuras de datos específicas de cada versión, las alteraciones en la codificación y la ordenación, las modificaciones en los tipos de datos y los ajustes en el catálogo del sistema.

En la siguiente tabla se muestran los fallos de comprobación previos a la actualización y sus mensajes de error:

Error en la comprobación previa a la actualización Mensaje de error
Cloud SQL detecta un tipo de datos desconocido. Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Al actualizar a PostgreSQL 12 o versiones posteriores, Cloud SQL detecta el tipo de datos 'sql_identifier'. Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta el tipo de datos reg*. Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta que el valor
LC_COLLATE de la base de datos postgres es un conjunto de caracteres distinto de en_US.UTF8.		 Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
Cloud SQL detecta las tablas que tienen identificadores de objeto (OIDs). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL detecta tipos de datos compuestos. Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta operadores de sufijo definidos por el usuario. Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name)
Cloud SQL detecta funciones polimórficas incompatibles. Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name)
Cloud SQL detecta las conversiones de codificación definidas por el usuario. Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name)
Cloud SQL detecta una ruta de búsqueda vacía para la función ll_to_earth Please update the search path of the 'll_to_earth' function
Cloud SQL detecta la presencia de archivos ráster de PostGIS sin comprimir. PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade.

Solucionar el problema de la ruta de búsqueda vacía

Esto ocurre porque la extensión earthdistance usa los tipos earth y cube sin especificar la ruta de búsqueda de la función. Debe especificar esta ruta, que es obligatoria durante el proceso de actualización.

Para evitar este problema, Cloud SQL realiza una comprobación automática previa a la actualización que verifica si la función ll_to_earth tiene un ajuste search_path para asegurarse de que se pueden resolver sus dependencias. Si no se ha definido ningún search_path específico de la función, la comprobación fallará y se mostrará el siguiente mensaje de error:

Please update the search path of the 'll_to_earth' function
(database: [your-db], search path: )

Para solucionar este problema, corrige la ruta de búsqueda de la función ll_to_earth ejecutando esta consulta: ALTER FUNCTION ll_to_earth SET search_path = public;

Ver los registros de errores

Si se produce algún problema con una solicitud de actualización válida, Cloud SQL publicará los registros de errores en projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Cada entrada de registro contiene una etiqueta con el identificador de instancia para ayudarte a identificar la instancia con el error de actualización. Busca estos errores de actualización y resuélvelos.

Para ver los registros de errores, usa la Google Cloud consola::

  1. En la Google Cloud consola, ve a la página Instancias de Cloud SQL.

    Ir a Instancias de Cloud SQL

  2. Para abrir la página Overview (Resumen) de una instancia, haz clic en su nombre.

  3. En el panel Operaciones y registros de la página Resumen de la instancia, haga clic en el enlace Ver registros de errores de PostgreSQL.

    Se abrirá la página Explorador de registros.

  4. Para ver los registros, sigue estos pasos:

    • Para ver todos los registros de errores de un proyecto, selecciona el nombre del registro en el filtro de registro Nombre del registro.

    Para obtener más información sobre los filtros de consulta, consulta Consultas avanzadas.

    • Para filtrar los registros de errores de actualización de una sola instancia, introduce la siguiente consulta en el cuadro Buscar en todos los campos, después de sustituir DATABASE_ID

    con el ID del proyecto seguido del nombre de la instancia en este formato: project_id:instance_name.

    resource.type="cloudsql_database"
resource.labels.database_id="DATABASE_ID"
logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    Por ejemplo, para filtrar los registros de errores de actualización por una instancia llamada shopping-db que se ejecuta en el proyecto buylots, usa el siguiente filtro de consulta:

     resource.type="cloudsql_database"
 resource.labels.database_id="buylots:shopping-db"
 logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    Puede revisar todos los registros notificados en un periodo determinado o filtrar los registros por gravedad. Una opción habitual para solucionar problemas puede ser seleccionar los siguientes filtros:

    • Emergencia
    • Alerta
    • Crítica
    • Error

Las entradas de registro con el prefijo pg_upgrade_dump indican que se ha producido un error de actualización. Por ejemplo:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

Además, las entradas de registro etiquetadas con un nombre de archivo secundario .txt pueden mostrar otros errores que te interese resolver antes de volver a intentar la actualización.

Todos los nombres de archivo se encuentran en el archivo postgres-upgrade.log. Para localizar un nombre de archivo, consulta el campo labels.FILE_NAME.

Estos son algunos de los nombres de archivo que pueden contener errores que debes resolver:

  • tables_with_oids.txt: Este archivo contiene tablas que se muestran con identificadores de objeto (OIDs). Elimina las tablas o modifícalas para que no usen OIDs.
  • tables_using_composite.txt: Este archivo contiene tablas que se muestran mediante tipos compuestos definidos por el sistema. Elimina las tablas o modifícalas para que no usen estos tipos compuestos.
  • tables_using_unknown.txt: Este archivo contiene tablas que se muestran con el tipo de datos UNKNOWN. Elimina las tablas o modifícalas para que no usen este tipo de datos.
  • tables_using_sql_identifier.txt: Este archivo contiene tablas que se enumeran con el tipo de datos SQL_IDENTIFIER. Elimina las tablas o modifícalas para que no usen este tipo de datos.
  • tables_using_reg.txt: Este archivo contiene tablas que se enumeran con el tipo de datos REG* (por ejemplo, REGCOLLATION o REGNAMESPACE). Elimine las tablas o modifíquelas para que no usen este tipo de datos.
  • postfix_ops.txt: Este archivo contiene tablas que se enumeran con operadores de sufijo (unarios por la derecha). Elimina las tablas o modifícalas para que no usen estos operadores.

Comprobar la memoria

Si la instancia no tiene suficiente memoria compartida, es posible que veas este mensaje de error: ERROR: out of shared memory. Este error es más probable que se produzca si tienes más de 10.000 tablas.

Antes de intentar actualizar, define el valor de la marca max_locks_per_transaction en aproximadamente el doble del número de tablas de la instancia. La instancia se reinicia cuando cambias el valor de esta marca.

Comprobar la capacidad de las conexiones

Si tu instancia no tiene suficiente capacidad de conexión, es posible que veas este mensaje de error: ERROR: Insufficient connections.

Cloud SQL recomienda que aumentes el valor de la marca max_connections en función del número de bases de datos de tu instancia. La instancia se reinicia cuando cambias el valor de esta marca.

Comprobar si hay una referencia de columna ambigua

Cloud SQL realiza automáticamente una comprobación previa a la actualización para identificar las vistas definidas por el usuario que dependen de las vistas del catálogo del sistema, como pg_stat_activity o pg_stat_replication. La estructura de las columnas de estas vistas de catálogo del sistema puede cambiar entre las versiones principales de PostgreSQL. Si tienes vistas que select * o dependen del orden de las columnas de estas vistas del sistema, es posible que se vuelvan incompatibles después de una actualización, lo que provocaría un error, como ERROR: column reference "column_name" is ambiguous.

La comprobación previa a la actualización detecta estas vistas comprobando las dependencias. Si se encuentran vistas incompatibles, el proceso de actualización se detiene y se muestra un mensaje de error. En este mensaje se enumeran las vistas incompatibles de cada base de datos que deben corregirse.

Ejemplo de mensaje de error

  • Si tienes problemas relacionados con pg_stat_activity: 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • Si tienes problemas relacionados con pg_stat_replication:

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

Para resolver estos problemas y continuar con la actualización, sigue estos pasos: 1. Identifica las vistas que se indican en el mensaje de error de la comprobación previa a la actualización.

  1. Elimina estas vistas con DROP VIEW view_name;.

  2. Vuelve a intentar la actualización de la versión principal.

  3. Una vez que se haya completado la actualización, vuelva a crear las vistas. Asegúrate de que las nuevas definiciones de vista sean compatibles con el esquema de las vistas del catálogo del sistema en la versión actual de PostgreSQL. Es posible que tengas que enumerar las columnas de forma explícita en lugar de usar select * para evitar problemas en el futuro.

Para ver un ejemplo más detallado del problema y más información, consulta esta conversación de Stack Overflow.

Comprobar si hay SRFs en las instrucciones CASE

Si vas a actualizar tu instancia desde la versión 9.6 y usas funciones que devuelven conjuntos en tus instrucciones CASE, es posible que veas este mensaje de error:ERROR: set-returning functions are not allowed in CASE. Este problema se produce porque, a partir de la versión 10, no se permite usar funciones que devuelven conjuntos en las instrucciones CASE.

Para solucionar este problema y actualizar tu instancia correctamente, asegúrate de que se hayan modificado todas las instrucciones CASE que utilicen funciones que devuelvan conjuntos para evitar su uso antes de volver a intentar la actualización. Algunos SRFs que se suelen usar son los siguientes:

  • unnest()
  • generate_series()
  • array_agg()
  • regexp_split_to_table()
  • jsonb_array_elements()
  • json_array_elements()
  • sonb_each()
  • json_each()

Consultar las vistas creadas en emisiones personalizadas

Si ha creado una vista en un elemento de contenido personalizado, aparecerá un mensaje de error similar al siguiente: ERROR: cannot cast type <type_1> to <type_2>. Este problema se debe a problemas de permisos en las emisiones creadas de forma personalizada.

Para solucionar este problema, actualice su instancia a [PostgreSQL version].R20240910.01_02

Para obtener más información, consulta Mantenimiento de autoservicio.

Comprobar la propiedad de los activadores de eventos

En Cloud SQL, todos los activadores de eventos deben pertenecer a un usuario con el rol cloudsqlsuperuser. Cloud SQL realiza una comprobación previa a la actualización para validar la propiedad de todos los activadores de eventos. Si un activador de evento es propiedad de un usuario que no tiene el rol cloudsqlsuperuser, el proceso de actualización se detendrá y es posible que recibas un mensaje de error, como el siguiente:

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

Para solucionar este problema, cambie el propietario del activador de eventos a un usuario que tenga el rol cloudsqlsuperuser, como postgres, o asigne el rol cloudsqlsuperuser al propietario actual.

Para identificar los activadores de eventos cuyos propietarios no tienen el rol necesario, ejecuta el siguiente comando:

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

Los resultados muestran cualquier activador de evento con un propietario que no tenga el rol cloudsqlsuperuser.

Comprobar las columnas generadas de tablas sin registrar

Si tienes una tabla sin registrar que tiene columnas generadas, puede que veas el mensaje de error ERROR: unexpected request for new relfilenumber in binary upgrade mode. Este problema se debe a las discrepancias en las características de persistencia entre las tablas y sus secuencias de columnas generadas.

Para solucionar este problema, siga estos pasos:

  1. Eliminar tablas sin registrar: si es posible, elimina las tablas sin registrar que estén vinculadas a columnas generadas. Asegúrate de que se pueda mitigar la pérdida de datos de forma segura antes de continuar.
  2. Convertir en tablas permanentes: convierte temporalmente las tablas sin registrar en tablas permanentes siguiendo estos pasos:
    1. Convertir la tabla en una tabla registrada ALTER TABLE SET LOGGED;
    2. Realizar una actualización de versión principal
    3. Volver a convertir la tabla en una tabla sin registrar ALTER TABLE SET UNLOGGED

Puedes identificar todas estas tablas con la siguiente consulta :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

Comprobar las marcas personalizadas de una instancia de PostgreSQL

Si vas a actualizar a una instancia de PostgreSQL de la versión 14 o posterior, comprueba los nombres de las marcas de base de datos personalizadas que hayas configurado en la instancia. Esto se debe a que PostgreSQL ha añadido restricciones a los nombres permitidos para los parámetros personalizados.

El primer carácter de una marca de base de datos personalizada debe ser alfabético (A-Z o a-z). Todos los caracteres posteriores pueden ser alfanuméricos, el carácter especial de guion bajo (_) o el carácter especial de signo de dólar ($).

Quitar extensiones

Si estás actualizando tu instancia de Cloud SQL, puede que veas este mensaje de error: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Para solucionar este problema, sigue estos pasos:

  1. Quita las extensiones pg_stat_statements y pgstattuple.
  2. Realiza la actualización.
  3. Vuelve a instalar las extensiones.

Restaurar la instancia principal a la versión principal anterior

Si el sistema de base de datos actualizado no funciona como se esperaba, es posible que tengas que restaurar la instancia principal a la versión anterior. Para ello, restaura la copia de seguridad anterior a la actualización en una instancia de recuperación de Cloud SQL, que es una instancia nueva que ejecuta la versión anterior a la actualización.

Para restaurar una instancia principal a la versión anterior, sigue estos pasos:

  1. Identifica la copia de seguridad que has creado antes de actualizar.

    Consulta Copias de seguridad de actualizaciones automáticas.

  2. Crea una instancia de recuperación.

    Crea una instancia de Cloud SQL con la versión principal que tenía Cloud SQL cuando se creó la copia de seguridad previa a la actualización. Define las mismas marcas y los mismos ajustes de instancia que la instancia original.

  3. Restaura la copia de seguridad que creaste antes de actualizar.

    Restaura la copia de seguridad que creaste antes de la actualización en la instancia de recuperación. Este proceso puede tardar varios minutos.

  4. Añade tus réplicas de lectura.

    Si usas réplicas de lectura, añádelas de forma individual.

  5. Conecta tu aplicación.

    Una vez que hayas recuperado tu sistema de base de datos, actualiza tu aplicación con los detalles sobre la instancia de recuperación y sus réplicas de lectura. Puedes reanudar el servicio de tráfico en la versión anterior a la actualización de tu base de datos.

Preguntas frecuentes

Pueden surgir las siguientes preguntas al actualizar la versión principal de la base de datos.

¿Mi instancia no estará disponible durante una actualización?
Sí. Tu instancia no estará disponible durante un periodo mientras Cloud SQL realiza la actualización.
¿Cuánto tiempo tarda una actualización?

La actualización de una sola instancia suele tardar menos de 10 minutos. Si la configuración de tu instancia tiene un número reducido de vCPUs o de memoria, es posible que la actualización tarde más tiempo.

Si tu instancia aloja demasiadas bases de datos o tablas, o si tus bases de datos son muy grandes, la actualización puede tardar horas o incluso agotarse el tiempo de espera, ya que el tiempo total de actualización corresponde al número de objetos de tus bases de datos. Si tienes varias instancias que necesitan actualizarse, el tiempo de actualización aumentará proporcionalmente. Si incluyes réplicas en la actualización, la operación puede tardar hasta una hora en completarse, en función del número de réplicas que tenga tu instancia principal.

¿Puedo monitorizar cada paso del proceso de actualización?
Aunque Cloud SQL te permite monitorizar si una operación de actualización sigue en curso, no puedes hacer un seguimiento de los pasos individuales de cada actualización.
¿Puedo cancelar el cambio a un plan superior después de haberlo iniciado?
No, no puedes cancelar una actualización una vez que haya empezado. Si la actualización falla, Cloud SQL recupera automáticamente la instancia en la versión anterior.
¿Qué ocurre con mi configuración durante una actualización?

Cuando realizas una actualización in situ de la versión principal, Cloud SQL conserva los ajustes de tu base de datos, incluido el nombre de la instancia, la dirección IP, los valores de las marcas configuradas explícitamente y los datos de usuario. Sin embargo, el valor predeterminado de las variables del sistema puede cambiar. Por ejemplo, el valor predeterminado de la marca password_encryption en PostgreSQL 13 y versiones anteriores es md5. Cuando actualices a PostgreSQL 14, el valor predeterminado de esta marca cambiará a scram-sha-256.

Para obtener más información, consulta Configurar marcas de bases de datos. Si una marca o un valor concretos ya no se admiten en la versión de destino, Cloud SQL quitará automáticamente la marca durante la actualización.

Siguientes pasos