Realizar una actualización de la versión principal de la base de datos in situ

En esta página se describe cómo realizar una actualización de la versión principal in situ de una base de datos de un clúster de AlloyDB para PostgreSQL. Para obtener información sobre los casos prácticos, el flujo de trabajo y las copias de seguridad automáticas de la actualización in situ de la versión principal de la base de datos, consulta el resumen de la actualización in situ de la versión principal de la base de datos.

Planificar una actualización de versión principal de la base de datos

Sigue estos pasos para planificar una actualización de la versión principal de la base de datos:

1. Busca la versión principal de tu base de datos.

   Consola

   1. En la Google Cloud consola, ve a la página Clusters.

      Ir a Clústeres

   2. Selecciona un clúster de la lista. Aparecerá la página Resumen.

   3. Busca la versión principal de la base de datos en el campo Versión.

   gcloud

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

   Ejecuta el siguiente comando para obtener los detalles del clúster, incluida la versión principal actual:

   gcloud alloydb clusters describe CLUSTER_ID --region=REGION

   Haz las siguientes sustituciones:

   • CLUSTER_ID: el ID del clúster
   • REGION: la ubicación o la región del clúster

   REST v1beta

   Ejecuta la siguiente solicitud para obtener los detalles del clúster, incluida la versión principal actual:

   GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID

   Haz las siguientes sustituciones:

   • CLUSTER_ID: el ID del clúster
   • PROJECT_ID: el ID del proyecto
   • REGION: la ubicación o la región del clúster

   Para enviar tu solicitud, usa una de las siguientes opciones:

   curl (Linux, macOS o Cloud Shell)

   Ejecuta el comando siguiente:

      curl -X GET \
            -H "Authorization: Bearer $(gcloud auth print-access-token)" \
            -H "Content-Type: application/json; charset=utf-8" \
            "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID"
      

   PowerShell (Windows)

   Ejecuta el siguiente comando:

      $cred = gcloud auth print-access-token
      $headers = @{ "Authorization" = "Bearer $cred" }
   
      Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID| Select-Object -Expand Content
      

2. Identifica la versión principal de la base de datos de destino en la siguiente tabla. Para ver una lista completa de las versiones de bases de datos que admite AlloyDB, consulta Versiones de bases de datos y políticas de versiones.

   Versión principal de origen	Versiones principales de destino admitidas
   POSTGRES_14	POSTGRES_15 POSTGRES_16
   POSTGRES_15	POSTGRES_16

3. Consulte las funciones que se ofrecen en cada versión principal de la base de datos.

   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14

4. Identifica las incompatibilidades que debas solucionar. Las nuevas versiones principales pueden introducir cambios incompatibles que requieran que modifiques el código de la aplicación, el esquema o la configuración de la base de datos.

5. Antes de iniciar la actualización de la versión principal en tu clúster de producción, te recomendamos que clones el clúster y pruebes la actualización de la versión principal en el clúster clonado.

   Además de verificar que la actualización se completa correctamente, ejecuta pruebas para asegurarte de que la aplicación se comporta como se espera en el clúster actualizado.

Preparar el clúster para una actualización de versión principal

Para conectarte a la base de datos, usa una de las siguientes opciones:

• AlloyDB Studio
• psql
• Otros métodos de conexión

1. Elimina o promociona tus réplicas entre regiones. Las actualizaciones de versión principal in situ de la base de datos no admiten réplicas entre regiones. Para obtener más información, consulta Réplica entre regiones.

2. Si tu clúster de AlloyDB es una fuente de replicación lógica, inhabilita las suscripciones de réplica y elimina todos los espacios de replicación lógica. Puedes volver a habilitar las suscripciones y recrear las ranuras de replicación lógica después de la actualización. Si la instancia de AlloyDB solo es un destino de replicación lógica, no es necesario seguir estos pasos. Para inhabilitar las suscripciones y eliminar las ranuras de replicación lógica, sigue estos pasos:

   1. Inhabilita cada suscripción de nivel inferior en el suscriptor o en el destino de replicación de nivel inferior. No inhabilite las suscripciones de nivel inferior en la instancia de AlloyDB que se va a actualizar:

      • Si usas pglogical, ejecuta el siguiente comando:

        SELECT * FROM
        pglogical.alter_subscription_disable(SUBSCRIPTION_NAME, immediate);
        

        Sustituye SUBSCRIPTION_NAME en la consulta por el nombre de la suscripción. Si la suscripción debe inhabilitarse inmediatamente, asigna el valor true al parámetro immediate. De forma predeterminada, el valor es false y la suscripción se inhabilita solo cuando finaliza la transacción actual.

        Por ejemplo:

        postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub',true);
        alter_subscription_disable
        ----------------------------
        t
        (1 row)
        

      • Si usas una extensión que no sea pglogical, ejecuta el siguiente comando:

        ALTER SUBSCRIPTION SUBSCRIPTION_NAME DISABLE;
        

   2. Elimina todos los slots de replicación lógica de la instancia principal de AlloyDB ejecutando el siguiente comando:

      SELECT pg_drop_replication_slot(REPLICATION_SLOT_NAME) FROM pg_replication_slots WHERE slot_type = 'logical';
      

      Sustituye REPLICATION_SLOT_NAME en la consulta por el nombre de la ranura de replicación.

3. Gestiona tus extensiones de PostgreSQL. Para obtener más información, consulta Configurar extensiones de bases de datos.

   Las comprobaciones previas a la actualización detectan incompatibilidades de extensiones y muestran esas infracciones en los registros, junto con las acciones sugeridas. Para obtener más información, consulta Ver los errores de la comprobación previa a la actualización.

   Puede que tengas que hacer lo siguiente:

   1. Elimina las extensiones que ya no sean compatibles con la versión de destino.

   2. Actualiza PostGIS y las extensiones relacionadas (address_standardizer, address_standardizer_data_us, postgis_raster, postgis_sfcgal, postgis_tiger_geocoder y postgis_topology) a una versión compatible en la versión de PostgreSQL de destino. Para obtener más información, consulta Extensiones de PostGIS. En la siguiente tabla se indican las versiones mínimas admitidas de la extensión PostGIS para cada versión principal de PostgreSQL:

      Versión de PostgreSQL	Versión mínima admitida de PostGIS
      PG14	3.1
      PG15	3.2
      PG16	3.4

      Por ejemplo, si tu versión de PostGIS es 3.1.x y quieres actualizar de POSTGRES 14 a POSTGRES 16, usa el siguiente comando para actualizar la extensión PostGIS:

      ALTER EXTENSION postgis UPDATE TO '3.4.0';
      SELECT PostGIS_Version();
      

4. Verifica que se permiten las conexiones de cada base de datos, excepto template0, ejecutando la siguiente consulta y comprobando el campo datallowconn de cada base de datos:

   SELECT datname,datallowconn from pg_database;
   

   Un valor t en el campo datallowconn significa que la conexión está permitida. Un valor f indica que no se puede establecer una conexión. La base de datos template0 no debe permitir conexiones.

   Para permitir las conexiones a una base de datos, ejecuta el siguiente comando:

   ALTER DATABASE DATABASE_NAME WITH ALLOW_CONNECTIONS = true;
   

5. Verifica que template1 sea una base de datos de plantilla ejecutando el siguiente comando:

   SELECT datname, datistemplate FROM pg_database WHERE datname = 'template1';
   

   Si datistemplate es f, asigna el valor true ejecutando el siguiente comando:

   ALTER DATABASE template1 WITH IS_TEMPLATE true;
   

Actualizar la versión principal del clúster in situ

La actualización in situ de la versión principal de la base de datos puede tardar entre 40 minutos y 48 horas en completarse, en función de factores como el tamaño de la base de datos, el tamaño del esquema y el número de instancias del grupo de lectura del clúster. El tiempo de inactividad de la instancia principal suele ser de entre 20 minutos y una hora, y depende principalmente del esquema de la base de datos.

Cuando envías una solicitud de actualización de versión principal in situ, AlloyDB primero realiza comprobaciones previas a la actualización. Si AlloyDB determina que tu clúster no está preparado para una actualización de versión principal, la solicitud fallará. Para obtener más información, consulta Solucionar problemas de una actualización in situ de una versión principal.

Para actualizar la versión principal de la base de datos, sigue estos pasos:

gcloud alloydb clusters upgrade CLUSTER_ID --region=REGION --version=DATABASE_VERSION --async

gcloud alloydb clusters upgrade my-cluster --region=us-central1 --version=POSTGRES_16 --async

PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:upgrade

{
  "version": "DATABASE_VERSION"
}

{
"version": "POSTGRES_16"
}

resource "google_alloydb_instance" "default" {
cluster       = google_alloydb_cluster.default.name
instance_id   = "alloydb-instance"
instance_type = "PRIMARY"

machine_config {
  cpu_count = 2
}

depends_on = [google_service_networking_connection.vpc_connection]
}

resource "google_alloydb_cluster" "default" {
  cluster_id = "alloydb-cluster"
  location   = "us-central1"
  network_config {
    network = google_compute_network.default.id
  }
  database_version = "POSTGRES_16"

  initial_user {
    password = "alloydb-cluster"
  }
}

data "google_project" "project" {}

resource "google_compute_network" "default" {
  name = "alloydb-network"
}

resource "google_compute_global_address" "private_ip_alloc" {
  name          =  "alloydb-cluster"
  address_type  = "INTERNAL"
  purpose       = "VPC_PEERING"
  prefix_length = 16
  network       = google_compute_network.default.id
}

resource "google_service_networking_connection" "vpc_connection" {
  network                 = google_compute_network.default.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_alloc.name]
}

Monitorizar la actualización de la versión principal del clúster

Una vez que se haya iniciado la actualización in situ de la versión principal de la base de datos, puedes monitorizar el estado de la actualización mediante la consola, la CLI de gcloud o la API REST. Google Cloud

Respuesta de la operación de actualización

La respuesta de la operación UpgradeCluster incluye lo siguiente:

• status: estado de la operación de actualización general. Los valores posibles son SUCCESS, FAILED y PARTIAL_SUCCESS..
• message: proporciona un breve resumen del resultado de la operación de actualización.
• clusterUpgradeDetails: detalles de la actualización de los clústeres que se están actualizando. Este campo es una matriz. AlloyDB solo permite actualizar un clúster, por lo que solo incluye una entrada.
  • name: nombre completo del clúster.
  • upgradeStatus: el estado de la actualización del clúster. Los valores posibles son SUCCESS, FAILED y PARTIAL_SUCCESS. PARTIAL_SUCCESS significa que no se puede actualizar una o varias instancias del grupo de lectura.
  • clusterType: el tipo de clúster. AlloyDB solo te permite actualizar un clúster PRIMARY. Este tipo siempre debe ser PRIMARY.
  • databaseVersion: la versión actual de la base de datos del clúster.
  • stageInfo: información sobre las fases principales de la actualización.
    • status: SUCCESS o FAILED
    • logs_url: enlace a los registros generados por la fase. Vacío para las fases que no generan registros.
  • instanceUpgradeDetails: información de actualización de todas las instancias del clúster.
    • name: nombre completo de la instancia
    • upgradeStatus: SUCCESS o FAILED
    • instanceType: PRIMARY o READ_POOL

A continuación, se muestra un ejemplo de respuesta de la operación de actualización:

"response": {
  "@type": "type.googleapis.com/google.cloud.alloydb.v1alpha.UpgradeClusterResponse",
  "status": "SUCCESS",
  "message": "Cluster upgraded successfully.",
  "clusterUpgradeDetails": [
    {
      "name": "projects/1234/locations/us-central1/clusters/abc",
      "upgradeStatus": "SUCCESS",
      "clusterType": "PRIMARY",
      "databaseVersion": "POSTGRES_16",
      "stageInfo": [
        {
          "stage": "ALLOYDB_PRECHECK",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "PG_UPGRADE_CHECK",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "PRIMARY_INSTANCE_UPGRADE",
          "status": "SUCCESS",
          "logsUrl": "https://console.cloud.google.com/logs/query..."
        },
        {
          "stage": "READ_POOL_INSTANCES_UPGRADE",
          "status": "SUCCESS",
        }
      ],
      "instanceUpgradeDetails": [
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/primary",
          "upgradeStatus": "SUCCESS",
          "instanceType": "PRIMARY",
        },
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/read1",
          "upgradeStatus": "SUCCESS",
          "instanceType": "READ_POOL",
        },
        {
          "name": "projects/1234/locations/us-central1/clusters/abc/instances/read2",
          "upgradeStatus": "SUCCESS",
          "instanceType": "READ_POOL",
        }
      ]
    }
  ]
}

Ver los registros de actualización de AlloyDB

AlloyDB publica todos los registros de actualización en el registro postgres_upgrade.

Para ver los registros relacionados con la actualización, sigue estos pasos:

1. En la Google Cloud consola, ve a la página Explorador de registros:

   Ve al Explorador de registros.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

2. Selecciona alloydb.googleapis.com/postgres_upgrade como nombre del registro. Esto se traduce en la consulta "logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade".

3. Usa las siguientes etiquetas para filtrar los registros:

   Etiqueta	Descripción
   LOG_TYPE	Fase de actualización que ha generado el registro. Los valores posibles son: ALLOYDB_PRECHECK, PG_UPGRADE_CHECK y PG_UPGRADE.
   OPERATION_NAME	Nombre completo de la operación de actualización.
   FILE_NAME	Solo se rellena en los registros pg_upgrade_check y pg_upgrade, y corresponde a los archivos de registro generados por la utilidad pg_upgrade.

A continuación, se muestra una consulta de ejemplo que devuelve los registros de comprobación previa a la actualización de AlloyDB de una operación determinada:

logName="projects/project1234/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
labels.LOG_TYPE="ALLOYDB_PRECHECK"
labels.OPERATION_NAME="projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID"

Para obtener más información sobre las comprobaciones de actualización, consulta el artículo Información general sobre la actualización de la versión principal de la base de datos in situ.

Ver los registros de actualización de un clúster

Para ver los registros de actualización de un clúster cuando no sepas el ID de operación y la operación haya caducado, sigue estos pasos:

1. En la Google Cloud consola, ve a la página Explorador de registros:

   Ve al Explorador de registros.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

2. Consulta los registros de comprobación previa de AlloyDB de tu clúster.

   logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
   labels.LOG_TYPE="ALLOYDB_PRECHECK"
   resource.labels.cluster_id=CLUSTER_ID
   

3. Busca el Operation_ID en la etiqueta de registro OPERATION_NAME.

   En el siguiente ejemplo, Operation_ID de OPERATION_NAME es operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013.

   labels.OPERATION_NAME="projects/myproject/locations/us-central1/operations/operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
   

4. Consulta todos los registros de postgres_upgrade de una operación específica.

   logName="projects/production-1/logs/alloydb.googleapis.com%2Fpostgres_upgrade"
   labels.OPERATION_NAME="operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013"
   

Cancelar la actualización de la versión principal in situ de la base de datos

Puedes cancelar una operación de actualización de versión principal en curso desde la consola de Google Cloud , la CLI de gcloud o la API REST.

Buscar el ID de operación

Para cancelar la operación de actualización de la versión principal con la CLI de gcloud o la API REST, necesitas el ID de la operación. Debes especificar este ID en el comando de la API REST o de la CLI de gcloud para que AlloyDB sepa qué operación cancelar.

No puedes cancelar la actualización después de que la instancia principal alcance un punto determinado.

Cuando inicias la actualización de la versión principal in situ, el ID de la operación se devuelve en el campo name de la respuesta. Consulta el ejemplo de respuesta.

También puedes encontrar el ID de operación haciendo una llamada operations.list en el clúster de AlloyDB.

Cancelar la actualización

Para cancelar una actualización de versión principal in situ, sigue estos pasos:

gcloud alloydb operations cancel OPERATION_ID

POST https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/operations/OPERATION_ID:cancel

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

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

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

Completar la actualización de la versión principal en contexto

Para completar la actualización de la versión principal, conéctate a una instancia de AlloyDB mediante AlloyDB Studio, psql u otros métodos de conexión.

Si usas un sistema que no es AlloyDB, consulta la documentación del sistema para obtener instrucciones sobre cómo conectarte.

Después de actualizar el clúster, sigue estos pasos para completar la actualización:

1. Si has inhabilitado pglogical, vuelve a habilitar la replicación de pglogical. Al habilitar la replicación pglogical, se crea automáticamente el espacio de replicación necesario.

   1. Elimina la suscripción pglogical en la réplica de destino con el siguiente comando:

        select pglogical.drop_subscription(subscription_name name);
      

      Sustituye name por el nombre de la suscripción. Por ejemplo:

      postgres=> select pglogical.drop_subscription(subscription_name:= 'test_sub');
      -[ RECORD 1 ]-----+--
      drop_subscription |1
      
      1.  Recreate the `pglogical` subscription on the destination or
        replica by providing the following connection information to the
        AlloyDB primary instance:
      
        ```sql
        SELECT pglogical.create_subscription(
        subscription_name :='test_sub',<br>
        provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
        );
        ```
      
      1.  Check the status of the subscription by using the following command:
      
        ```sql
        SELECT * FROM pglogical.show_subscription_status('test_sub');
        ```
      
      1.  Test the replication by performing write transactions and
        verifying that the changes are visible on the destination.
      

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

   Una vez completada la actualización, ejecuta ANALYZE en tu clúster principal para actualizar las estadísticas del sistema. Las estadísticas precisas aseguran que el planificador de consultas de PostgreSQL procese las consultas de forma óptima. Si faltan estadísticas, se pueden generar planes de consulta inexactos, lo que puede reducir el rendimiento y ocupar demasiada memoria.

3. Ejecuta pruebas de aceptación para asegurarte de que el sistema actualizado funciona como se espera.

4. Verifica que la versión principal de la base de datos actualizada in situ aparezca en la página Información general del clúster en la consola Google Cloud .

Restaurar la versión principal anterior

Si el sistema de base de datos actualizado no funciona como esperabas, es posible que tengas que volver al estado anterior a la actualización. Para ello, restaura una copia de seguridad anterior a la actualización (ya sea la que AlloyDB crea automáticamente durante el proceso de actualización o una copia de seguridad anterior a la actualización que ya tengas) para crear un clúster con el estado anterior a la actualización.

Para volver a un estado anterior a la actualización, sigue estos pasos:

1. Identifica una copia de seguridad anterior a la actualización desde la que restaurar. Durante el proceso de actualización, AlloyDB crea automáticamente una copia de seguridad previa a la actualización con el prefijo pre-upgrade-bkp. Para obtener más información, consulta Ver una lista de copias de seguridad.

2. Inicia una restauración a partir de la copia de seguridad anterior a la actualización, lo que creará un nuevo clúster con la versión anterior de PostgreSQL. Para obtener más información, consulta Restaurar un clúster a partir de una copia de seguridad almacenada.

3. Conecta tu aplicación. Actualiza tu aplicación con detalles sobre el clúster restaurado y sus réplicas de lectura. Puedes reanudar el servicio de tráfico en el clúster restaurado.

También puedes realizar una recuperación a un momento dado anterior a la actualización. Para obtener más información, consulta Usar la recuperación a un momento dado (PITR).

Limitaciones

Las siguientes limitaciones afectan a las actualizaciones de versión principal in situ de AlloyDB:

• No puedes realizar una actualización de versión principal in situ en un clúster secundario.
• Actualizar instancias que tengan más de 1000 bases de datos de una versión a otra puede llevar mucho tiempo y puede que se agote el tiempo de espera.
• AlloyDB no admite la actualización de clústeres que usan pg_largeobject_metadata. Si select count(*) from pg_largeobject_metadata; es distinto de cero, la actualización falla.
• La operación de actualización de la versión principal in situ puede completarse antes de que se complete la copia de seguridad previa a la actualización o las copias de seguridad posteriores a la actualización, sobre todo si tienes una base de datos grande con menos objetos de esquema.
• Puede que haya un breve retraso entre el momento en que se reanudan las escrituras en la instancia actualizada y el momento en que se crea la copia de seguridad posterior a la actualización. Esto significa que el contenido de la copia de seguridad posterior a la actualización podría no coincidir con el contenido de la base de datos anterior a la actualización de la versión principal.
• Es posible que se sigan creando copias de seguridad previas a la actualización cuando falle una actualización de versión principal in situ.
• Como las copias de seguridad de la actualización automática son continuas, no puedes eliminarlas hasta que alcancen el tiempo máximo de conservación de las copias de seguridad y la recuperación continuas. Cuando se alcanza el tiempo máximo de conservación, las copias de seguridad se eliminan. También puedes usar la CLI de gcloud para eliminar las copias de seguridad manualmente. Para obtener más información, consulta Restricciones para eliminar copias de seguridad.

Siguientes pasos

• Más información sobre las actualizaciones de la versión principal in situ de la base de datos
• Solucionar problemas con una actualización in situ de una versión principal.
• Consulta información sobre los errores de actualización de la versión principal in situ de la base de datos.