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

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 strings 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. 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.
      2. 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 subartículo muestra 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.

    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:

    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"
}

    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:

    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"
}

    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

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

    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.

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

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

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. Cambia el nombre de la base de datos.
    3. Actualiza la configuración de la aplicación para usar el nuevo nombre de la base de datos.
    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 réplicas de lectura.

    Cloud SQL para PostgreSQL no admite la replicación entre versiones, lo que significa que no puedes actualizar la instancia principal mientras la instancia se replica en las réplicas de lectura. Antes de actualizar, inhabilita la replicación para cada réplica de lectura o borra las réplicas de lectura.

  3. Si Cloud SQL es la fuente de replicación lógica, inhabilita la replicación de extensión pglogical de la siguiente manera. Puedes volver a habilitarla después de la actualización. Si Cloud SQL es el destino de replicación lógica, estos pasos no son necesarios.
    1. Inhabilita la suscripción y desconecta la réplica del proveedor mediante el siguiente comando: 
      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      Reemplaza name por el nombre de la suscripción existente.

      Establece el valor del parámetro immediate en true si la suscripción debe inhabilitarse de inmediato. Según la configuración predeterminada, el valor es false y la suscripción se inhabilita solo después de que finaliza la transacción actual.

      Por ejemplo:

      postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true);
 alter_subscription_disable
----------------------------
 t
(1 row)
    2. Quita la ranura de replicación si te conectas al publicador o a la instancia principal de Cloud SQL y ejecutas el siguiente comando: 
      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
  WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      Por ejemplo:

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
-[ RECORD 1 ]------------+-
pg_drop_replication_slot |

postgres=>

  4. 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 PostGIS a cualquier versión intermedia o superior. 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.
  5. 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.
  6. 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.
  7. 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().

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 in situ a PostgreSQL 16 y versiones posteriores, actualiza la extensión PostGIS de todas tus bases de datos a la versión 3.4.0.
  • 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 local de la versión principal a PostgreSQL 16 y versiones posteriores, primero debes actualizar a una versión intermedia de PostgreSQL (versiones 13, 14 o 15).

  • Si instalas las extensiones pgRouting y pg_squeeze para tu instancia, no podrás realizar una actualización de versión principal. Para solucionar este problema, desinstala estas extensiones 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, incluida la forma de borrarlas, consulta Configura marcas de base de datos.

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

Cuando inicias una operación de actualización, Cloud SQL primero verifica la configuración de tu instancia a fin de garantizar que sea compatible con una actualización. Después de verificar tu configuración, Cloud SQL hace que tu instancia deje de estar disponible, realiza una copia de seguridad previa a la actualización, ejecuta la actualización, hace que la instancia esté disponible otra vez y realiza una copia de seguridad posterior a la actualización.

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 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 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 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
}

Aplique los cambios

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.

Borra los cambios

Para borrar tus cambios, haz lo siguiente:

  1. Para inhabilitar la protección contra la eliminación, en tu archivo de configuración de Terraform, establece el argumento deletion_protection en false. 
    deletion_protection =  "false"
  2. Para aplicar la configuración actualizada de Terraform, ejecuta el siguiente comando y, luego, ingresa yes cuando se te solicite: 
    terraform apply

  1. Quita los recursos que se aplicaron antes con tu configuración de Terraform mediante la ejecución del siguiente comando y, luego, ingresa yes cuando se te solicite:

    terraform destroy

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.

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.

Completa la actualización de la versión principal

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

  1. Habilita la replicación pglogical si la instancia la usó antes de la actualización. Esto crea de forma automática la ranura de replicación necesaria.
    1. Descarta la suscripción pglogical en la réplica de destino mediante el siguiente comando: 
      select pglogical.drop_subscription(subscription_name name);

      Reemplaza name por el nombre de la suscripción existente.

      Por ejemplo:

      postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub');
-[ RECORD 1 ]-----+--
drop_subscription | 1
    2. Para volver a crear la suscripción pglogical package en el destino (réplica), proporciona los detalles de la conexión de la siguiente instancia principal de Cloud SQL: 
      SELECT pglogical.create_subscription(
    subscription_name := 'test_sub',
    provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
);

      Por ejemplo:

      postgres=> SELECT pglogical.create_subscription(
postgres(>     subscription_name := 'test_sub',
postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
postgres(> );
-[ RECORD 1 ]-------+-----------
create_subscription | 2769129391
    3. Para verificar el estado de la suscripción, usa el siguiente comando: 
      SELECT * FROM pglogical.show_subscription_status('test_sub');
    4. Para probar la replicación, realiza transacciones de escritura y verifica que los cambios sean visibles en el destino.

  2. Actualiza las réplicas de lectura.

    Si detuviste la replicación para leer réplicas, actualízalas una por una. Puedes usar cualquiera de los métodos utilizados para actualizar la instancia principal. Cuando actualizas una réplica, Cloud SQL vuelve a crearla y conserva las direcciones IP, la actualiza con los datos más recientes de la instancia principal y la reinicia.

    Si borraste tus réplicas de lectura antes de actualizar tu instancia principal, puedes crear réplicas de lectura nuevas, que se aprovisionarán de forma automática en la versión de la base de datos actualizada.

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

  4. Realiza pruebas de aceptación.

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

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.

Visualiza las fallas de la verificación previa a la actualización

Las fallas de verificación previas a la actualización son problemas o errores que Cloud SQL detecta durante el proceso de verificación o validación previa a la actualización. Estas fallas ocurren antes de que comience el proceso de actualización real y están diseñadas para identificar posibles problemas o incompatibilidades que pueden afectar el éxito de la actualización.

Las fallas de la verificación previa a la actualización se muestran para las siguientes categorías:

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

En la siguiente tabla, se enumeran las fallas de verificación previas a la actualización y sus mensajes de error:

Falla de verificación previa a la actualización Mensaje de error
Cloud SQL detecta un tipo de datos desconocido. Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cuando actualizas a PostgreSQL 12 o versiones posteriores, Cloud SQL detecta el tipo de datos 'sql_identifier'. Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta el tipo de datos reg*. Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta que el valor
LC_COLLATE para la base de datos postgres es un grupo de caracteres que no es en_US.UTF8.		 Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
Cloud SQL detecta tablas que tienen identificadores de objetos (OID). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL detecta tipos de datos compuestos. Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL detecta operadores de sufijos definidos por el usuario. Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name)
Cloud SQL detecta funciones polimórficas incompatibles. Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name)
Cloud SQL detecta las conversiones de codificación definidas por el usuario. Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name)
Cloud SQL detecta una ruta de búsqueda vacía para la función ll_to_earth Please update the search path of the 'll_to_earth' function
Cloud SQL detecta la presencia de archivos de trama de PostGIS sin descomprimir. 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.

Se corrigió el problema de ruta de acceso de búsqueda vacía

Esto sucede porque la extensión earthdistance usa tipos de cubo y Tierra sin especificar la ruta de búsqueda de la función. Debes especificar esta ruta de acceso, que es obligatoria durante el proceso de actualización.

Para resolver este problema, ejecuta esta consulta para corregir la ruta de búsqueda de la función ll_to_earth: ALTER FUNCTION ll_to_earth SET search_path = public;

Visualiza los registros de actualización

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, sigue estos pasos:

  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"

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.

Cómo verificar si hay una referencia de columna ambigua

Si tienes una referencia de columna ambigua en tus vistas, es posible que veas este mensaje de error: ERROR: column reference "<column_name>" is ambiguous. Este problema ocurre cuando una nueva versión de PostgreSQL introduce cambios en la estructura de las vistas del catálogo del sistema, como pg_stat_activity y pg_stat_replication. Esto puede interrumpir las vistas personalizadas que dependen del orden de las columnas.

Para verificar este mensaje de error, agrega esta consulta al editor de consultas: textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

Puedes resolver este problema de las siguientes maneras:

  1. Adapta tus vistas personalizadas.

    Actualiza las referencias de columna en tus vistas personalizadas para que se alineen con la nueva definición de la vista del catálogo del sistema (como pg_stat_activity y pg_stat_replication) en la versión de PostgreSQL de destino.

  2. Vuelve a crear tus vistas.

    Elimina tus vistas personalizadas antes de realizar una actualización de versión principal. Vuelve a crear las vistas después de que se complete la actualización y asegúrate de que sean compatibles con la nueva estructura.

Para obtener un ejemplo más detallado del problema y más estadísticas, consulta esta discusión sobre desbordamiento de pila.

Cómo verificar si hay SRF en las instrucciones CASE

Si actualizas tu instancia desde la versión 9.6 y usas funciones que muestran conjuntos en tus sentencias CASE, es posible que veas este mensaje de error ERROR: set-returning functions are not allowed in CASE. Este problema ocurre 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 se modifiquen los enunciados CASE que usan funciones que devuelven conjuntos para evitar su uso antes de volver a intentar la actualización. Entre algunos SRF de uso general, se incluyen los siguientes:

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

Cómo verificar las vistas creadas en transmisiones personalizadas

Si creaste una vista en una transmisión 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

Si un activador de eventos pertenece a un usuario que no tiene el rol de cloudsqlsuperuser, es posible que recibas un mensaje de error, como ERROR: permission denied to change owner of event trigger "<trigger_name>". Este problema se debe a problemas de permisos cuando se intenta volver a crear estos activadores durante la actualización. Puedes agregar la siguiente consulta en el editor de consultas para verificar si aparece este mensaje de error.textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

Para solucionar este problema, verifica la propiedad de todos los activadores de eventos de tu instancia. Asegúrate de que el propietario de cada activador sea un cloudsqlsuperuser. Si otros usuarios son propietarios de los activadores, actualiza su propiedad a un cloudsqlsuperuser antes de intentar volver a realizar la actualización. Puedes usar la siguiente consulta para cambiar la propiedad.ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

Puedes usar la siguiente consulta para obtener una lista de activadores de eventos y los detalles del propietario. SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

Verifica las columnas generadas de las tablas no registradas

Si tienes una tabla sin registrar que generó columnas, es posible que veas el mensaje de error ERROR: unexpected request for new relfilenumber in binary upgrade mode. Este problema ocurre 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. Suprime las tablas que no están registradas: Si es posible, suprime las tablas que no están registradas y que están vinculadas a columnas generadas. Asegúrate de que se pueda mitigar de forma segura la pérdida de datos antes de continuar.
  2. Conversión a tablas permanentes: Convierte de forma temporal las tablas sin registrar en tablas permanentes con los siguientes pasos:
    1. Convierte la tabla en una tabla registrada ALTER TABLE SET LOGGED;
    2. Cómo realizar la actualización de la versión principal
    3. Vuelve a convertir la tabla en una tabla sin registrar. 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.

Restablece 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 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 a la versión anterior, realiza los siguientes 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 usabas 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 usa 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 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 total aumenta de forma proporcional.

¿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?
No, no puedes cancelar una actualización una vez que se inicia. Si la actualización falla, Cloud SQL recupera de forma automática la instancia en la versión anterior.
¿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.

¿Qué sigue?