Actualiza la versión principal de la base de datos de manera local

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se describe cómo actualizar la versión principal de la base de datos mediante la actualización de tu instancia de Cloud SQL in situ en lugar de hacerlo mediante la migración de datos.

Introducción

Periódicamente, los proveedores de software de base de datos lanzan nuevas versiones principales que contienen nuevas funciones y mejoras de rendimiento y seguridad. Cloud SQL toma versiones nuevas después de su lanzamiento. Una vez que Cloud SQL ofrece compatibilidad con una versión principal nueva, puedes actualizar las instancias para mantener la base de datos actualizada.

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

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

Planifica una actualización de la 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 comenzar a usar la CLI de gcloud, consulta Instala la CLI de gcloud. Para obtener información sobre cómo iniciar Cloud Shell, consulta Usa Cloud Shell.

   Para verificar las versiones de las bases de datos a las que puedes orientar una actualización in situ en tu instancia, haz lo siguiente:

   1. Ejecuta el siguiente comando.

   gcloud sql instances describe INSTANCE_NAME
      

   Reemplaza INSTANCE_NAME por el nombre de la instancia.

   2. En el resultado del comando, busca la sección etiquetada upgradableDatabaseVersions.
   3. Cada apartado devuelve una versión de base de datos que está disponible para actualización. En cada subartículo, revisa los siguientes campos.
   • majorVersion: la versión principal a la que puedes orientar la actualización in situ.
   • name: la 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.
   Nota: Si upgradableDatabaseVersions no aparece en el resultado, es posible que tu instancia ya esté ejecutando la versión principal de la base de datos compatible más reciente o que la instancia no se esté ejecutando. Las réplicas externas no se pueden actualizar in situ.

   REST v1

   Para verificar qué versiones de bases 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 de Cloud SQL Admin.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • INSTANCE_NAME: El 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, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

   Nota: Si upgradableDatabaseVersions no aparece en la respuesta, es posible que tu instancia ya esté ejecutando la versión principal de la base de datos más reciente compatible o que la instancia no se esté ejecutando. Las réplicas externas no se pueden actualizar in situ.

   REST v1beta4

   Para verificar qué versiones de bases 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 de Cloud SQL Admin.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • INSTANCE_NAME: El 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, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

   Nota: Si upgradableDatabaseVersions no aparece en la respuesta, es posible que tu instancia ya esté ejecutando la versión principal de la base de datos más reciente compatible o que la instancia no se esté ejecutando. Las réplicas externas no se pueden actualizar in situ.

   Para obtener la lista completa de las versiones de bases de datos compatibles con Cloud SQL, consulta Versiones de bases de datos y políticas de versiones

3. Considera las características que se ofrecen en cada versión principal de la base de datos y aborda las incompatibilidades.

   • PostgreSQL 18
   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14
   • PostgreSQL 13
   • PostgreSQL 12
   • PostgreSQL 11
   • PostgreSQL 10

   Las nuevas versiones principales agregan 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 que puedas actualizar la instancia de la base de datos, debes revisar las notas de la versión principal de destino para determinar las incompatibilidades que debes abordar.

4. Realiza la verificación previa para las actualizaciones.

5. Prueba la actualización con una ejecución de prueba.

   Realiza una ejecución de prueba del proceso de actualización de extremo a extremo 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 los que probarás el proceso de actualización.

   Además de validar que la actualización se complete con éxito, ejecuta pruebas para asegurarte de que la aplicación se comporte como se espera en la base de datos actualizada.

   Nota: Asegúrate de tener suficiente espacio en el disco antes de ejecutar una actualización de versión principal. Si no habilitaste los aumentos automáticos de almacenamiento, toma nota del almacenamiento en disco que usa la instancia de ejecución de prueba actualizada. Esto te ayuda a determinar si necesitas aumentar la capacidad de almacenamiento para la instancia de producción antes de realizar la actualización.

6. Decide el momento de la actualización.

   La actualización requiere que la instancia deje de estar disponible durante un período. Planifica la actualización durante un período en el que la actividad de la base de datos sea baja. Te recomendamos que no realices una actualización de versión principal durante períodos de tráfico alto o cuando haya transacciones de larga duración activas en tu base de datos.

Prepárate para una actualización de versión principal

Antes de realizar la actualización, completa los siguientes pasos.

1. Verifica el valor LC_COLLATE para las bases de datos template y postgres. El grupo de caracteres para cada base de datos debe ser en_US.UTF8.

   Si el valor LC_COLLATE para las bases de datos template y postgres no es en_US.UTF8, la actualización de la versión principal falla. Para solucionar esto, si alguna de las bases de datos tiene un grupo de caracteres que no sea en_US.UTF8, cambia el valor LC_COLLATE a en_US.UTF8 antes de realizar la actualización.

   Para cambiar la codificación de una base de datos, haz lo siguiente:

   1. Vuelca tu base de datos.
   2. Borra tu base de datos.
   3. Crea una base de datos nueva con la codificación diferente (para 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. Cambiar el nombre de la base de datos
   3. Actualiza la configuración de tu aplicación para usar el nombre de la base de datos nueva.
   4. Crea una base de datos nueva y vacía con la codificación predeterminada.

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

2. Administra tus extensiones de PostgreSQL restantes.

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

   Puedes actualizar PostGIS y sus extensiones relacionadas con sus versiones compatibles más recientes de forma manual.

   A veces, la actualización de la versión 2.x de PostGIS puede crear una situación en la que haya objetos de base de datos restantes que no estén asociados con la extensión PostGIS. Esto puede bloquear la operación de actualización. Para obtener información sobre cómo resolver este problema, consulta Corrige una instalación de trama de postgis dañada.

   A veces, la actualización a la versión 3.1.7 o posterior de PostGIS no se puede completar debido a que los objetos usan funciones obsoletas. Esto puede bloquear la operación de actualización. Para verificar el estado de la actualización, ejecuta SELECT PostGIS_full_version();. Si hay advertencias, descarta los objetos que usen las funciones obsoletas y actualiza la extensión de PostGIS a cualquier versión intermedia o posterior. Después de completar estas acciones, vuelve a ejecutar el comando SELECT PostGIS_full_version();. Verifica que no aparezcan advertencias. Luego, continúa con la operación de actualización.

   Para obtener más información sobre cómo actualizar tus extensiones de PostGIS, consulta Actualiza PostGIS. Para problemas relacionados con la actualización de PostGIS, consulta Verifica la versión de tu instancia de PostgreSQL.
3. Administra las marcas de bases de datos personalizadas. Verifica los nombres de las marcas de bases de datos personalizadas que configuraste para tu instancia de PostgreSQL. Para conocer los problemas asociados con estas marcas, consulta Verifica 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 ver si hay problemas de compatibilidad. Asegúrate de que tus bases de datos puedan conectarse entre sí. Verifica el campo datallowconn de cada base de datos a fin de asegurarte de que se permita una conexión. Un valor t significa que está permitido, y un 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, descarta la función pg_stat_activity().

6. Administrar instancias con una gran cantidad de objetos

   El tiempo necesario para una actualización de versión principal in situ depende de la cantidad de objetos de base de datos que haya en la instancia. Las instancias con una gran cantidad de objetos, en especial tablas e índices, pueden experimentar tiempos de actualización considerablemente más largos. Esto aumenta el riesgo de que se agote el tiempo de espera de la operación. Cloud SQL está optimizado para instancias con hasta alrededor de 100,000 relaciones. Si tu instancia supera este límite, la actualización no se bloquea, pero se considera menos confiable y es más probable que tarde un período prolongado o falle después de un tiempo de espera de 6 horas.

   Si tu instancia contiene un recuento de objetos alto, haz lo siguiente antes de iniciar el proceso de actualización principal:

   1. Audita y descarta los objetos sin usar: Identifica y quita las tablas vacías, las tablas que solo se usan para pruebas o cualquier otro objeto de base de datos (esquemas, vistas, funciones) que ya no se necesite.
   2. Optimiza las estructuras de las tablas:
      • Si usas la partición de tablas, una cantidad excesiva de particiones puede contribuir a un recuento de relaciones alto. En este caso, evalúa cómo reducir la cantidad de particiones que usas.
      • Considera migrar los datos históricos o a los que se accede con poca frecuencia a una opción de almacenamiento de datos diferente. Esto podría reducir la cantidad de tablas activas o el tamaño y la complejidad de las existentes.
   3. Ejecuta una prueba de actualización: Realiza una ejecución de prueba de la actualización en una clonación de tu instancia de producción. Esto te permite obtener una estimación realista del tiempo necesario y te ayuda a descubrir posibles problemas. Esta estimación es especialmente crucial para las bases de datos con un alto recuento de objetos.

   Si reduces la cantidad total de objetos y la complejidad, puedes reducir los riesgos y el tiempo de inactividad asociados con las actualizaciones de versiones principales.

7. Administrar instancias con objetos grandes (LOB)

   El proceso de actualización in situ usa la utilidad pg_upgrade de PostgreSQL. Este proceso puede tardar mucho tiempo si la base de datos contiene una gran cantidad de LOB, lo que podría provocar un error de actualización debido al tiempo de espera.

   Para verificar la cantidad de objetos grandes en tu base de datos, conéctate a la instancia de base de datos con un cliente de PostgreSQL, como psql, y ejecuta la siguiente consulta:

       SELECT count(*) AS total_large_objects FROM pg_largeobject_metadata;
     

   Si tu instancia contiene más de 30 millones de LOB, tiene un mayor riesgo de tiempo de espera. En esos casos, considera las siguientes acciones antes de iniciar una actualización:

   1. Limpia los objetos grandes huérfanos: PostgreSQL no quita automáticamente los LOB a los que ya no se hace referencia. Usa la utilidad vacuumlo, que forma parte del módulo contrib, para quitar los LOB huérfanos. Debes ejecutar este comando desde una máquina cliente que pueda conectarse a tu instancia de Cloud SQL.
      • Instala el paquete postgresql-contrib en tu máquina cliente si no tienes vacuumlo.
      • Ejecuta el siguiente comando para realizar una ejecución de prueba y ver qué LOB se borrarían:

                vacuumlo -h INSTANCE_IP -U DATABASE_USER --dry-run DATABASE_NAME
                  

        Reemplaza INSTANCE_IP, DATABASE_USER y DATABASE_NAME por los detalles de tu instancia. Se te pedirá la contraseña del usuario.
      • Ejecuta el siguiente comando para quitar los LOB identificados:

                vacuumlo -h INSTANCE_IP -U DATABASE_USER DATABASE_NAME
                  

        Después de ejecutar vacuumlo, vuelve a verificar el recuento de LOB para confirmar que la limpieza se haya realizado correctamente.
   2. Borra manualmente los objetos grandes: Revisa las políticas de retención de datos de tu aplicación y quita los LOB que ya no sean necesarios.
   3. Aumenta los recursos de la instancia: De forma temporal o permanente, aumenta las CPU virtuales y la memoria de la instancia. Esto proporciona más recursos para el proceso pg_upgrade.
   4. Migra tus datos: Si el recuento de LOB no se puede reducir lo suficiente, considera actualizar mediante la migración de tus datos. Puedes crear un enfoque personalizado con pg_dump y pg_restore específicamente para las LOB. Es posible que los métodos de replicación lógica estándar no admitan por completo los LOB, lo que podría requerir pasos adicionales y tiempo de inactividad para la migración de LOB.
8. Advertencia: El proceso de actualización de la versión principal local para PostgreSQL borra todas las ranuras de replicación lógica existentes en la instancia. Si no vuelves a crear estas ranuras después de que se complete la actualización, se interrumpirán los flujos de replicación.

   Registra la información que necesitarás para volver a crear todas las ranuras de replicación lógica en la instancia, incluidas las ranuras que usa pglogical, la replicación lógica integrada de PostgreSQL, Datastream o cualquier otro consumidor de decodificación lógica.

Limitaciones conocidas

Las siguientes limitaciones afectan a las actualizaciones locales de las versiones principales de Cloud SQL para PostgreSQL:

• No puedes realizar una actualización local de versión principal en una réplica externa.
• La actualización de las instancias que tienen más de 1,000 bases de datos de una versión a otra puede tardar mucho y agotar el tiempo de espera.
• Usa la instrucción select * from pg_largeobject_metadata; para consultar la cantidad de objetos grandes en cada base de datos de PostgreSQL de tu instancia de Cloud SQL. Si el resultado de todas las bases de datos es de más de 10 millones de objetos grandes, la actualización falla. Cloud SQL revierte a la versión anterior de tu base de datos.
• Antes de realizar una actualización de versión principal local a PostgreSQL 16 y versiones posteriores, actualiza la extensión de PostGIS para todas tus bases de datos a la versión 3.4.0. Para PostgreSQL 18, actualiza a la versión 3.6.0 de PostGIS.
• Antes de realizar una actualización de versión principal local a PostgreSQL 17, actualiza la extensión rdkit para todas tus bases de datos a la versión 4.6.1.
• Antes de realizar una actualización de versión principal local a PostgreSQL 16, 17 o 18, actualiza la extensión pg_squeeze para 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 de PostGIS. Por lo tanto, para realizar una actualización de versión principal local a PostgreSQL 16 y versiones posteriores, primero debes actualizar a una versión intermedia de PostgreSQL (versiones 13, 14 o 15).

• Si instalas la extensión pg_ivm para tu instancia, no podrás realizar una actualización de versión principal. Para solucionar este problema, desinstala esta extensión y, luego, realiza la actualización. Para obtener más información sobre las extensiones, consulta Configura extensiones de PostgreSQL.

• Si habilitas las marcas vacuum_defer_cleanup_age y force_parallel_mode, no podrás realizar una actualización de versión principal. Para solucionar este problema, borra estas marcas y, luego, realiza la actualización. Para obtener más información sobre las marcas, incluido cómo borrarlas, consulta Configura marcas de base de datos.

  Nota: En PostgreSQL 16 y versiones posteriores, la marca vacuum_defer_cleanup_age está obsoleta y la marca force_parallel_mode cambió de nombre a debug_parallel_query.

Evalúa la preparación para la actualización de tu instancia

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

La verificación previa confirma que tu instancia se puede actualizar o enumera los problemas que debes corregir primero y sus soluciones. Estos problemas pueden deberse a extensiones incompatibles, dependencias no admitidas o problemas de formato de datos.

Cloud SQL puede ejecutar el proceso de verificación previa en paralelo con tu carga de trabajo. Ejecutar la verificación previa antes de realizar una actualización de versión principal puede ayudar a evitar que falle la actualización.

Cuando ejecutas la verificación previa, ocurre una de las siguientes situaciones:

• No se encontraron problemas: la verificación previa finalizó correctamente y no se encontraron problemas.
• Se encontraron problemas: La verificación previa finalizó correctamente, pero se encontraron errores que bloquearán la actualización. Los problemas se deben resolver antes de la actualización.
• Se encontraron advertencias: La verificación previa finalizó correctamente y se encontraron advertencias. Revisa las advertencias. Te recomendamos que resuelvas cualquier problema antes de continuar con la actualización.

Según los resultados de la verificación previa, puedes continuar con la actualización o corregir los problemas identificados antes de actualizar.

Limitaciones

Cuando uses la verificación previa de la actualización de la versión principal, ten en cuenta las siguientes limitaciones:

• El estado de la instancia debe establecerse en RUNNING.

• La instancia debe ser una instancia principal. La verificación previa no admite instancias de réplica.

• La instancia no debe tener ninguna operación de bloqueo pendiente. Si hay una operación de bloqueo pendiente, la verificación previa genera 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 verificació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 verificación previa falle o muestre errores. Te recomendamos que ejecutes la verificación previa cuando la carga de la base de datos sea baja.

Antes de comenzar

• Asegúrate de que la API de Cloud SQL Admin esté habilitada para tu instancia.
• Confirma que tienes el permiso de IAM cloudsql.instances.preCheckMajorVersionUpgrade.

Realiza la verificación previa

Para realizar la verificación previa de la actualización de la versión principal, haz lo siguiente:

Console

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

   Ir a Instancias de Cloud SQL

2. Busca la instancia en la que deseas realizar la verificación previa. Para abrir la página de Descripción general de la instancia, haz clic en su nombre.
3. Haz clic en Editar.
4. En Información de la instancia, haz clic en Validar actualización.
5. En el cuadro de diálogo Validar actualización, selecciona la versión de la base de datos a la que deseas actualizar y, luego, haz clic en Validar.

   Comienza la operación de verificación previa. Supervisa el estado de la operación de verificación previa en el panel lateral de notificaciones Operaciones.

6. Una vez que se complete la operación de verificación previa, se abrirá una ventana nueva llamada Validar los resultados de la actualización. Esta ventana contiene los resultados del proceso de verificación previa. Los resultados pueden ser uno de los siguientes:
   • Si la operación de verificación previa no contiene errores, haz clic en Actualizar página para comenzar el proceso de actualización.
   • Si la operación de verificación previa contiene mensajes info, revisa los hallazgos. Cuando tengas todo listo para actualizar, haz clic en Página de actualización para comenzar el proceso.
   • Si la verificación previa contiene mensajes de warning, revisa los hallazgos. Te recomendamos que resuelvas estas advertencias antes de continuar con la actualización, pero estos mensajes no bloquean el proceso de actualización.
   • Si la operación de verificación previa contiene errors, revisa los hallazgos. Resuelve los errores y, luego, vuelve a ejecutar el proceso de verificación previa. Se deben resolver todos los errores antes de comenzar el proceso de actualización.

gcloud

1. Usa gcloud sql instances pre-check-major-version-upgrade para ejecutar la verificación previa:

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

   Reemplaza lo siguiente:

   • INSTANCE_NAME: El nombre de la instancia.
   • TARGET_DATABASE_VERSION: Es la versión principal a la que deseas actualizar tu instancia. Para encontrar la versión de la base de datos, consulta Planifica una actualización.
   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .

   Opcional: Usa la marca --async para ejecutar el comando de forma asíncrona.

2. Si usas la marca --async para ejecutar el comando pre-check-major-version-upgrade de forma asíncrona, haz lo siguiente:

   1. Obtén el nombre de la operación de verificación previa:

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

      gcloud sql operations list --instance=INSTANCE_NAME

      Reemplaza lo siguiente:

      • INSTANCE_NAME: El nombre de la instancia.

   2. Supervisa el estado de la verificación previa.

      Usa el comando gcloud sql operations describe:

      gcloud sql operations describe OPERATION_NAME

      Reemplaza lo siguiente:

      • OPERATION_NAME: Es el nombre de la operación de verificación previa que se recuperó en el paso anterior.
3. Si no ejecutas el comando pre-check-major-version-upgrade de forma asíncrona, espera a que se complete la verificación previa para ver los resultados.

REST v1

1. Ejecuta la verificación previa.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • PROJECT_ID: el ID del proyecto
   • INSTANCE_ID: El ID de la instancia
   • TARGET_DATABASE_VERSION: Es la versión principal a la que se actualizará. Para encontrar una lista de las versiones de bases de datos disponibles, consulta Planifica una actualización.

   Método HTTP y URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

   Cuerpo JSON de la solicitud:

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

   Para enviar tu solicitud, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
     "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 verificación previa.

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

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

   Reemplaza lo siguiente:

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

3. Supervisa el estado de la verificación previa.

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

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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • OPERATION_NAME: Es el nombre de la operación de verificación previa que se recuperó en el paso anterior.

REST v1beta4

1. Ejecuta la verificación previa.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • PROJECT_ID: el ID del proyecto
   • INSTANCE_ID: El ID de la instancia
   • TARGET_DATABASE_VERSION: Es la versión principal a la que se actualizará. Para encontrar una lista de las versiones de bases de datos disponibles, consulta Planifica 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, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade"

   PowerShell (Windows)

   Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade" | Select-Object -Expand Content

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
     "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 verificación previa.

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

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

   Reemplaza lo siguiente:

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

3. Supervisa el estado de la verificación previa.

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

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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • operation_name: Es el nombre de la operación de verificación previa que se recuperó en el paso anterior.

Revisa los resultados de la verificación previa

Una vez que finaliza la verificación previa, la instancia está lista para la actualización o tiene problemas que requieren tu atención.

Listo para actualizar

Si la verificación previa finaliza correctamente y el array preCheckResponse está vacío, significa que no se encontraron problemas ni advertencias. La instancia está lista para la actualización de la versión principal. Para continuar, consulta Realiza la actualización de la versión principal.

No está listo para la actualización

Si la verificación previa se ejecutó correctamente y el array preCheckResponse contiene problemas, tu instancia no está lista para la actualización y requiere atención. Los problemas identificados pueden bloquear o no la actualización. Estos problemas se indican en el preCheckResponse con los siguientes tipos de mensajes:

Tipo	Descripción	¿Quieres bloquear la actualización?
INFO	Es un mensaje informativo.	No
WARNING	Se encontró un problema potencial, pero no bloquea la actualización. Cloud SQL recomienda revisar y abordar la advertencia antes de actualizar para garantizar la compatibilidad total.	No
ERROR	Se encontró un problema crítico que bloquea la actualización. Estos problemas pueden hacer que la actualización falle. Debes resolverlos antes de actualizar tu instancia.	Sí

Si tu instancia solo tiene mensajes 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 de ERROR, debes resolver estos problemas antes de actualizar.

Cada tipo de problema incluye un campo message y un campo actions_required. Revisa cada problema para comprender su tipo y cómo resolverlo. Para obtener más información sobre los problemas comunes y sus soluciones, consulta Errores comunes de la verificación previa de la actualización de la versión principal.

Después de resolver los problemas, vuelve a ejecutar la verificación previa para confirmar que la instancia esté lista para la actualización. Luego, continúa con la actualización de la instancia una vez que se complete la verificación previa.

Realiza la actualización de la versión principal

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

Actualiza 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. Verifica la configuración de tu instancia para asegurarte de que sea compatible con una actualización.
2. Después de que Cloud SQL verifica la configuración, hace que la instancia no esté disponible.
3. Realiza una copia de seguridad previa a la actualización.
4. Realiza la actualización en la instancia.
5. Hace que tu instancia esté disponible.
6. Realiza una copia de seguridad posterior a la actualización.

Nota: Si usas réplicas de lectura y eliges no incluir réplicas con la actualización de la versión principal, debes actualizar las réplicas de lectura antes de actualizar la instancia principal. Después de actualizar una réplica, no puedes revertir su versión de la base de datos. Las bases de datos replicadas de una réplica actualizada solo están disponibles después de actualizar la instancia principal.

Console

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

   Ir a Instancias de Cloud SQL

2. Para abrir la página de Descripción general 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 deseas ir a la página de actualización.
5. En la página Elige una versión para 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 base de datos disponibles.
6. Haz clic en Continuar.
7. En el cuadro ID de instancia, ingresa el nombre de la instancia y, luego, haz clic en el botón Iniciar actualización.

La operación tarda varios minutos en completarse.

Verifica que la versión principal de la base de datos actualizada aparezca debajo del nombre de la instancia en la página Descripción general 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, reemplaza lo siguiente:

   • INSTANCE_NAME: El nombre de la instancia
   • DATABASE_VERSION: La enumeración de la versión principal de la base de datos, que debe ser posterior que 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 esta enumeración como el primer paso del plan de actualización. Si necesitas una lista completa de las enumeraciones 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 indica que la operación está tardando más de lo esperado. Puedes ignorar este mensaje o ejecutar el comando gcloud sql operations wait para descartarlo.

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, reemplaza lo siguiente: * INSTANCE_NAME: el nombre de la instancia.

   gcloud sql operations list --instance=INSTANCE_NAME

3. Supervisa el estado de la actualización.

   Usa el comando gcloud sql operations describe.

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

   gcloud sql operations describe OPERATION

REST v1

1. Inicia la actualización local.

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

   Antes de usar cualquiera de los datos de la solicitud, reemplaza 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
   }

   Reemplaza DATABASE_VERSION por la enumeración de la versión principal de la base de datos, que debe ser posterior que 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 esta enumeración como el primer paso del plan de actualización. Si necesitas una lista completa de las 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 reemplazar PROJECT_ID por el ID del proyecto.

   Método HTTP y URL:

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

3. Supervisa el estado de la actualización.

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

   • PROJECT_ID: El ID del proyecto.
   • OPERATION_NAME: El nombre de la operación de actualización que se recuperó 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 principal de la base de datos con Terraform, debes establecer el argumento database_version en la definición del recurso google_sql_database_instance en la versión principal de destino. Debes usar el proveedor de Terraform para la versión 4.34.0 o posterior de Google Cloud .

En los siguientes ejemplos, se muestra una configuración básica de google_sql_database_instance. Para actualizar la versión principal, establece el argumento database_version en la versión principal correspondiente.

resource "google_sql_database_instance" "default" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
}

Realiza los siguientes cambios en los argumentos de Terraform:

• database_version: Configura este valor en la versión principal de destino para la actualización.
• deletion_protection: Define la protección de Terraform a nivel de raíz contra la eliminación de instancias.
  • true: Impide que Terraform destruya la instancia. Se bloquea cualquier operación de Terraform que planee borrar este recurso.
  • false: Permite que Terraform borre la instancia.

Nota: Esto es diferente de la protección contra eliminaciones a nivel de GCP (settings.deletion_protection_enabled).

Revisa el plan de Terraform

Antes de aplicar cualquier cambio, siempre ejecuta terraform plan y, luego, inspecciona con cuidado el resultado. Los símbolos junto al nombre del recurso indican cómo Terraform aplicará los cambios:

• ~ Actualización in situ: Este símbolo indica que Terraform modificará la instancia existente. Este es el resultado esperado y seguro para una actualización in situ de versión principal cuando se cambia database_version.
• +/- Recrear (reemplazo forzado): Este símbolo significa que Terraform planea destruir la instancia actual y crear una nueva.
  Advertencia: Si aparece +/- junto a tu recurso google_sql_database_instance después de cambiar database_version, no continúes con terraform apply. Esta acción borrará tu instancia y todos sus datos.
  • Si deletion_protection se establece en true, Terraform generará un error y bloqueará este reemplazo peligroso. Tendrías que establecer de forma explícita deletion_protection = false en tu configuración y volver a ejecutar terraform apply para actualizar el estado, antes de que un apply posterior permita la destrucción y la recreación.
  • Si deletion_protection se establece en false, terraform apply continuará con la pérdida de datos.

  Las instancias se pueden programar para su reemplazo (borrado y recreación) debido a un cambio de configuración o a una ruta de actualización no admitida para la modificación in situ. Si descubres que una instancia está programada para borrarse y volver a crearse, debes detenerla de inmediato y, antes de que continúe, investigar el motivo del reemplazo programado.

Después de revisar el resultado de terraform plan para asegurarte de que solo indique una actualización local (~) para el cambio de versión de la base de datos, aplica la configuración

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud , completa los pasos de las siguientes secciones.

Prepara Cloud Shell

1. Inicia Cloud Shell

2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

   Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

Prepara 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 dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

   Copia el código de muestra en el main.tf recién creado.

   De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
4. Guarda los cambios.
5. Inicializa Terraform. Solo debes hacerlo una vez por directorio.

   terraform init

   De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

   terraform init -upgrade

Aplica los cambios

1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:

   terraform plan

   Corrige la configuración según sea necesario.

2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:

   terraform apply

   Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud , navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Nota: Por lo general, las muestras de Terraform suponen que las APIs necesarias están habilitadas en tu proyecto de Google Cloud .

Cuando envías una solicitud de actualización local, Cloud SQL primero realiza una verificació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á con un mensaje que sugiere cómo abordar el problema. Consulta también Soluciona problemas de una actualización de versión principal.

Nota: Cloud SQL aprovisiona tu instancia de forma automática en la versión secundaria predeterminada.

Incluye 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 entre regiones y las réplicas en cascada.

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

1. Verifica la configuración de tu instancia principal y las réplicas para garantizar que sean compatibles con una actualización.
2. Hace que tu instancia principal no esté disponible.
3. Realiza una copia de seguridad previa a la actualización de la instancia principal.
4. Detiene la replicación para 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, esta vuelve a estar disponible y reinicia la replicación.
7. Cloud SQL realiza una copia de seguridad posterior a la actualización de la instancia principal.
8. Cloud SQL procede a actualizar todas las réplicas.

Incluso si falla 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 la consola deGoogle Cloud ni Terraform. Solo puedes usar la gcloud CLI o la API de Cloud SQL Admin.

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, reemplaza lo siguiente:

   • INSTANCE_NAME: Es el nombre de la instancia principal.
   • DATABASE_VERSION: Es la enumeración 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 esta enumeración como el primer paso del plan de actualización. Si necesitas una lista completa de las enumeraciones 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 indica que la operación está tardando más de lo esperado. Puedes ignorar este mensaje o ejecutar el comando gcloud sql operations wait para descartarlo. La actualización de las réplicas puede tardar varios minutos en completarse. Para verificar el estado de la actualización, haz lo siguiente:

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, reemplaza la variable INSTANCE_NAME por el nombre de la instancia.

   gcloud sql operations list --instance=INSTANCE_NAME

3. Supervisa el estado de la actualización.

   Usa el comando gcloud sql operations describe.

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

   gcloud sql operations describe OPERATION

REST

1. Inicia la actualización local.

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

   Antes de usar cualquiera de los datos de la solicitud, reemplaza 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
   }

   • Reemplaza DATABASE_VERSION por la enumeración de la versión principal de la base de datos, que debe ser posterior que 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 esta enumeración como el primer paso del plan de actualización. Si necesitas una lista completa de las 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 reemplazar PROJECT_ID por el ID del proyecto.

   Método HTTP y URL:

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

3. Supervisa el estado de la actualización.

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

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

   Método HTTP y URL:

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

Copias de seguridad automáticas de actualización

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

• La primera copia de seguridad de actualización es la copia de seguridad previa a la actualización, que se realiza inmediatamente antes de comenzar la actualización. Puedes usar esta copia de seguridad para restablecer la instancia de la base de datos a su estado en la versión anterior.
• La segunda copia de seguridad es la copia de seguridad posterior a la actualización, que se realiza inmediatamente después de que se permiten nuevas operaciones de escritura en la instancia de la base de datos actualizada.

Cuando ves tu lista de copias de seguridad, las copias de seguridad de actualización se enumeran con el tipo On-demand. Las copias de seguridad de actualización están etiquetadas para que puedas identificarlas con facilidad. Por ejemplo, si actualizas de PostgreSQL 14 a PostgreSQL 15, tu copia de seguridad previa a la actualización se etiqueta como Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. y tu copia de seguridad posterior a la actualización se etiqueta como Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

Al igual que con otras copias de seguridad bajo demanda, las copias de seguridad de actualización persisten hasta que las borres o borres la instancia. Si tienes habilitada la PITR, no puedes borrar las copias de seguridad de actualización mientras se encuentran en el período de retención. Si necesitas borrar tus copias de seguridad de actualización, debes inhabilitar la PITR o esperar hasta que las copias de seguridad de actualización ya no estén en el período de retención.

Cancela la actualización de la versión principal

Puedes cancelar una operación de actualización de versión principal local, pero solo mientras la instancia realiza la actualización de versión real.

Nota: Si usas réplicas de lectura y eliges incluir réplicas con la actualización de la versión principal, no podrás cancelar la actualización de la versión principal.

Período de cancelación

Una actualización de la versión principal implica una secuencia de pasos. Solo puedes cancelar durante la fase de actualización principal.

1. Inicialización: Cloud SQL prepara la instancia y sus recursos. No puedes cancelar durante esta fase.

2. Fase de actualización principal: Cloud SQL actualiza de forma activa tus datos a la nueva versión principal. Solo puedes cancelar durante esta fase.

3. Finalización: La instancia completa la actualización y realiza las verificaciones finales.

Para determinar cuándo tu instancia ingresó a la fase cancelable, verifica la disponibilidad de los registros de actualización. Los registros de actualización están disponibles en projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log

Cuando las entradas de registro comienzan a aparecer en este archivo de registro, la fase de actualización principal está activa y puedes cancelar la operación.

Realizar la cancelación

Para cancelar una actualización de versión principal in situ, necesitas el ID de la operación. Debes especificar este ID en el comando gcloud o de la API de REST para que Cloud SQL sepa qué operación cancelar.

Puedes usar los comandos de la API de REST o de gcloud para cancelar una operación de actualización de versión principal.

gcloud

1. Obtén el ID de la operación de actualización.

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

   gcloud sql operations list --instance=INSTANCE_NAME
   

   Reemplaza lo siguiente:

   • INSTANCE_NAME: El nombre de la instancia.

2. Cancela la actualización.

   Usa el comando gcloud sql operations cancel:

   gcloud sql operations cancel OPERATION_ID
   

   Reemplaza lo siguiente:

   • OPERATION_ID: Es el ID de la operación que se recuperó en el paso anterior.

3. Verifica el estado cancelado.

   Usa el comando gcloud sql operations describe:

   gcloud sql operations describe OPERATION_ID
   

   Reemplaza lo siguiente:

   • OPERATION_ID: Es el ID de operación que se recuperó en el primer paso.

REST v1

1. Obtén el ID de la operación de actualización.

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

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

   Reemplaza lo siguiente:

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

2. Cancela la actualización.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • OPERATION_ID: Es el ID de la operación que se recuperó en el paso anterior.

   Método HTTP y URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel

   Para enviar tu solicitud, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel"

   PowerShell (Windows)

   Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   Ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID/cancel" | Select-Object -Expand Content

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   Respuesta

   {}
   

   Esta llamada a la API de REST no muestra ninguna respuesta.

3. Verifica el estado cancelado.

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

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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • OPERATION_ID: Es el ID de operación que se recuperó en el primer paso.

REST v1beta4

1. Obtén el ID de la operación de actualización.

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

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

   Reemplaza lo siguiente:

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

2. Cancela la actualización.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
• OPERATION_ID: Es el ID de la operación que se recuperó en el paso anterior.

Método HTTP y URL:

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID/cancel" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Respuesta

{}

Esta llamada a la API de REST no muestra ninguna respuesta.

1. Verifica el estado cancelado.

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

   GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
   • OPERATION_ID: Es el ID de operación que se recuperó en el primer paso.

Si se acepta tu solicitud de cancelación, Cloud SQL detiene el proceso de actualización en curso y comienza a revertir la instancia a su estado original.

Nota: La cancelación no es instantánea. Activar una cancelación no restablece de inmediato el acceso a tu instancia. La instancia permanece no disponible mientras Cloud SQL realiza los pasos de reversión necesarios para devolver el sistema a su estado anterior a la actualización.

Cómo solucionar problemas relacionados con las cancelaciones

Problema	Soluciona problemas
Mensaje de error: The operation OPERATION_ID cannot be canceled at the moment. Please retry in approximately 5-10 minutes	La actualización aún no llegó al período de cancelación. Espera unos minutos y vuelve a intentarlo.
Mensaje de error: The operation OPERATION_ID cannot be cancelled as it has passed the cancellable state. The operation is in its final stage and should complete soon.	El proceso de actualización superó el período de cancelación. Ya no es posible cancelar la actualización, que debería finalizar en breve.
Mensaje de error: You can't cancel operation OPERATION_ID because it isn't in progress.	La operación ya finalizó, ya sea de forma correcta o con un error, y ya no se puede cancelar.
Mensajes de error: You can't cancel operation OPERATION_ID because Cloud SQL doesn't support the cancellation of this OPERATION_TYPE operation. The operation OPERATION_ID cannot be cancelled.	Por lo general, este error ocurre cuando pasas el OPERATION_ID incorrecto al comando de cancelación, específicamente, el ID de un tipo de operación que no admite la cancelación. Verifica que estés usando el OPERATION_ID asociado con la actualización de la versión principal de la base de datos in situ que quieres cancelar.

Si la cancelación falló después de que se aceptó la solicitud de cancelación, debes restablecer tu instancia desde la copia de seguridad previa a la actualización que se realizó automáticamente al comienzo del proceso. Si los problemas persisten, comunícate con el equipo de asistencia deGoogle Cloud .

Completa la actualización de la versión principal

Luego de que termines de actualizar la instancia principal, realiza los siguientes pasos para completar la actualización:

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

   Ejecuta ANALYZE en la instancia principal para actualizar las estadísticas del sistema después de la actualización. Las estadísticas precisas garantizan que el planificador de consultas de PostgreSQL procese las consultas de manera óptima. Las estadísticas faltantes pueden generar planes de consultas incorrectos, lo que puede degradar el rendimiento y consumir una memoria excesiva.

2. Realiza pruebas de aceptación.

   Ejecuta pruebas para asegurarte de que el sistema actualizado funcione como se espera.

3. Para evitar la interrupción de los flujos de replicación, vuelve a crear las ranuras de replicación lógica de tu instancia con la información que registraste antes de comenzar la actualización (consulta Prepárate para una actualización de versión principal).

Soluciona problemas de una actualización de versión principal

Cloud SQL muestra 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 versión nueva.

Si tu solicitud de actualización falla, verifica su sintaxis. Si la solicitud tiene una estructura válida, intenta con las siguientes sugerencias.

Ver registros de errores

Si se produce algún problema con una solicitud de actualización válida, Cloud SQL publica 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 que te ayuda a identificarla con el error de actualización. Busca estos errores de actualización y resuélvelos.

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

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

   Ir a Instancias de Cloud SQL

2. Para abrir la página de Descripción general de una instancia, haz clic en su nombre.

3. En el panel Operaciones y registros de la página Descripción general de la instancia, haz clic en el vínculo Ver registros de errores de PostgreSQL.

   Se abrirá la página Explorador de registros.

4. Visualiza los registros de la siguiente manera:

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

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

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

   por 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 de 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"

   Puedes revisar todos los registros informados en un período determinado o filtrarlos por gravedad. Una opción común para solucionar problemas podría incluir la selección de los siguientes filtros:

   • Emergencia
   • Alert
   • Critical
   • Error

Las entradas de registro con el prefijo pg_upgrade_dump indican que se produjo 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 enumerar otros errores que deberás resolver antes de intentar realizar la actualización de nuevo.

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

Estos son algunos nombres de archivos que pueden contener errores de resolución:

• tables_with_oids.txt:: Este archivo contiene tablas que se enumeran con identificadores de objetos (OID). Borra las tablas o modifícalas para que no usen OID.
• tables_using_composite.txt:: Este archivo contiene tablas que se enumeran mediante tipos compuestos definidos por el sistema. Borra las tablas o modifícalas para que no usen estos tipos compuestos.
• tables_using_unknown.txt:: Este archivo contiene tablas que se enumeran mediante el tipo de datos UNKNOWN. Borra 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 mediante el tipo de datos SQL_IDENTIFIER. Borra las tablas o modifícalas para que no usen este tipo de datos.
• tables_using_reg.txt:: Este archivo contiene tablas que se enumeran mediante el tipo de datos REG* (por ejemplo, REGCOLLATION o REGNAMESPACE). Borra las tablas o modifícalas para que no usen este tipo de datos.
• postfix_ops.txt:: Este archivo contiene tablas que se enumeran mediante operadores posfix (unario derecho). Borra las tablas o modifícalas para que no usen estos operadores.

Verifica la memoria

Si la instancia tiene memoria compartida insuficiente, es posible que veas este mensaje de error: ERROR: out of shared memory. Este error es más probable que suceda si tienes más de 10,000 tablas.

Antes de intentar una actualización, establece el valor de la marca max_locks_per_transaction aproximadamente el doble de la cantidad de tablas en la instancia. La instancia se reinicia cuando cambias el valor de esta marca.

Verifica la capacidad de las conexiones

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

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

Verifica si hay una referencia de columna ambigua

Cloud SQL realiza automáticamente una verificació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 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 generará un error, como ERROR: column reference "column_name" is ambiguous.

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

Ejemplo de mensaje de error

• Para 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)

• Para 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, haz lo siguiente: 1. Identifica las vistas que se indican en el mensaje de error de la verificación previa a la actualización.

1. Descarta estas vistas con DROP VIEW view_name;.

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

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

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

Verifica si hay SRF en las instrucciones CASE

Si actualizas tu instancia desde PostgreSQL 9.6 y usas funciones de devolución de conjuntos en tus declaraciones 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 sentencias CASE.

Para resolver este problema y actualizar tu instancia correctamente, asegúrate de que las declaraciones CASE que usan funciones que devuelven conjuntos se modifiquen para evitar su uso antes de volver a intentar la actualización. Algunos SRF de uso frecuente son los siguientes:

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

Verifica las vistas creadas en las transmisiones personalizadas

Si tienes una vista creada en una conversión de tipos personalizada, aparecerá un mensaje de error similar al siguiente: ERROR: cannot cast type <type_1> to <type_2>. Este problema se produce debido a problemas de permisos en las transmisiones creadas de forma personalizada.

Para resolver este problema, actualiza tu instancia a [PostgreSQL version].R20240910.01_02

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

Verifica la propiedad del activador de eventos

En Cloud SQL, todos los activadores de eventos deben pertenecer a un usuario con el rol cloudsqlsuperuser. Cloud SQL realiza una verificación previa a la actualización para validar la propiedad de todos los activadores de eventos. Si un activador de eventos pertenece a un usuario que no tiene el rol cloudsqlsuperuser, el proceso de actualización se detiene 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 resolver este problema, cambia el propietario del activador de eventos a un usuario que tenga el rol cloudsqlsuperuser, como postgres, o bien otorga el rol cloudsqlsuperuser al propietario actual.

Para identificar los activadores de eventos con propietarios que no tienen el rol requerido, 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');

En los resultados, se muestra cualquier activador de eventos con un propietario que no tenga el rol de cloudsqlsuperuser.

Verifica las columnas generadas a partir de tablas no registradas

Si tienes una tabla no registrada que tiene columnas generadas, es posible que veas el mensaje de error ERROR: unexpected request for new relfilenumber in binary upgrade mode. Este problema se produce debido a discrepancias en las características de persistencia entre las tablas y sus secuencias para las columnas generadas.

Para solucionar este problema, haz lo siguiente:

1. Descarta las tablas no registradas: si es posible, descarta las tablas no registradas que estén vinculadas a columnas generadas. Asegúrate de que la pérdida de datos se pueda mitigar de forma segura antes de continuar.
2. Convierte en tablas permanentes: Convierte de forma temporal las tablas sin registro en tablas permanentes con los siguientes pasos:
   1. Convierte la tabla en una tabla registrada ALTER TABLE SET LOGGED;
   2. Realiza la actualización de la versión principal
   3. Vuelve a convertir la tabla en una tabla sin registro ALTER TABLE SET UNLOGGED

Puedes identificar todas esas 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;

Verifica las marcas personalizadas para tu instancia de PostgreSQL

Si actualizas a una instancia de PostgreSQL, versión 14 o superior, verifica los nombres de las marcas de bases de datos personalizadas que configuraste para la instancia. Esto se debe a que PostgreSQL colocó restricciones adicionales en los nombres permitidos para parámetros personalizados.

El primer carácter de una marca de base de datos personalizada debe ser alfabético (una letra mayúscula o minúscula). Todos los caracteres posteriores pueden ser alfanuméricos, el carácter especial de guion bajo (_) o el carácter especial del signo del dólar ($).

Cómo quitar extensiones

Si actualizas tu instancia de Cloud SQL, es posible que veas este mensaje de error: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Para resolver el problema, sigue estos pasos:

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

La operación de MVU se ejecuta durante más tiempo

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

• Operación de verificación previa: Devuelve un error de tiempo de espera si no finaliza en un plazo de tres horas.
• Operación de actualización: Muestra un error de tiempo de espera si no finaliza en seis horas.

Si la instancia tiene una operación MAJOR_VERSION_UPGRADE en curso durante un período más largo de lo esperado, investiga los registros de errores de PostgreSQL. Esto podría deberse a problemas comunes, como los siguientes:

• Una gran cantidad de tablas, vistas o índices
• Recursos insuficientes, como CPU o memoria
• Transacciones importantes que bloquean el cierre de las bases de datos para que comience el proceso de actualización. Puedes usar la consola de Google Cloud para verificar los procesos actuales.

Errores comunes de la verificación previa de la actualización de la versión principal

Los problemas que se encuentran en la verificació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 en 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: Son problemas con tu base de datos o datos que podrían ocurrir después de una actualización de versión principal. Esto incluye diferencias en las estructuras de la base de datos, los tipos de datos, la codificación, la intercalación o los cambios en el catálogo del sistema específicos de la versión nueva.

Extensiones incompatibles

En la siguiente tabla, se enumeran los errores comunes relacionados con las extensiones incompatibles que puede encontrar la verificación previa de la actualización de la versión principal:

Tipo	Ejemplo con errores	Solución
Extensión no compatible 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 usan 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 destino de Cloud SQL para PostgreSQL. Para conocer las versiones compatibles, consulta Configura Cloud SQL para PostgreSQL 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 de trama 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 quita o cambia cualquier objeto de la base de datos que use 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 compatibles

En la siguiente tabla, se enumeran los errores comunes relacionados con las dependencias no compatibles que puede encontrar la verificación previa de la actualización de la versión principal:

Tipo	Ejemplo con errores	Solució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 con psql o Cloud SQL Studio y cambia el propietario del activador a un usuario postgres.
Sentencias preparadas no confirmadas	Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact)	Confirma o revierte la sentencia preparada.
Marcas obsoletas	Your installation contains deprecated flags for the new version . These flags must be removed before attempting an upgrade: (database: %s, Flag name: %s)	Quita la marca de base de datos de la configuración de la instancia.

Incompatibilidades de la base de datos

En la siguiente tabla, se enumeran los errores comunes relacionados con las incompatibilidades de formato de datos que puede encontrar la verificación previa de la actualización de la versión principal:

Tipo	Ejemplo con errores	Solució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)	Quita 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 que se quitó	Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ...	Conviértelos en TEXT, timestamptz o en otro tipo de datos adecuado.
Formato interno de ​​aclitem	Please remove the following usages of 'aclitem' data types before attempting an upgrade: ...	Deja de usar aclitem en las definiciones de 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 usar 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 postfix personalizados. Es posible que debas volver a escribir tu código para usar operadores de prefijo o llamadas a funciones en su lugar.
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 quitar 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)	Quita la conversión de codificación definida por el usuario. Es posible que debas volver a crearla después de la actualización con una firma que funcione con la versión nueva.
Verifica si hay una referencia de columna ambigua	Cloud SQL verifica automáticamente las vistas definidas por el usuario que dependen de las vistas del catálogo del sistema. La estructura de columnas de estas vistas del catálogo del sistema puede cambiar entre las 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 quítalas con el comando DROP VIEW. Después de la actualización, vuelve a crear las vistas.
Tablas no registradas 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 en LOGGED o quitarla con el comando DROP TABLE. Vuelve a crear la tabla después de la actualización.
Corrige 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;.

Restablece la instancia principal a la versión principal anterior

Si el sistema de la base de datos actualizada no funciona como se espera, es posible que debas restablecer la instancia principal a la versión anterior. Para ello, restablece tu copia de seguridad previa a la actualización en una instancia de recuperación de Cloud SQL, que es una instancia nueva que ejecuta la versión previa a la actualización.

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

1. Identifica la copia de seguridad previa a la actualización.

   Consulta Copias de seguridad automáticas de actualización.

2. Crea una instancia de recuperación.

   Crea una nueva instancia de Cloud SQL con la versión principal que ejecutaba Cloud SQL cuando se hizo la copia de seguridad previa a la actualización. Establece las mismas marcas y la configuración de instancia que usa la instancia original.

3. Restablece la copia de seguridad previa a la actualización.

   Restablece la copia de seguridad previa a la actualización en la instancia de recuperación. Esto puede tardar varios minutos en completarse.

4. Agrega las réplicas de lectura.

   Si usas réplicas de lectura, agrégalas de forma individual.

5. Conecta tu aplicación.

   Después de recuperar el sistema de la base de datos, actualiza la aplicación con detalles sobre la instancia de recuperación y sus réplicas de lectura. Puedes reanudar la entrega de tráfico en la versión previa a la actualización de tu base de datos.

Preguntas frecuentes

Las siguientes preguntas pueden surgir cuando actualizas la versión principal de la base de datos.

¿Mi instancia no está disponible durante una actualización?

Sí. Tu instancia permanece no disponible durante un período mientras Cloud SQL realiza la actualización.

¿Cuánto demora una actualización?

La actualización de una sola instancia suele tomar menos de 10 minutos. Si la configuración de tu instancia tiene una pequeña cantidad de CPU virtuales o memoria, es posible que la actualización tarde más tiempo.

Si tu instancia aloja demasiadas bases de datos o tablas, o tus bases de datos son muy grandes, es posible que la actualización tarde horas o incluso se agote el tiempo de espera porque el tiempo total de actualización corresponde a la cantidad de objetos en tus bases de datos. Si tienes que actualizar múltiples instancias, el tiempo de actualización aumenta de forma proporcional. Si incluyes réplicas en la actualización, la operación puede tardar hasta una hora en completarse, según la cantidad de réplicas que tenga la instancia principal.

¿Puedo supervisar cada paso de mi proceso de actualización?

Si bien Cloud SQL te permite supervisar si una operación de actualización aún está en curso, no puedes realizar un seguimiento de los pasos individuales en cada actualización.

¿Puedo cancelar la actualización después de iniciarla?

Sí, pero solo en condiciones específicas. Puedes cancelar la operación durante la fase de actualización principal. Consulta Cancela la actualización de la versión principal para obtener detalles sobre cómo identificar la ventana cancelable. Además, no se admite la cancelación si incluyes réplicas de lectura con la instancia principal. Para conservar la capacidad de cancelar, debes actualizar sin incluir réplicas de lectura.

¿Qué sucede con mi configuración durante una actualización?

Cuando realizas una actualización local de versión principal, Cloud SQL conserva la configuración de tu base de datos, incluidos el nombre de la instancia, la dirección IP, los valores de marca configurados de manera explícita y los datos del usuario. Sin embargo, el valor predeterminado de las variables de sistema puede cambiar. Por ejemplo, el valor predeterminado de la marca password_encryption en PostgreSQL 13 y versiones anteriores es md5. Cuando actualizas a PostgreSQL 14, el valor predeterminado de esta marca cambia a scram-sha-256.

Para obtener más información, consulta Configura marcas de base de datos. Si una marca o un valor de marca determinados ya no son compatibles con tu versión de destino, Cloud SQL quita automáticamente la marca durante la actualización, siempre que no la hayas establecido tú. Si configuraste una marca que no es compatible con la versión de destino, debes quitarla antes de actualizar.

¿Qué sigue?

• Aprende sobre las opciones para conectarse a una instancia.
• Aprende a importar y exportar datos.
• Obtén más información para configurar marcas de base de datos.