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

Nesta página, descrevemos como fazer um upgrade da versão principal de um banco de dados no local de um cluster do AlloyDB para PostgreSQL. Para saber mais sobre casos de uso, fluxo de trabalho e backups automáticos de upgrade da versão principal do banco de dados no local, consulte Visão geral do upgrade da versão principal do banco de dados no local.

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 console Google Cloud , 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 começar a usar 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 comando a seguir para receber 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 solicitação a seguir para receber 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, macOS ou 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 banco de dados compatíveis com o AlloyDB, consulte Versões de 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_15	POSTGRES_16

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

   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14

4. Identifique incompatibilidades que precisam ser resolvidas. As novas versões principais podem introduzir mudanças incompatíveis que exigem a modificação do código do aplicativo, do esquema ou das 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 comporte conforme o esperado no cluster atualizado.

Preparar o cluster para um upgrade da versão principal

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

• AlloyDB Studio
• psql
• Outros métodos de conexão

1. Remova ou promova suas réplicas entre regiões. Os upgrades in-loco de versão principal 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.

2. Se o cluster do AlloyDB for uma origem de replicação lógica, desative as assinaturas downstream e descarte todos os slots de replicação lógica. Você pode 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 as assinaturas e descartar os slots de replicação lógica, siga estas etapas:

   1. Desative cada assinatura downstream no assinante ou destino de replicação downstream. Não desative as assinaturas de 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 comando a seguir:

        ALTER SUBSCRIPTION SUBSCRIPTION_NAME DISABLE;
        

   2. Exclua 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.

3. 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 ações sugeridas. Para mais informações, consulte Conferir falhas na verificação anterior ao upgrade.

   Talvez seja necessário fazer o seguinte:

   1. Solte 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 na 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

      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();
      

4. Verifique se as conexões são permitidas para cada banco de dados, exceto template0, executando a seguinte consulta 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 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 tamanho do banco de dados, 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 de 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 com um upgrade de versão principal no local.

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

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

Monitorar o upgrade da versão principal do cluster

Depois que o upgrade da versão principal do banco de dados no local for iniciado, monitore o status do upgrade usando o console Google Cloud , a CLI gcloud ou a API REST.

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 permite apenas um upgrade de cluster, então ele 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 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 principais do upgrade.
    • 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.

Confira 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 postgres_upgrade log name.

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

1. No console 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.

Confira 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 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 conferir 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 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 do marcador 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. Consulta de todos os registros 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 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 ele 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. Confira 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 da versão principal no local, siga estas etapas:

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
    

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 o AlloyDB, consulte a documentação dele para instruções de conexão.

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

1. Se você já tiver desativado pglogical, reative a replicação de pglogical. A ativação da replicação 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
      
      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. Atualize as estatísticas do banco de dados.

   Depois que o upgrade for concluído, 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.

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

4. Verifique se a versão principal atualizada do banco de dados no local aparece na página Visão geral do cluster no console 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 à atualização. Para isso, restaure um backup de pré-upgrade, seja aquele que o AlloyDB cria automaticamente durante o processo de upgrade ou um backup de pré-upgrade existente, para criar um novo cluster com o estado de pré-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 de 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. É possível retomar a exibição de tráfego no cluster restaurado.

Também é possível fazer uma recuperação pontual para um momento anterior à atualização. 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.
• O upgrade de instâncias com mais de 1.000 bancos de dados de uma versão para outra pode levar muito tempo e atingir o tempo limite.
• O AlloyDB não oferece suporte a upgrades de clusters que usam pg_largeobject_metadata. Se select count(*) from pg_largeobject_metadata; for diferente de zero, o upgrade vai falhar.
• A operação de upgrade da versão principal no local pode ser concluída antes do backup pré-upgrade ou dos backups pós-upgrade, principalmente 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 a criação do backup pós-upgrade. Isso significa que o conteúdo do backup após o upgrade pode não corresponder ao conteúdo do banco de dados antes do upgrade da versão principal.
• Os backups pré-upgrade ainda podem ser criados quando um upgrade no local de uma versão principal 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 o período máximo de retenção é atingido, os backups são coletados como lixo. Também é possível usar a CLI gcloud para excluir os backups manualmente. Para mais informações, consulte Restrições na exclusão de backups.

A seguir

• Saiba mais sobre os upgrades da versão principal do banco de dados no local.
• Resolver problemas de upgrade de versão principal no local.
• Saiba mais sobre erros de upgrade da versão principal do banco de dados no local.