Actualizar la versión principal de la base de datos en el lugar

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Esta página describe cómo actualizar la versión principal de la base de datos actualizando su instancia de Cloud SQL en el lugar en lugar de migrar los datos .

Introducción

Los proveedores de software de bases de datos lanzan periódicamente nuevas versiones principales con nuevas funciones, mejoras de rendimiento y de seguridad. Cloud SQL acepta nuevas versiones tras su lanzamiento. Una vez que Cloud SQL ofrece soporte para una nueva versión principal, puede actualizar sus instancias para mantener su base de datos actualizada.

Puede actualizar la versión de la base de datos de una instancia localmente o migrando datos . Las actualizaciones locales son una forma más sencilla de actualizar la versión principal de su instancia. No necesita migrar datos ni cambiar las cadenas de conexión de la aplicación. Con las actualizaciones locales, puede conservar el nombre, la dirección IP y otras configuraciones de su instancia actual después de la actualización. Las actualizaciones locales no requieren mover archivos de datos y se completan más rápido. En algunos casos, el tiempo de inactividad es menor que el que implica migrar los datos.

Planificar una actualización de versión importante

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

2. Elija una versión principal de destino.

   nube g

   Para obtener información sobre la instalación y los primeros pasos con la CLI de gcloud, consulte Instalar la CLI de gcloud . Para obtener información sobre cómo iniciar Cloud Shell, consulte Usar Cloud Shell .

   Para comprobar las versiones de base de datos que puede seleccionar para una actualización local en su instancia, haga lo siguiente:

   1. Ejecute el siguiente comando.

   gcloud sql instances describe INSTANCE_NAME
      

   Reemplace INSTANCE_NAME con el nombre de la instancia.

   2. En la salida del comando, ubique la sección denominada upgradableDatabaseVersions .
   3. Cada subsección devuelve una versión de la base de datos que puede actualizarse. En cada subsección, revise los siguientes campos.
   • majorVersion : la versión principal a la que puede apuntar para la actualización local.
   • name : la cadena de versión de la base de datos que incluye la versión principal.
   • displayName : el nombre para mostrar de la versión de la base de datos.

   REST versión 1

   Para verificar qué versiones de la base de datos de destino están disponibles para una actualización local de una versión principal, utilice el método instances.get de la API de administración de Cloud SQL.

   Antes de utilizar cualquiera de los datos solicitados, realice las siguientes sustituciones:

   • 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 su solicitud, expanda una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Ejecute 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)

   Ejecute 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ía recibir una respuesta JSON similar a la siguiente:

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

   REST v1beta4

   Para verificar qué versiones de la base de datos de destino están disponibles para la actualización local de la versión principal de una instancia, utilice el método instances.get de la API de administración de Cloud SQL.

   Antes de utilizar cualquiera de los datos solicitados, realice las siguientes sustituciones:

   • 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 su solicitud, expanda una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Ejecute 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)

   Ejecute 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ía recibir una respuesta JSON similar a la siguiente:

   
   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, consulte Versiones de bases de datos y políticas de versiones .

3. Tenga en cuenta las características ofrecidas en cada versión principal de la base de datos y aborde las incompatibilidades.

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

   Las nuevas versiones principales introducen cambios incompatibles que podrían requerir la modificación del código de la aplicación, el esquema o la configuración de la base de datos. Antes de actualizar la instancia de la base de datos, revise las notas de la versión principal de destino para determinar las incompatibilidades que debe solucionar.

4. Pruebe la actualización con una ejecución en seco.

   Realice un simulacro del proceso de actualización integral en un entorno de prueba antes de actualizar la base de datos de producción. Puede clonar su instancia para crear una copia idéntica de los datos con la que probar el proceso de actualización.

   Además de validar que la actualización se complete exitosamente, ejecute pruebas para garantizar que la aplicación se comporte como se espera en la base de datos actualizada.

5. Decide un momento para realizar la actualización.

   La actualización requiere que la instancia no esté disponible durante un tiempo. Planifique la actualización durante un período de baja actividad de la base de datos.

Prepárese para una actualización de versión importante

Antes de actualizar, complete los siguientes pasos.

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

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

   Para cambiar la codificación de una base de datos:

   1. Vacíe su base de datos.
   2. Elimina tu base de datos.
   3. Cree una nueva base de datos con la codificación diferente (para este ejemplo, en_US.UTF8 ).
   4. Recargue sus datos.

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

   1. Cerrar todas las conexiones a la base de datos.
   2. Cambiar el nombre de la base de datos.
   3. Actualice las configuraciones de su aplicación para utilizar el nuevo nombre de la base de datos.
   4. Crea una nueva base de datos vacía con la codificación predeterminada.

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

2. Administre sus extensiones restantes de PostgreSQL .

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

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

   En ocasiones, actualizar desde la versión 2.x de PostGIS puede generar objetos de base de datos sobrantes que no están asociados con la extensión PostGIS. Esto puede bloquear la actualización. Para obtener información sobre cómo resolver este problema, consulte "Reparar una instalación ráster de PostGIS defectuosa" .

   En ocasiones, la actualización a la versión 3.1.7 o posterior de PostGIS no se puede completar debido a que los objetos utilizan funciones obsoletas. Esto puede bloquear la actualización. Para comprobar el estado de la actualización, ejecute SELECT PostGIS_full_version(); . Si aparecen advertencias, elimine los objetos que utilicen las funciones obsoletas y actualice la extensión de PostGIS a una versión intermedia o superior. Tras completar estas acciones, vuelva a ejecutar el comando SELECT PostGIS_full_version(); . Compruebe que no aparezcan advertencias. A continuación, proceda con la actualización.

   Para obtener más información sobre cómo actualizar las extensiones de PostGIS, consulte Actualización de PostGIS . Para obtener información sobre problemas relacionados con la actualización de PostGIS, consulte Comprobar la versión de su instancia de PostgreSQL .
3. Administre sus indicadores de base de datos personalizados. Compruebe los nombres de los indicadores de base de datos personalizados que haya configurado para su instancia de PostgreSQL. Para obtener información sobre problemas relacionados con estos indicadores, consulte "Comprobar los indicadores personalizados de su instancia de PostgreSQL" .
4. Al actualizar de una versión principal a otra, intente conectarse a cada base de datos para comprobar si hay problemas de compatibilidad. Asegúrese de que las bases de datos puedan conectarse entre sí. Revise el campo datallowconn de cada base de datos para comprobar que se permite la conexión. Un valor t significa que está permitido y un valor f indica que no se puede establecer la conexión.
5. Si utiliza la instalación de Datadog para actualizar su instancia de Cloud SQL a PostgreSQL 10 o versiones posteriores, antes de realizar la actualización, elimine la función pg_stat_activity() .

Limitaciones conocidas

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

• No es posible realizar una actualización de versión principal local en una réplica externa .
• La actualización de instancias que tienen más de 1000 bases de datos de una versión a otra puede llevar mucho tiempo y generar tiempos de espera.
• Use la instrucción select * from pg_largeobject_metadata; para consultar el número de objetos grandes en cada base de datos PostgreSQL de su instancia de Cloud SQL. Si el resultado de todas sus bases de datos supera los 10 millones de objetos grandes, la actualización fallará. Cloud SQL revierte a la versión anterior de su base de datos.
• Antes de realizar una actualización local de una versión principal de PostgreSQL 16 y posteriores, actualice la extensión PostGIS de todas sus bases de datos a la versión 3.4.0.
• Antes de realizar una actualización de versión principal local a PostgreSQL 17, actualice la extensión rdkit de todas sus bases de datos a la versión 4.6.1.
• Si utiliza las versiones 9.6, 10, 11 o 12 de PostgreSQL, la versión 3.4.0 de la extensión PostGIS no es compatible. Por lo tanto, para realizar una actualización principal local a PostgreSQL 16 o posterior, primero debe actualizar a una versión intermedia de PostgreSQL (versiones 13, 14 o 15).

• Si instala las extensiones pg_ivm o pg_squeeze en su instancia, no podrá realizar una actualización de versión principal. Para solucionarlo, desinstálelas y realice la actualización. Para obtener más información sobre las extensiones, consulte Configurar extensiones de PostgreSQL .

• Si habilita las marcas vacuum_defer_cleanup_age y force_parallel_mode , no podrá realizar una actualización de versión principal. Para solucionarlo, elimine estas marcas y luego realice la actualización. Para obtener más información sobre las marcas, incluyendo cómo eliminarlas, consulte Configurar marcas de base de datos .

Realizar la actualización de la versión principal

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

Actualizar la versión principal de una sola instancia

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

1. Comprueba la configuración de su instancia para garantizar que la instancia sea compatible para 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 su instancia esté disponible.
6. Realiza una copia de seguridad posterior a la actualización.

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
}

Al solicitar una actualización local, Cloud SQL realiza primero una comprobación previa. Si Cloud SQL determina que su instancia no está lista para una actualización, la solicitud fallará y mostrará un mensaje que sugiere cómo solucionar el problema. Consulte también Solucionar problemas de una actualización de versión principal .

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

Si su instancia principal tiene réplicas, puede 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 incluye réplicas en una actualización de versión principal, Cloud SQL hace lo siguiente:

1. Comprueba la configuración de la instancia principal y las réplicas para garantizar que la instancia y las réplicas sean compatibles para una actualización.
2. Hace que su 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 de todas las réplicas.
5. Realiza la actualización en la instancia principal.
6. Si la actualización en la instancia principal es exitosa, la instancia principal vuelve a estar disponible y reinicia la replicación.
7. Cloud SQL realiza una copia de seguridad de la instancia principal posterior a la actualización.
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 continúa estando disponible.

Para incluir réplicas en una actualización de versión principal, no puede utilizar elGoogle Cloud Consola o Terraform. Solo puedes usar la CLI de gcloud o la API de administración de Cloud SQL.

Copias de seguridad de actualización automáticas

Cuando realiza una actualización de versión importante, Cloud SQL realiza automáticamente dos copias de seguridad a pedido, denominadas copias de seguridad de actualización:

• La primera copia de seguridad de la actualización es la copia de seguridad previa a la actualización, que se realiza justo antes de iniciarla. Puede usar esta copia de seguridad para restaurar la instancia de la base de datos a su estado original.
• La segunda copia de seguridad de actualización es la copia de seguridad posterior a la actualización , que se realiza inmediatamente después de que se permiten nuevas escrituras en la instancia de base de datos actualizada.

Al consultar la lista de copias de seguridad , las de actualización se muestran como " On-demand . Estas copias de seguridad están etiquetadas para que pueda identificarlas rápidamente. Por ejemplo, si actualiza de PostgreSQL 14 a PostgreSQL 15, la copia de seguridad previa a la actualización se etiqueta como Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. y la 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 se conservan hasta que las elimine o hasta que elimine la instancia. Si tiene PITR habilitado, no podrá eliminar las copias de seguridad de actualización mientras estén dentro del período de retención. Si necesita eliminarlas, debe deshabilitar PITR o esperar a que finalicen el período de retención.

Completar la actualización de la versión principal

Después de terminar de actualizar su instancia principal, realice los siguientes pasos para completar la actualización:

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

   Ejecute ANALYZE en su instancia principal para actualizar las estadísticas del sistema después de la actualización. Unas estadísticas precisas garantizan que el planificador de consultas de PostgreSQL procese las consultas de forma óptima. La falta de estadísticas puede generar planes de consulta incorrectos, lo que a su vez podría reducir el rendimiento y ocupar demasiada memoria.

2. Realizar pruebas de aceptación.

   Ejecute pruebas para garantizar que el sistema actualizado funcione como se espera.

Solucionar problemas de una actualización de versión importante

Cloud SQL devuelve un mensaje de error si intenta un comando de actualización no válido, por ejemplo, si su instancia contiene indicadores de base de datos no válidos para la nueva versión.

Si su solicitud de actualización falla, verifique su sintaxis. Si la solicitud tiene una estructura válida, consulte las siguientes sugerencias.

Ver fallas de verificación previas a la actualización

Los fallos de comprobación previos a la actualización son problemas o errores que Cloud SQL detecta durante el proceso de verificación o validación previo a la actualización. Estos fallos se producen antes de que comience el proceso de actualización y su objetivo es identificar posibles problemas o incompatibilidades que puedan afectar el éxito de la actualización.

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

• Extensiones incompatibles: detecta 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 necesitan actualizarse.
• Incompatibilidades de formato de datos: verificar inconsistencias de datos que surgen de varios factores, incluidas diferencias en estructuras de datos específicas de la versión, alteraciones en la codificación y la intercalación, modificaciones en los tipos de datos y ajustes en el catálogo del sistema.

La siguiente tabla enumera los fallos de comprobación previos a la actualización y sus mensajes de error:

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

Esto se debe a que la extensión earthdistance utiliza los tipos Earth y Cube sin especificar la ruta de búsqueda de la función. Debe especificar esta ruta, que es necesaria durante el proceso de actualización.

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

Ver registros de actualización

Si ocurre 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 upgrade.log. Cada entrada del registro contiene una etiqueta con el identificador de la instancia para ayudarle a identificar la instancia con el error de actualización. Busque estos errores de actualización y resuélvalos.

Para ver los registros de errores, siga estos pasos:

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

   Ir a Instancias de Cloud SQL

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

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

   Se abre la página del Explorador de registros .

4. Ver registros de la siguiente manera:

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

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

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

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

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

   Por ejemplo, para filtrar los registros de errores de actualización por una instancia llamada shopping-db que se ejecuta en el proyecto buylots , utilice 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.

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;