Realizar um upgrade da versão principal do banco de dados no local

Para fazer upgrade de um cluster do AlloyDB para PostgreSQL para uma versão principal mais recente do PostgreSQL preservando os nomes das instâncias, os endereços IP e as strings de conexão atuais, planeje, valide e execute um upgrade de versão principal no local. Para Aprenda Mais sobre os casos de uso, as etapas do fluxo de trabalho e os backups automáticos do upgrade de versão principal no local, consulte Visão geral do upgrade de versão principal no local do banco de dados.

Planejar um upgrade da versão principal do banco de dados

Siga estas etapas para planejar um upgrade da versão principal do banco de dados:

  1. Encontre a versão principal atual do banco de dados.

    Console

    1. No Google Cloud console, acesse a página Clusters.

      Acessar Clusters

    2. Selecione um cluster na lista. A página Visão geral é exibida.

    3. Localize a versão principal do banco de dados no campo Versão.

    gcloud

    Para informações sobre como instalar e dar os primeiros passos com a CLI gcloud, consulte Instalar a CLI gcloud. Para mais informações sobre como iniciar o Cloud Shell, consulte Usar o Cloud Shell.

    Execute o seguinte comando para ver os detalhes do cluster, incluindo a versão principal atual:

    gcloud alloydb clusters describe CLUSTER_ID --region=REGION

    Faça as seguintes substituições:

    • CLUSTER_ID: o ID do cluster.
    • REGION: o local ou a região do cluster

    REST v1beta

    Execute a seguinte solicitação para ver os detalhes do cluster, incluindo a versão principal atual:

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

    Faça as seguintes substituições:

    • CLUSTER_ID: o ID do cluster.
    • PROJECT_ID: o ID do projeto;
    • REGION: o local ou a região do cluster

    Para enviar a solicitação, use uma das seguintes opções:

    curl (Linux, macOSou Cloud Shell)

    Execute o seguinte comando: 

       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)

    Execute este 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. Identifique uma versão principal do banco de dados de destino na tabela a seguir. Para uma lista completa das versões de bancos de dados com suporte do AlloyDB, consulte Versões do banco de dados e políticas de versão.

    Versão principal de origem Versões principais de destino compatíveis
    POSTGRES_14
    • POSTGRES_15
    • POSTGRES_16
    • POSTGRES_17
    • POSTGRES_18
    POSTGRES_15
    • POSTGRES_16
    • POSTGRES_17
    • POSTGRES_18
    POSTGRES_16
    • POSTGRES_17
    • POSTGRES_18
    POSTGRES_17
    • POSTGRES_18

  3. Analise os recursos oferecidos em cada versão principal do banco de dados.

  4. Identifique as incompatibilidades que você precisa resolver. As novas versões principais podem apresentar alterações incompatíveis que podem exigir que você modifique o código do aplicativo, o esquema ou as configurações do banco de dados.

  5. Antes de iniciar o upgrade da versão principal no cluster de produção, recomendamos que você clone o cluster e teste o upgrade da versão principal no cluster clonado.

    Além de verificar se o upgrade foi concluído com sucesso, execute testes para garantir que o aplicativo se comporta conforme o esperado no cluster atualizado.

Preparar o cluster para um upgrade de versão principal

Para se conectar ao banco de dados, use uma das seguintes opções:

1. Remova ou promova suas réplicas entre regiões. Os upgrades de versão principal no local do banco de dados não são compatíveis com réplicas entre regiões. Para mais informações, consulte Replicação entre regiões.

  1. Se o cluster do AlloyDB for uma origem de replicação lógica, desative as assinaturas downstream e remova todos os slots de replicação lógica. É possível reativar as assinaturas e recriar os slots de replicação lógica após o upgrade. Se a instância do AlloyDB for apenas um destino de replicação lógica, essas etapas não serão necessárias. Para desativar assinaturas e descartar slots de replicação lógica, siga estas etapas:

    1. Desative cada assinatura downstream no assinante ou no destino de replicação downstream. Não desative as assinaturas downstream na instância do AlloyDB que está sendo atualizada:

      • Se você estiver usando pglogical, execute o seguinte comando:

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

        Substitua SUBSCRIPTION_NAME na consulta pelo nome da assinatura atual. Se a assinatura precisar ser desativada imediatamente, defina o valor do parâmetro immediate como true. Por padrão, o valor é false, e a assinatura é desativada apenas depois que a transação atual termina.

        Exemplo:

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

      • Se você estiver usando uma extensão diferente de pglogical, execute o seguinte comando:

        ALTER SUBSCRIPTION SUBSCRIPTION_NAME DISABLE;

    2. Remova todos os slots de replicação lógica na instância principal do AlloyDB executando o seguinte comando:

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

      Substitua REPLICATION_SLOT_NAME na consulta pelo nome do slot de replicação.

  2. Gerencie suas extensões do PostgreSQL. Para mais informações, consulte Configurar extensões de banco de dados.

    As verificações pré-upgrade detectam incompatibilidades de extensão e mostram essas violações nos registros, além de sugerir ações. Para mais informações, consulte Conferir falhas na verificação anterior ao upgrade.

    Talvez seja necessário fazer o seguinte:

    1. Remova as extensões que não são mais compatíveis com a versão de destino.

    2. Faça upgrade do PostGIS e das extensões relacionadas (address_standardizer, address_standardizer_data_us, postgis_raster, postgis_sfcgal, postgis_tiger_geocoder e postgis_topology) para uma versão compatível com a versão de destino do PostgreSQL. Para mais informações, consulte Extensões do PostGIS. A tabela a seguir lista as versões mínimas compatíveis da extensão PostGIS para cada versão principal do PostgreSQL:

      Versão do PostgreSQL Versão mínima compatível do PostGIS
      PG14 3.1
      PG15 3.2
      PG16 3.4
      PG17 3.5
      PG18 3.6

      Por exemplo, se a versão do PostGIS for 3.1.x e você quiser fazer upgrade do POSTGRES 14 para o POSTGRES 16, use o seguinte comando para fazer upgrade da extensão PostGIS:

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

  3. Verifique se os clusters não contêm associações de papéis órfãs. Os upgrades de versão principal no local não preservam as associações de papéis em que o concedente original não existe mais. Se algum cluster tiver associações órfãs no catálogo pg_auth_members, elas serão perdidas após o upgrade.

    Para detectar assinaturas órfãs, execute a seguinte consulta:

    SELECT roleid::regrole, member::regrole, grantor::regrole
FROM pg_auth_members
WHERE grantor::regrole::text ~ '^[0-9]+$';

    Se a consulta retornar linhas, recrie as assinaturas de papel antes de fazer upgrade do cluster. Para cada associação órfã, revogue o privilégio e conceda-o novamente. Isso associa a assinatura a um concedente atual e válido (como alloydbadmin).

    Execute o seguinte bloco de transação para cada associação órfã:

    BEGIN;
REVOKE ROLE_NAME FROM MEMBER_NAME;
GRANT ROLE_NAME TO MEMBER_NAME;
COMMIT;

    Substitua ROLE_NAME e MEMBER_NAME pelos papéis dos resultados da consulta.

  4. Verifique se as conexões são permitidas para cada banco de dados, exceto template0, executando a consulta a seguir e verificando o campo datallowconn de cada banco de dados:

    SELECT datname,datallowconn from pg_database;

    Um valor t no campo datallowconn significa que a conexão é permitida. Um valor f indica que não é possível estabelecer uma conexão. O banco de dados template0 não pode permitir conexões.

    Para permitir conexões com um banco de dados, execute o seguinte comando:

    ALTER DATABASE DATABASE_NAME WITH ALLOW_CONNECTIONS = true;

  5. Verifique se template1 é um banco de dados de modelo executando o seguinte comando:

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

    Se datistemplate for f, defina-o como true executando o seguinte comando:

    ALTER DATABASE template1 WITH IS_TEMPLATE true;

Fazer upgrade da versão principal do cluster no local

O upgrade da versão principal do banco de dados no local pode levar de 40 minutos a 48 horas para ser concluído, dependendo de fatores como o tamanho do banco de dados, o tamanho do esquema e o número de instâncias do pool de leitura no cluster. O tempo de inatividade da instância principal geralmente é de 20 minutos a uma hora e depende principalmente do esquema do banco de dados.

Quando você faz uma solicitação de upgrade de versão principal no local, o AlloyDB primeiro realiza verificações pré-upgrade. Se o AlloyDB determinar que o cluster não está pronto para um upgrade de versão principal, a solicitação vai falhar. Para mais informações, consulte Resolver problemas de um upgrade no local da versão principal.

Para fazer upgrade da versão principal do banco de dados no local, siga estas etapas:

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Selecione um cluster na lista. A página Visão geral é exibida.

  3. Clique em Fazer upgrade para iniciar o processo de upgrade da versão principal do banco de dados.

  4. Na etapa Escolher a versão do banco de dados, selecione uma das versões principais disponíveis como a versão principal de destino.

  5. Clique em Continuar.

  6. Na etapa Fazer upgrade do cluster, no campo ID do cluster, insira o nome do cluster.

  7. Clique em Iniciar upgrade. Você vai para a etapa Status do upgrade, em que é possível verificar o status do upgrade. Para mais informações, consulte Monitorar o upgrade da versão principal do banco de dados.

gcloud

Inicie o upgrade da versão principal no local executando o seguinte comando:

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

Confira um exemplo de comando:

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

REST v1beta

Inicie o upgrade da versão principal no local executando o seguinte comando:

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

Corpo JSON da solicitação:

{
  "version": "DATABASE_VERSION"
}

Substitua pelo tipo enumerado da versão principal do banco de dados de destino, que precisa ser posterior à versão atual.

Exemplo de corpo JSON da solicitação:

{
"version": "POSTGRES_16"
}
* { Terraform }





To upgrade an instance within your database cluster to a PostgreSQL version, use a [Terraform resource](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/alloydb_instance) and set the `database_version` to a [supported target major version](/alloydb/docs/upgrade-db-inplace-major-version#plan-upgrade).

```none
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]
}
```

To learn how to apply or remove a Terraform configuration, see [Basic Terraform commands](/docs/terraform/basic-commands).

Monitorar o upgrade da versão principal do cluster

Depois que o upgrade de versão principal do banco de dados no local começar, será possível monitorar o status do upgrade usando o Google Cloud console, a CLI gcloud ou a API REST.

Console

Siga estas etapas para verificar o status do upgrade no console do Google Cloud :

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Selecione o cluster que está sendo atualizado. A página Visão geral é exibida.

  3. Abra a página Visão geral.

  4. Clique em Status do upgrade. A página Status do upgrade é exibida, onde é possível verificar o status do upgrade.

gcloud

Siga estas etapas para verificar o status do upgrade na CLI gcloud:

  1. Para receber o ID da operação de upgrade, execute o comando a seguir. Antes de executar o comando, substitua a variável CLUSTER_ID pelo nome do cluster:

    gcloud alloydb operations list --cluster=CLUSTER_ID --region=REGION_ID --filter=metadata.verb:upgrade

    A chamada da CLI gcloud usada para acionar um upgrade de versão principal. alloydb beta clusters upgrade, retorna o ID da operação como uma resposta síncrona. Como alternativa, use o comando gcloud alloydb operations list com a flag --cluster.

    Confira um exemplo de comando:

    gcloud alloydb operations list --cluster=my-cluster --region=us-central1 --filter=metadata.verb:upgrade

  2. Monitore o status do upgrade executando o comando gcloud alloydb operations describe:

    gcloud alloydb operations describe OPERATION_ID
--region=REGION

REST v1beta

Siga estas etapas para verificar o status do upgrade na API REST:

  1. Receba o ID da operação de upgrade.

    Use a seguinte solicitação GET com o método operations.list para listar todas as operações de upgrade e encontrar aquela que corresponde ao cluster de destino:

    GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/operations/filter=metadata.verb:upgrade

    A chamada de API REST retorna o ID da operação como uma resposta síncrona.

  2. Monitore o status do upgrade.

    Use uma solicitação GET com o método operations.get:

      GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

    Faça as seguintes substituições:

    • PROJECT_ID: o ID do projeto;
    • REGION: o local ou a região do cluster
    • OPERATION_ID: o ID da operação de upgrade, que foi recuperado na etapa anterior.

    Veja a seguir um exemplo de resposta quando a operação está em andamento:

    {
"name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
"metadata": {
"@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
"createTime": "2024-09-16T23:17:39.727319438Z",
"target": "projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID",
"verb": "upgrade",
"requestedCancellation": false,
"apiVersion": "v1",
"upgradeClusterStatus": {
   "state": "IN_PROGRESS",
   "cancellable": true,
   "stages": [
    {
      "stage": "ALLOYDB_PRECHECK",
      "state": "IN_PROGRESS"
    },
    {
      "stage": "PG_UPGRADE_CHECK",
      "state": "IN_PROGRESS"
    },
    {
      "stage": "PREPARE_FOR_UPGRADE",
      "state": "NOT_STARTED"
    },
    {
      "stage": "PRIMARY_INSTANCE_UPGRADE",
      "state": "NOT_STARTED"
    },
    {
      "stage": "CLEANUP",
      "state": "NOT_STARTED"
    }
   ]
 }
},
"done":false
}

    Veja a seguir um exemplo de resposta quando a operação é concluída:

    {
"operations": [
{
 "metadata": {
 "@type": "type.googleapis.com/google.cloud.alloydb.v1betaalpha.OperationMetadata",
 "createTime": "2024-09-16T21:52:17.303861317Z",
 "endTime": "2024-09-16T22:29:13.947527949Z",
 "target": "projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID",
 "verb": "upgrade",
 "requestedCancellation": false,
 "apiVersion": "v1beta",
 "upgradeClusterStatus": {
  "state": "SUCCESS",
  "stages": [
    {
      "stage": "ALLOYDB_PRECHECK",
      "state": "SUCCESS"
    },
    {
      "stage": "PG_UPGRADE_CHECK",
      "state": "SUCCESS"
    },
    {
      "stage": "PREPARE_FOR_UPGRADE",
      "state": "SUCCESS"
    },
    {
      "stage": "PRIMARY_INSTANCE_UPGRADE",
      "state": "SUCCESS"
    },
    {
      "stage": "CLEANUP",
      "state": SUCCESS"
    }
   ]
 }
},
"response": {
     …
},
"name":  "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
"done": true
}
]
}

    Para mais informações sobre a estrutura response, consulte Resposta da operação de upgrade.

Resposta da operação de upgrade

A resposta da operação UpgradeCluster inclui o seguinte:

  • status: status da operação geral de upgrade. Os valores possíveis são SUCCESS, FAILED e PARTIAL_SUCCESS..
  • message: fornece um breve resumo do resultado da operação de upgrade.
  • clusterUpgradeDetails: detalhes do upgrade dos clusters que estão sendo atualizados. Esse campo é uma matriz. O AlloyDB só permite um upgrade de cluster, então inclui apenas uma entrada.
    • name: nome totalmente qualificado do cluster.
    • upgradeStatus: o status do upgrade do cluster. Os valores possíveis são SUCCESS, FAILED, PARTIAL_SUCCESS. PARTIAL_SUCCESS significa que não é possível fazer upgrade de uma ou mais instâncias do pool de leitura.
    • clusterType: o tipo de cluster. O AlloyDB só permite fazer upgrade de um único cluster PRIMARY. Esse tipo precisa ser sempre PRIMARY.
    • databaseVersion: a versão atual do banco de dados do cluster.
    • stageInfo: informações sobre as etapas de upgrade do núcleo.
      • status: SUCCESS ou FAILED.
      • logs_url: link para os registros gerados pela etapa. Vazio para etapas que não geram registros.
    • instanceUpgradeDetails: informações de upgrade para todas as instâncias no cluster.
      • name: nome totalmente qualificado da instância.
      • upgradeStatus: SUCCESS ou FAILED.
      • instanceType: PRIMARY ou READ_POOL.

Veja a seguir um exemplo de resposta de operação de upgrade:

"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 registros de upgrade do AlloyDB

O AlloyDB publica todos os registros de upgrade no nome de registro postgres_upgrade.

Para ver os registros relacionados ao upgrade, siga estas etapas:

  1. No console do Google Cloud , acesse a página Análise de registros:

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

  2. Selecione alloydb.googleapis.com/postgres_upgrade como o nome do registro. Isso se traduz na consulta "logName="projects/PROJECT_ID/logs/alloydb.googleapis.com%2Fpostgres_upgrade".

  3. Use os seguintes rótulos para filtrar os registros:

    Rótulo Descrição

    LOG_TYPE

    		 Estágio de upgrade que gerou o registro. Os valores possíveis são ALLOYDB_PRECHECK, PG_UPGRADE_CHECK e PG_UPGRADE.

    OPERATION_NAME

    		 Nome completo da operação de upgrade.

    FILE_NAME

    		 Preenchido apenas para registros pg_upgrade_check e pg_upgrade e corresponde aos arquivos de registro gerados pelo utilitário pg_upgrade.

Veja a seguir um exemplo de consulta que retorna registros de upgrade de pré-verificação do AlloyDB para uma determinada operação:

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 mais informações sobre as verificações de upgrade, consulte Visão geral do upgrade da versão principal do banco de dados no local.

Ver registros de upgrade de um cluster

Para ver os registros de upgrade de um cluster quando você não sabe o ID da operação e ela expirou, siga estas etapas:

  1. No console do Google Cloud , acesse a página Análise de registros:

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

  2. Consulte os registros de pré-verificação do AlloyDB para seu cluster.

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

  3. Encontre o Operation_ID no rótulo de registro OPERATION_NAME.

    No exemplo a seguir, Operation_ID de OPERATION_NAME é operation-1728225968201-623cff6ed1e02-e34b7191-3cd92013.

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

  4. Consulte todos os registros de postgres_upgrade de uma operação específica.

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

Cancelar o upgrade da versão principal do banco de dados no local

É possível cancelar uma operação de upgrade de versão principal em andamento no console do Google Cloud , na CLI gcloud ou na API REST.

Encontrar o ID da operação

Para cancelar a operação de upgrade da versão principal usando a CLI gcloud ou a API REST, você precisa do ID da operação. É necessário especificar esse ID no comando da CLI gcloud ou da API REST para que o AlloyDB saiba qual operação cancelar.

Não é possível cancelar o upgrade depois que o upgrade da instância principal atinge um determinado ponto.

Quando você inicia o upgrade da versão principal no local, o ID da operação é retornado no campo name da resposta. Consulte o exemplo de resposta.

Também é possível encontrar o ID da operação fazendo uma chamada operations.list no cluster do AlloyDB.

Cancelar o upgrade

Para cancelar um upgrade de versão principal no local, siga estas etapas:

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Selecione um cluster na lista. A página Visão geral é exibida.

  3. Clique em Status do upgrade.

  4. Clique em Cancelar upgrade. Se o upgrade não puder ser cancelado, esse botão vai ficar esmaecido.

gcloud

Use o comando gcloud alloydb operations cancel para cancelar a operação:

gcloud alloydb operations cancel OPERATION_ID

Substitua a variável OPERATION_ID pelo ID da operação.

Se o UpgradeClusterStatus mostrar cancellable como false na saída do comando gcloud alloydb operations cancel, o AlloyDB vai ignorar a solicitação de cancelamento e continuar com o upgrade. Nesse caso, a API não gera um erro e retorna uma resposta vazia. Para mais informações sobre o status do upgrade, consulte Monitorar o upgrade da versão principal do cluster.

REST v1beta

Execute este comando:

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

Antes de usar os dados da solicitação, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto;
  • OPERATION_ID: o ID da operação de importação ou exportação.

Se cancellable em UpgradeClusterStatus for false, não será possível cancelar o upgrade.

Para enviar a solicitação, use uma das seguintes opções:

curl (Linux, macOSou Cloud Shell)

Execute este comando:

       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"

PowerShell (Windows)

Execute este comando:

       $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

Você receberá uma resposta JSON semelhante a esta:

Resposta

Essa chamada de API REST não retorna nenhuma resposta.

Concluir o upgrade da versão principal no local

Para concluir o upgrade da versão principal, conecte-se a uma instância do AlloyDB usando o AlloyDB Studio, o psql ou outros métodos de conexão.

Se você estiver usando um sistema que não seja do AlloyDB, consulte a documentação do sistema para ver as instruções de conexão.

Depois de fazer upgrade do cluster, siga estas etapas para concluir o upgrade:

  1. Se você desativou o pglogical, reative a replicação do pglogical. Ativar a replicação do pglogical cria automaticamente o slot de replicação necessário.

    1. Solte a assinatura pglogical na réplica de destino usando o seguinte comando:

        select pglogical.drop_subscription(subscription_name name);

      Substitua name pelo nome da assinatura atual. Exemplo:

      postgres=> select pglogical.drop_subscription(subscription_name:= 'test_sub');
-[ RECORD 1 ]-----+--
drop_subscription |1

    2. Recrie a assinatura pglogical no destino ou na réplica fornecendo as seguintes informações de conexão à instância principal do AlloyDB:

        SELECT pglogical.create_subscription(
  subscription_name :='test_sub',<br>
  provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
  );

    3. Verifique o status da assinatura usando o seguinte comando:

        SELECT * FROM pglogical.show_subscription_status('test_sub');

    4. Teste a replicação executando transações de gravação e verificando se as alterações estão visíveis no destino.

  2. Atualize manualmente as extensões nos bancos de dados atualizados.

    Embora os upgrades de versão principal instalem automaticamente os binários de extensão mais recentes no software subjacente da instância, eles não atualizam automaticamente o catálogo de banco de dados da extensão. Você é responsável por atualizar manualmente suas extensões para garantir que elas usem as versões mais recentes compatíveis. Para instruções, consulte Atualizar uma extensão.

  3. Atualize as estatísticas do banco de dados.

    Após a conclusão do upgrade, execute ANALYZE no cluster principal para atualizar as estatísticas do sistema. Estatísticas precisas garantem que o planejador de consultas do PostgreSQL processe as consultas de maneira ideal. Estatísticas ausentes podem resultar em planos de consulta imprecisos, o que pode prejudicar o desempenho e consumir muita memória.

  4. Execute testes de aceitação para garantir que o sistema atualizado tenha o desempenho esperado.

  5. Verifique se a versão principal atualizada do banco de dados no local aparece na página Visão geral do cluster no console do Google Cloud .

Restaurar a versão principal anterior

Se o sistema de banco de dados atualizado não tiver o desempenho esperado, talvez seja necessário reverter para o estado anterior ao upgrade. Para isso, restaure um backup anterior ao upgrade, seja o que o AlloyDB cria automaticamente durante o processo de upgrade ou um backup anterior ao upgrade, para criar um novo cluster com o estado anterior ao upgrade.

Para restaurar um estado pré-upgrade, siga estas etapas:

  1. Identifique um backup pré-upgrade para restaurar. Durante o processo de upgrade, o AlloyDB cria automaticamente um backup pré-upgrade com o prefixo pre-upgrade-bkp. Para mais informações, consulte Ver uma lista de backups.

  2. Inicie uma restauração do backup pré-upgrade, que cria um novo cluster com a versão anterior do PostgreSQL. Para mais informações, consulte Restaurar um cluster de um backup armazenado.

  3. Conecte o aplicativo. Atualize o aplicativo com detalhes sobre o cluster restaurado e as réplicas de leitura dele. É possível retomar a exibição de tráfego no cluster restaurado.

Também é possível realizar uma recuperação pontual para um momento anterior ao upgrade. Para mais informações, consulte Usar a recuperação pontual (PITR).

Limitações

As limitações a seguir afetam os upgrades de versões principais no local para o AlloyDB:

- Não é possível realizar um upgrade de versão principal no local em um cluster secundário. - Ao fazer um upgrade de versão principal no local, o upgrade de instâncias com mais de 1.000 bancos de dados ou 1 milhão de objetos (como tabelas e visualizações) leva muito tempo e pode expirar. Essa limitação é independente do tamanho real dos dados. - O AlloyDB não é compatível com o upgrade de clusters que usam pg_largeobject_metadata. Se select count(*) from pg_largeobject_metadata; for diferente de zero, o upgrade vai falhar. - O AlloyDB não preserva as associações de papéis em que o concedente original não existe mais. Se o banco de dados tiver essas associações órfãs, resolva-as antes de fazer o upgrade. Para mais informações, consulte Preparar o cluster. - A operação de upgrade da versão principal no local pode ser concluída antes do backup pré-upgrade ou antes da conclusão dos backups pós-upgrade, especialmente quando você tem um banco de dados grande com menos objetos de esquema. - Pode haver um pequeno atraso entre o momento em que as gravações são retomadas na instância atualizada e o momento em que o backup pós-upgrade é criado. Isso significa que o conteúdo do backup pós-upgrade pode não corresponder ao conteúdo do banco de dados de antes do upgrade da versão principal. - Os backups pré-upgrade ainda podem ser criados quando um upgrade de versão principal no local falha. - Como os backups de upgrade automático são contínuos, não é possível excluí-los até que eles atinjam a retenção máxima de backups e recuperação contínuos. Quando a retenção máxima é atingida, os backups são coletados como lixo. Como alternativa, use a CLI gcloud para excluir os backups manualmente. Para mais informações, consulte Restrições para excluir backups.

A seguir