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. Realiza la comprobación previa para las actualizaciones.

  5. 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.

  6. 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. En PostgreSQL 18, actualiza a la versión 3.6.0 de PostGIS.
  • 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, 17 o 18, actualiza la extensión pg_squeeze de todas tus bases de datos a la versión 1.6, 1.7 o 1.8, 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.

Evaluar si tu instancia está preparada para la actualización

Cloud SQL te permite ejecutar una comprobación previa en tu instancia antes de actualizar a una versión principal. Esta comprobación previa es una operación de larga duración (OLD) que comprueba si tu instancia está lista para una actualización. Ayuda a encontrar posibles problemas, como incompatibilidades, problemas de configuración o problemas con los datos, antes de la operación de actualización.

La comprobación previa confirma si se puede actualizar la instancia o muestra los problemas que debes solucionar primero y sus soluciones. Estos problemas pueden deberse a extensiones incompatibles, dependencias no admitidas o problemas con el formato de los datos.

La comprobación previa lee principalmente los metadatos de tu instancia y realiza comprobaciones. Estas tareas no afectan al rendimiento de tu instancia ni provocan tiempos de inactividad. Te recomendamos que ejecutes la comprobación previa, ya que ayuda a evitar errores de actualización y tiempos de inactividad inesperados.

Cuando ejecutas la comprobación previa, ocurre lo siguiente:

  • No se ha detectado ningún problema: la comprobación previa se ha completado correctamente y no se ha detectado ningún problema.
  • Se han encontrado problemas que impiden la actualización: la comprobación previa se ha completado correctamente, pero se han detectado errores que impiden la actualización. Los problemas deben resolverse antes de la actualización.
  • Se han encontrado advertencias no bloqueantes: la comprobación previa se ha completado correctamente y se han encontrado advertencias, pero ninguna de ellas impide la actualización.

En función de los resultados de la comprobación previa, puedes continuar con la actualización o solucionar los problemas identificados antes de actualizar.

Limitaciones

Cuando uses la comprobación previa de la actualización de la versión principal, ten en cuenta estas limitaciones:

  • El estado de la instancia debe ser RUNNING.
  • La instancia debe ser una instancia principal. La comprobación previa no admite instancias réplica.

  • La instancia no debe tener ninguna operación de bloqueo pendiente. Si hay una operación de bloqueo pendiente, la comprobación previa dará como resultado un error con el siguiente mensaje:

    Operation failed because another operation was already in progress. Try
your request after the current operation is complete.

  • La comprobación previa debe conectarse a todas las bases de datos de la instancia. Si no se puede acceder a una base de datos, está bloqueada o no responde, es posible que la comprobación previa falle o muestre errores. Aunque la comprobación previa no afecta al rendimiento de tu instancia ni provoca tiempos de inactividad, te recomendamos que la ejecutes cuando la carga de la base de datos sea baja.

Antes de empezar

Realizar la comprobación previa

Para realizar la comprobación previa de la actualización de la versión principal, siga estos pasos:

gcloud

  1. Ejecuta la comprobación previa:

    gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
--target-database-version=TARGET_DATABASE_VERSION \
--project=PROJECT_ID \
[--async]

    Haz los cambios siguientes:

    • INSTANCE_NAME: el nombre de la instancia.
    • TARGET_DATABASE_VERSION: la versión principal a la que quieres actualizar tu instancia. Para consultar la versión de la base de datos, consulta Planificar una actualización.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .

  2. Obtén el nombre de la operación de comprobación previa:

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

    gcloud sql operations list --instance=INSTANCE_NAME

    Haz los cambios siguientes:

    • INSTANCE_NAME: el nombre de la instancia.

  3. Monitoriza el estado de la comprobación previa.

    Usa el comando gcloud sql operations describe:

    gcloud sql operations describe OPERATION_NAME

    Haz los cambios siguientes:

    • OPERATION_NAME: el nombre de la operación de comprobación previa obtenida en el paso anterior.

REST v1

  1. Ejecuta la comprobación previa.

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

    • PROJECT_ID: el ID del proyecto
    • INSTANCE_ID: el ID de instancia.
    • TARGET_DATABASE_VERSION: la versión principal a la que se va a actualizar. Para ver una lista de las versiones de la base de datos disponibles, consulta Planificar una actualización.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Cuerpo JSON de la solicitud: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

    Para enviar tu solicitud, despliega una de estas opciones:

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Obtén el nombre de la operación de comprobación previa.

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

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

    Haz los cambios siguientes:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud .

  3. Monitoriza el estado de la comprobación previa.

    Usa la solicitud GET con el método operations.list:

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

    Haz los cambios siguientes:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • OPERATION_NAME: el nombre de la operación de comprobación previa obtenido en el paso anterior.

REST v1beta4

  1. Ejecuta la comprobación previa.

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

    • PROJECT_ID: el ID del proyecto
    • INSTANCE_ID: el ID de instancia.
    • TARGET_DATABASE_VERSION: la versión principal a la que se va a actualizar. Para ver una lista de las versiones de la base de datos disponibles, consulta Planificar una actualización.

    Método HTTP y URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Cuerpo JSON de la solicitud: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

    Para enviar tu solicitud, despliega una de estas opciones:

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Obtén el nombre de la operación de comprobación previa.

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

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

    Haz los cambios siguientes:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud .

  3. Monitoriza el estado de la comprobación previa.

    Usa la solicitud GET con el método operations.list:

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

    Haz los cambios siguientes:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • operation_name: el nombre de la operación de comprobación previa obtenido en el paso anterior.

Revisar los resultados de la comprobación previa

Una vez finalizada la comprobación previa, tu instancia estará lista para actualizarse o tendrá problemas que requieren tu atención.

Listo para actualizar

Si la comprobación previa se completa correctamente y el array preCheckResponse está vacío, significa que no se han encontrado problemas ni advertencias. Tu instancia está lista para actualizarse a la versión principal. Para continuar, consulta Actualizar la versión principal.

No está listo para la actualización

Si la comprobación previa se ha realizado correctamente y la matriz preCheckResponse contiene problemas, tu instancia no está lista para la actualización y requiere atención. Los problemas identificados pueden impedir o no la actualización. Estos problemas se indican en las preCheckResponse con los siguientes tipos de mensajes:

Tipo Descripción ¿Bloqueo mejorado?
INFO Un mensaje informativo. No
WARNING Se ha detectado un posible problema, pero no impide la actualización. Cloud SQL recomienda revisar y solucionar la advertencia antes de actualizar para asegurar la compatibilidad total. No
ERROR Se ha detectado un problema crítico que impide la actualización. Estos problemas pueden provocar que la actualización falle. Debes resolverlos antes de actualizar tu instancia. Sí

Si tu instancia solo tiene mensajes de INFO o WARNING, puedes actualizarla, pero es posible que tengas problemas después de la actualización. Te recomendamos que revises los detalles del mensaje y resuelvas el problema antes de actualizar. Si tu instancia tiene mensajes ERROR, debes resolver estos problemas antes de actualizarla.

Cada tipo de problema incluye los campos message y actions_required. Revisa cada problema para saber de qué tipo es y cómo solucionarlo. Para obtener más información sobre los problemas habituales y sus soluciones, consulta Errores habituales en la comprobación previa de la actualización de la versión principal.

Una vez que hayas resuelto los problemas, vuelve a ejecutar la comprobación previa para confirmar que tu instancia está lista para la actualización. A continuación, actualiza tu instancia una vez que se haya completado la comprobación previa.

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 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 puedes 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. La falta de estadísticas puede dar lugar a planes de consulta incorrectos, lo que a su vez puede degradar el rendimiento y ocupar una cantidad excesiva de 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 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 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.

Operación de MVU que se ejecuta durante más tiempo

Hay dos tareas subyacentes asociadas a la actualización de una versión principal:

  • Operación de comprobación previa: devuelve un error de tiempo de espera si no se completa en un plazo de tres horas.
  • Operación de actualización: devuelve un error de tiempo de espera si no se completa en seis horas.

Si la instancia tiene una operación MAJOR_VERSION_UPGRADE en curso durante un periodo de tiempo superior al esperado, investiga los registros de errores de PostgreSQL. Esto puede deberse a problemas habituales, como los siguientes:

  • Un gran número de tablas, vistas o índices
  • Recursos insuficientes, como la CPU o la memoria
  • Transacciones importantes que impiden que se cierren las bases de datos para que empiece el proceso de actualización. Puedes usar la Google Cloud consola para comprobar los procesos actuales.

Errores habituales de comprobación previa de la actualización de la versión principal

Los problemas detectados por la comprobación previa de la actualización de la versión principal se dividen en las siguientes categorías:

  • Extensiones incompatibles: son extensiones de Cloud SQL para PostgreSQL de tu instancia que no funcionan con la nueva versión principal.

  • Dependencias no compatibles: son dependencias que no son compatibles con la nueva versión principal o que necesitan actualizaciones para funcionar con ella.

  • Incompatibilidades de la base de datos: se trata de problemas con tu base de datos o tus datos que pueden producirse después de una actualización importante de la versión. Esto incluye diferencias en las estructuras de las bases de datos, los tipos de datos, la codificación, la ordenación o los cambios en el catálogo del sistema específicos de la nueva versión.

Extensiones incompatibles

En la siguiente tabla se enumeran los errores habituales relacionados con extensiones incompatibles que puede detectar la comprobación previa de la actualización de la versión principal:

Tipo Ejemplo de error Resolución
Extensión no admitida o obsoleta Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s) Quita la extensión de todas las bases de datos que la usen con DROP EXTENSION $extension_name;.
Versión de extensión incompatible Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s) Actualiza la extensión a una versión que funcione con la versión de Cloud SQL para PostgreSQL de destino. Para ver las versiones compatibles, consulta Configurar extensiones de Cloud SQL para PostgreSQL.
PostGIS archivos sin empaquetar 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. Limpia los archivos ráster sin empaquetar.
PostGIS funciones obsoletas PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade. Busca y elimina o cambia los objetos de la base de datos que usen funciones PostGIS obsoletas antes de actualizar la extensión PostGIS.
Propiedad de la extensión Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user) Cambia el propietario de la extensión con ALTER EXTENSION postgres_fdw OWNER TO postgres;.

Dependencias no admitidas

En la siguiente tabla se enumeran los errores habituales relacionados con las dependencias no admitidas que puede encontrar la comprobación previa de la actualización de la versión principal:

Tipo Ejemplo de error Resolución
Propiedad del activador de eventos 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) Conéctate a la base de datos identificada mediante psql o Cloud SQL Studio y cambia el propietario del activador a un usuario de postgres.
Instrucciones preparadas sin confirmar Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact) Confirma o revierte la instrucción preparada.
Marcas obsoletas flag "force_parallel_mode" is deprecated in new postgres version, Please delete this flag before retrying again Quita la marca de la base de datos de la configuración de la instancia.

Incompatibilidades de bases de datos

En la siguiente tabla se enumeran los errores habituales relacionados con incompatibilidades de formato de datos que puede detectar la comprobación previa de la actualización de la versión principal:

Tipo Ejemplo de error Resolución
Tipo de datos desconocido Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Elimina la columna o la tabla, o cambia el tipo de datos de la tabla con ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT;.
Tipo de datos reg* Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Quita la columna o cambia su tipo de datos.
Tipo de datos eliminado Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ... Convierte el valor a TEXT, timestamptz u otro tipo de datos adecuado.
​​aclitem Formato interno Please remove the following usages of 'aclitem' data types before attempting an upgrade: ... Deja de usar aclitem en las definiciones de las tablas de tu base de datos.
Tipos de datos compuestos definidos por el sistema Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Cambia las columnas identificadas para que usen un tipo compuesto definido por el usuario o un tipo de datos estándar. Es posible que los tipos compuestos del sistema no sean coherentes en las versiones principales.
Tablas con OIDS Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table) Actualiza la tabla con ALTER TABLE my_table SET WITHOUT OIDS;.
Operadores postfix definidos por el usuario Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype) Quita los operadores personalizados de postfix. Es posible que tengas que reescribir el código para usar operadores de prefijo o llamadas a funciones.
Funciones polimórficas incompatibles Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func) Quita o cambia la función para eliminar las funciones polimórficas incompatibles. Esto puede implicar ajustar las firmas o la lógica de las funciones para que funcionen con Cloud SQL para PostgreSQL 14 y versiones posteriores.
Conversiones de codificación definidas por el usuario Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv) Elimina la conversión de codificación definida por el usuario. Es posible que tengas que volver a crearla después de la actualización con una firma que funcione con la nueva versión.
Comprobar si hay una referencia de columna ambigua Cloud SQL comprueba automáticamente si hay vistas definidas por el usuario que dependen de vistas de catálogo del sistema. La estructura de las columnas de estas vistas de catálogo del sistema puede cambiar entre versiones principales.

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) 		Busca las vistas que se indican en el mensaje de error y elimínalas con el comando DROP VIEW. Después de la actualización, vuelve a crear las vistas.
Tablas sin registrar con columnas generadas o secuencias registradas Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table) Puedes convertir la tabla a LOGGED o quitarla con el comando DROP TABLE. Vuelve a crear la tabla después de la actualización.
Solucionar el problema de la ruta de búsqueda vacía Please update the search path of the 'll_to_earth' function (database: your_db, search path: ) La extensión earthdistance usa earth y cube types sin especificar la ruta de búsqueda de la función. Actualiza la ruta de búsqueda con ALTER FUNCTION ll_to_earth SET search_path = public;.

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