Atualize a versão principal da base de dados no local

Esta página descreve como atualizar a versão principal da base de dados atualizando a instância do Cloud SQL no local, em vez de migrar dados.

Introdução

Os fornecedores de software de base de dados lançam periodicamente novas versões principais que contêm novas funcionalidades, melhorias de desempenho e melhoramentos de segurança. O Cloud SQL aceita novas versões após o respetivo lançamento. Depois de o Cloud SQL oferecer suporte para uma nova versão principal, pode atualizar as suas instâncias para manter a base de dados atualizada.

Pode atualizar a versão da base de dados de uma instância no local ou migrando os dados. As atualizações no local são uma forma mais simples de atualizar a versão principal da sua instância. Não precisa de migrar dados nem alterar strings de ligação de aplicações. Com as atualizações no local, pode manter o nome, o endereço IP e outras definições da sua instância atual após a atualização. As atualizações no local não exigem que mova ficheiros de dados e podem ser concluídas mais rapidamente. Em alguns casos, o tempo de inatividade é inferior ao que a migração dos seus dados implica.

A operação de atualização no local do Cloud SQL para PostgreSQL usa o utilitário pg_upgrade.

Planeie uma atualização da versão principal

  1. Confirme que tem a função necessária para fazer uma atualização da versão principal: Proprietário do Cloud SQL ou Administrador do Cloud SQL.

  2. Escolha uma versão principal de destino.

    gcloud

    Para informações sobre a instalação e o início da utilização da CLI gcloud, consulte o artigo Instale a CLI gcloud. Para obter informações sobre como iniciar a Cloud Shell, consulte o artigo Use a Cloud Shell.

    Para verificar as versões da base de dados que pode segmentar para uma atualização no local na sua instância, faça o seguinte:

    1. Execute o seguinte comando.
      2. gcloud sql instances describe INSTANCE_NAME

      Substitua INSTANCE_NAME pelo nome da instância.

    2. Na saída do comando, localize a secção com a etiqueta upgradableDatabaseVersions.
    3. Cada subsecção devolve uma versão da base de dados que está disponível para atualização. Em cada subsecção, reveja os seguintes campos.
      • majorVersion: a versão principal que pode segmentar para a atualização no local.
      • name: a string da versão da base de dados que inclui a versão principal.
      • displayName: o nome a apresentar da versão da base de dados.

    REST v1

    Para verificar que versões da base de dados de destino estão disponíveis para uma atualização no local de uma versão principal, use o método instances.get da API Cloud SQL Admin.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar o seu pedido, expanda uma destas opções:

    Deve receber uma resposta JSON semelhante à seguinte:

    
upgradableDatabaseVersions:

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

    REST v1beta4

    Para verificar que versões da base de dados de destino estão disponíveis para a atualização no local da versão principal de uma instância, use o método instances.get da API Admin do Cloud SQL.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar o seu pedido, expanda uma destas opções:

    Deve receber uma resposta JSON semelhante à seguinte:

    
upgradableDatabaseVersions:

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

    Para ver a lista completa das versões de bases de dados suportadas pelo Cloud SQL, consulte o artigo Versões de bases de dados e políticas de versões.

  3. Considere as funcionalidades oferecidas em cada versão principal da base de dados e resolva as incompatibilidades.

    As novas versões principais introduzem alterações incompatíveis que podem exigir que modifique o código da aplicação, o esquema ou as definições da base de dados. Antes de poder atualizar a instância da base de dados, reveja as notas de lançamento da versão principal de destino para determinar as incompatibilidades que tem de resolver.

  4. Teste a atualização com um teste prévio.

    Faça um teste do processo de atualização ponto a ponto num ambiente de teste antes de atualizar a base de dados de produção. Pode clonar a sua instância para criar uma cópia idêntica dos dados nos quais testar o processo de atualização.

    Além de validar se a atualização é concluída com êxito, execute testes para garantir que a aplicação funciona como esperado na base de dados atualizada.

  5. Decida quando fazer a atualização.

    A atualização requer que a instância fique indisponível durante um período. Planeie a atualização durante um período em que a atividade da base de dados seja baixa.

Prepare-se para uma atualização da versão principal

Antes de fazer a atualização, conclua os seguintes passos.

  1. Verifique o valor LC_COLLATE para as bases de dados template e postgres. O conjunto de carateres de cada base de dados tem de ser en_US.UTF8.

    Se o valor LC_COLLATE para as bases de dados template e postgres não for en_US.UTF8, a atualização da versão principal falha. Para corrigir este problema, se qualquer uma das bases de dados tiver um conjunto de carateres diferente de en_US.UTF8, altere o valor de LC_COLLATE para en_US.UTF8 antes de fazer a atualização.

    Para alterar a codificação de uma base de dados:

    1. Despeje a sua base de dados.
    2. Elimine a sua base de dados.
    3. Crie uma nova base de dados com a codificação diferente (para este exemplo, en_US.UTF8).
    4. Atualize os seus dados.

    Outra opção é mudar o nome da base de dados:

    1. Feche todas as ligações à base de dados.
    2. Mude o nome da base de dados.
    3. Atualize as configurações da aplicação para usar o novo nome da base de dados.
    4. Crie uma nova base de dados vazia com a codificação predefinida.

    Recomendamos que execute estes passos numa instância clonada antes de os aplicar a uma instância de produção.

  2. Faça a gestão das extensões do PostgreSQL restantes.

    A maioria das extensões funciona na versão principal atualizada da base de dados. Remova todas as extensões que já não são suportadas na versão de destino. Por exemplo, elimine a extensão chkpass se estiver a atualizar para o PostgreSQL 11 ou versões posteriores.

    Pode atualizar o PostGIS e as respetivas extensões relacionadas para as versões suportadas mais recentes manualmente.

    Por vezes, a atualização das versões 2.x do PostGIS pode criar uma situação em que existem objetos de base de dados residuais que não estão associados à extensão PostGIS. Isto pode bloquear a operação de atualização. Para obter informações sobre a resolução deste problema, consulte o artigo Corrigir uma instalação raster postgis danificada.

    Por vezes, a atualização para a versão 3.1.7 ou posterior do PostGIS não pode ser concluída devido a objetos que usam funções descontinuadas. Isto pode bloquear a operação de atualização. Para verificar o estado da atualização, execute SELECT PostGIS_full_version();. Se existirem avisos, elimine todos os objetos que usem as funções descontinuadas e atualize a extensão PostGIS para qualquer versão intermédia ou superior. Depois de concluir estas ações, execute novamente o comando SELECT PostGIS_full_version();. Verifique se não são apresentados avisos. Em seguida, avance com a operação de atualização.

    Para saber como atualizar as extensões PostGIS, consulte o artigo Atualizar o PostGIS. Para problemas associados à atualização do PostGIS, consulte o artigo Verifique a versão da sua instância do PostgreSQL.
  3. Faça a gestão das suas flags de base de dados personalizadas. Verifique os nomes de quaisquer flags de base de dados personalizadas que configurou para a sua instância do PostgreSQL. Para problemas associados a estas flags, consulte o artigo Verifique as flags personalizadas da sua instância do PostgreSQL.
  4. Quando fizer uma atualização de uma versão principal para outra, tente estabelecer ligação a cada base de dados para ver se existem problemas de compatibilidade. Certifique-se de que as suas bases de dados podem estabelecer ligação entre si. Verifique o campo datallowconn de cada base de dados para garantir que é permitida uma ligação. Um valor t significa que é permitido e um valor f indica que não é possível estabelecer uma ligação.
  5. Se usar a instalação do Datadog para atualizar a sua instância do Cloud SQL para o PostgreSQL 10 ou versões posteriores, antes de fazer a atualização, elimine a função pg_stat_activity().

Limitações conhecidas

As seguintes limitações afetam as atualizações da versão principal no local para o Cloud SQL para PostgreSQL:

  • Não é possível fazer uma atualização da versão principal no local numa réplica externa.
  • A atualização de instâncias com mais de 1000 bases de dados de uma versão para outra pode demorar muito tempo e atingir o limite de tempo.
  • Use a declaração select * from pg_largeobject_metadata; para consultar o número de objetos grandes em cada base de dados PostgreSQL da sua instância do Cloud SQL. Se o resultado de todas as suas bases de dados for superior a 10 milhões de objetos grandes, a atualização falha. O Cloud SQL reverte para a versão anterior da sua base de dados.
  • Antes de fazer uma atualização da versão principal no local para o PostgreSQL 16 e posterior, atualize a extensão PostGIS para todas as suas bases de dados para a versão 3.4.0.
  • Antes de fazer uma atualização da versão principal no local para o PostgreSQL 17, atualize a extensão rdkit para todas as suas bases de dados para a versão 4.6.1.
  • Antes de fazer uma atualização da versão principal no local para o PostgreSQL 16 ou 17, atualize a extensão pg_squeeze para todas as suas bases de dados para a versão 1.6 ou 1.7, respetivamente.
  • Se estiver a usar as versões 9.6, 10, 11 ou 12 do PostgreSQL, a versão 3.4.0 da extensão PostGIS não é suportada. Por conseguinte, para fazer uma atualização da versão principal no local para o PostgreSQL 16 e posterior, tem de atualizar primeiro para uma versão intermédia do PostgreSQL (versões 13, 14 ou 15).

  • Se instalar a extensão pg_ivm para a sua instância, não pode fazer uma atualização da versão principal. Para corrigir este problema, desinstale esta extensão e, em seguida, faça a atualização. Para mais informações sobre as extensões, consulte o artigo Configure extensões do PostgreSQL.

  • Se ativar as flags vacuum_defer_cleanup_age e force_parallel_mode, não pode fazer uma atualização da versão principal. Para corrigir este problema, elimine estas flags e, em seguida, faça a atualização. Para mais informações acerca das flags, incluindo como as eliminar, consulte o artigo Configure flags da base de dados.

Faça a atualização da versão principal

Pode atualizar a versão principal de uma única instância do Cloud SQL ou atualizar a versão principal de uma instância principal e incluir todas as respetivas réplicas na atualização, incluindo réplicas em cascata e réplicas entre regiões.

Atualize a versão principal de uma única instância

Quando inicia uma operação de atualização para uma única instância, o Cloud SQL faz o seguinte:

  1. Verifica a configuração da sua instância para garantir que a instância é compatível com uma atualização.
  2. Depois de o Cloud SQL validar a configuração, o Cloud SQL torna a instância indisponível.
  3. Faz uma cópia de segurança antes da atualização.
  4. Realiza a atualização na instância.
  5. Disponibiliza a sua instância.
  6. Faz uma cópia de segurança após a atualização.

Consola

  1. Na Google Cloud consola, aceda à página Instâncias do Cloud SQL.

    Aceda a Instâncias do Cloud SQL

  2. Para abrir a página Vista geral de uma instância, clique no nome da instância.
  3. Clique em Edit.
  4. Na secção Informações da instância, clique no botão Atualizar e confirme que quer aceder à página de atualização.
  5. Na página Escolha uma versão da base de dados, clique na lista Versão principal da base de dados para atualização e selecione uma das versões principais da base de dados disponíveis.
  6. Clique em Continuar.
  7. Na caixa ID da instância, introduza o nome da instância e, de seguida, clique no botão Iniciar atualização.
A operação demora vários minutos a ser concluída.

Verifique se a versão principal da base de dados atualizada é apresentada abaixo do nome da instância na página Vista geral da instância.

gcloud

  1. Inicie a atualização.

    Use o comando gcloud sql instances patch com a flag --database-version.

    Antes de executar o comando, substitua o seguinte:

    • INSTANCE_NAME: o nome da instância.
    • DATABASE_VERSION: a enumeração para a versão principal da base de dados, que tem de ser posterior à versão atual. Especifique uma versão da base de dados para uma versão principal que esteja disponível como destino de atualização para a instância. Pode obter esta enumeração como o primeiro passo do Plan for upgrade. Se precisar de uma lista completa de enumerações de versões de bases de dados, consulte SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    As atualizações de versões principais demoram vários minutos a serem concluídas. Pode ver uma mensagem a indicar que a operação está a demorar mais do que o esperado. Pode ignorar esta mensagem ou executar o comando gcloud sql operations wait para ignorar a mensagem.

  2. Obtenha o nome da operação de atualização.

    Use o comando gcloud sql operations list com a flag --instance.

    Antes de executar o comando, substitua a variável INSTANCE_NAME pelo nome da instância. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitorize o estado da atualização.

    Use o comando gcloud sql operations describe.

    Antes de executar o comando, substitua a variável OPERATION pelo nome da operação de atualização obtido no passo anterior. 

    gcloud sql operations describe OPERATION

REST v1

  1. Inicie a atualização no local.

    Use um pedido PATCH com o método instances:patch.

    Antes de usar qualquer um dos dados do pedido, substitua estas variáveis:

    • PROJECT_ID: o ID do projeto.
    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Corpo JSON do pedido: 

    {
  "databaseVersion": DATABASE_VERSION
}

    Substitua DATABASE_VERSION pela enumeração da versão principal da base de dados, que tem de ser posterior à versão atual. Especifique uma versão da base de dados para uma versão principal que esteja disponível como destino de atualização para a instância. Pode obter esta enumeração como o primeiro passo do Plan for upgrade. Se precisar de uma lista completa de enumerações de versões da base de dados, consulte SqlDatabaseVersion.

  2. Obtenha o nome da operação de atualização.

    Use um pedido GET com o método operations.list depois de substituir PROJECT_ID pelo ID do projeto.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitorize o estado da atualização.

    Use um pedido GET com o método operations.get depois de substituir as seguintes variáveis:

    • PROJECT_ID: o ID do projeto.
    • OPERATION_NAME: o nome da operação de atualização obtido no passo anterior.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Para atualizar a versão da base de dados, use um recurso do Terraform e o fornecedor do Terraform para Google Cloud, versão 4.34.0 ou posterior.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Aplique as alterações

Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

    Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

  1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

    Copie o exemplo de código para o ficheiro main.tf criado recentemente.

    Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

  3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
  4. Guarde as alterações.
  5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
    terraform plan

    Faça as correções necessárias à configuração.

  2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando: 
    terraform apply

    Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

  3. Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

Eliminar as alterações

Para eliminar as alterações, faça o seguinte:

  1. Para desativar a proteção contra eliminação, no ficheiro de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Aplique a configuração do Terraform atualizada executando o seguinte comando e introduzindo yes no comando: 
    terraform apply

  1. Remova os recursos aplicados anteriormente com a sua configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

    terraform destroy

Quando envia um pedido de atualização no local, o Cloud SQL executa primeiro uma verificação pré-atualização. Se o Cloud SQL determinar que a sua instância não está preparada para uma atualização, o pedido de atualização falha com uma mensagem que sugere como pode resolver o problema. Consulte também o artigo Resolva problemas de uma atualização de versão principal.

Inclua réplicas na atualização da versão principal

Se a sua instância principal tiver réplicas, pode incluir todas as réplicas na atualização. O Cloud SQL pode atualizar todas as réplicas da instância principal, incluindo réplicas entre regiões e réplicas em cascata.

Quando inclui réplicas numa atualização da versão principal, o Cloud SQL faz o seguinte:

  1. Verifica a configuração da instância principal e das réplicas para garantir que a instância e as réplicas são compatíveis para uma atualização.
  2. Torna a sua instância principal indisponível.
  3. Cria uma cópia de segurança pré-atualização da instância principal.
  4. Interrompe a replicação para todas as réplicas.
  5. Realiza a atualização na instância principal.
  6. Se a atualização na instância principal for bem-sucedida, a instância principal fica novamente disponível e reinicia a replicação.
  7. O Cloud SQL faz uma cópia de segurança pós-atualização da instância principal.
  8. O Cloud SQL prossegue com a atualização de todas as réplicas.

Mesmo que a atualização da versão principal de uma réplica falhe, a instância principal continua disponível.

Para incluir réplicas numa atualização de versão principal, não pode usar aGoogle Cloud consola nem o Terraform. Só pode usar a CLI gcloud ou a API Admin do Cloud SQL.

gcloud

  1. Inicie a atualização.

    Use o comando gcloud sql instances patch com as flags --database-version e --include-replicas-for-major-version-upgrade.

    Antes de executar o comando, substitua o seguinte:

    • INSTANCE_NAME: o nome da instância principal.
    • DATABASE_VERSION: a enumeração para a versão principal da base de dados, que tem de ser posterior à versão atual. Especifique uma versão da base de dados para uma versão principal que esteja disponível como destino de atualização para a instância. Pode obter esta enumeração como o primeiro passo do Plan for upgrade. Se precisar de uma lista completa de enumerações de versões de bases de dados, consulte SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --include-replicas-for-major-version-upgrade

    As atualizações de versões principais demoram vários minutos a serem concluídas. Pode ver uma mensagem a indicar que a operação está a demorar mais do que o esperado. Pode ignorar esta mensagem ou executar o comando gcloud sql operations wait para ignorar a mensagem. A atualização de réplicas pode demorar vários minutos a ser concluída. Para verificar o estado da atualização, faça o seguinte:

  2. Obtenha o nome da operação de atualização.

    Use o comando gcloud sql operations list com a flag --instance.

    Antes de executar o comando, substitua a variável INSTANCE_NAME pelo nome da instância. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitorize o estado da atualização.

    Use o comando gcloud sql operations describe.

    Antes de executar o comando, substitua a variável OPERATION pelo nome da operação de atualização obtido no passo anterior. 

    gcloud sql operations describe OPERATION

REST

  1. Inicie a atualização no local.

    Use um pedido PATCH com o método instances:patch.

    Antes de usar qualquer um dos dados do pedido, substitua estas variáveis:

    • PROJECT_ID: o ID do projeto.
    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Corpo JSON do pedido: 

    {
  "databaseVersion": DATABASE_VERSION
  "includeReplicasForMajorVersionUpgrade": true
}

    • Substitua DATABASE_VERSION pela enumeração da versão principal da base de dados, que tem de ser posterior à versão atual. Especifique uma versão da base de dados para uma versão principal que esteja disponível como destino de atualização para a instância. Pode obter esta enumeração como o primeiro passo do Plan for upgrade. Se precisar de uma lista completa de enumerações de versões da base de dados, consulte SqlDatabaseVersion.
    • No campo includeReplicasForMajorVersionUpgrade, especifique true.

  2. Obtenha o nome da operação de atualização.

    Use um pedido GET com o método operations.list depois de substituir PROJECT_ID pelo ID do projeto.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitorize o estado da atualização.

    Use um pedido GET com o método operations.get depois de substituir as seguintes variáveis:

    • PROJECT_ID: o ID do projeto.
    • OPERATION_NAME: o nome da operação de atualização obtido no passo anterior.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Cópias de segurança de atualizações automáticas

Quando faz uma atualização da versão principal, o Cloud SQL faz automaticamente duas cópias de segurança a pedido, denominadas cópias de segurança de atualização:

  • A primeira cópia de segurança da atualização é a cópia de segurança pré-atualização, que é feita imediatamente antes de iniciar a atualização. Pode usar esta cópia de segurança para restaurar a instância da base de dados para o estado em que se encontrava na versão anterior.
  • A segunda cópia de segurança da atualização é a cópia de segurança pós-atualização, que é feita imediatamente após serem permitidas novas gravações na instância da base de dados atualizada.

Quando vê a sua lista de cópias de segurança, as cópias de segurança de atualização são apresentadas com o tipo On-demand. As atualizações das cópias de segurança são etiquetadas para que as possa identificar rapidamente. Por exemplo, se estiver a atualizar do PostgreSQL 14 para o PostgreSQL 15, a cópia de segurança pré-atualização é etiquetada como Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. e a cópia de segurança pós-atualização é etiquetada como Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

Tal como acontece com outras cópias de segurança a pedido, as cópias de segurança de atualização persistem até as eliminar ou eliminar a instância. Se tiver a PITR ativada, não pode eliminar as cópias de segurança de atualização enquanto estiverem no período de retenção. Se precisar de eliminar as cópias de segurança da atualização, tem de desativar a PITR ou aguardar até que as cópias de segurança da atualização deixem de estar no período de retenção.

Conclua a atualização da versão principal

Depois de concluir a atualização da instância principal, siga os passos seguintes para concluir a atualização:

  1. Atualizar as estatísticas da base de dados.

    Execute ANALYZE na instância principal para atualizar as estatísticas do sistema após a atualização. As estatísticas precisas garantem que o planeador de consultas do PostgreSQL processa as consultas de forma ideal. As estatísticas em falta podem originar planos de consultas incorretos, que, por sua vez, podem degradar o desempenho e ocupar memória excessiva.

  2. Realize testes de aceitação.

    Execute testes para se certificar de que o sistema atualizado tem o desempenho esperado.

Resolva problemas com uma atualização da versão principal

O Cloud SQL devolve uma mensagem de erro se tentar executar um comando de atualização inválido, por exemplo, se a sua instância contiver flags de base de dados inválidas para a nova versão.

Se o seu pedido de atualização falhar, verifique a sintaxe do pedido de atualização. Se o pedido tiver uma estrutura válida, experimente as seguintes sugestões.

Veja as falhas na verificação pré-atualização

As falhas na verificação pré-atualização são problemas ou erros que o Cloud SQL deteta durante o processo de verificação ou validação pré-atualização. Estas falhas ocorrem antes do início do processo de atualização real e destinam-se a identificar potenciais problemas ou incompatibilidades que podem afetar o sucesso da atualização.

As falhas na verificação pré-atualização são apresentadas para as seguintes categorias:

  • Extensões incompatíveis: detete extensões do PostgreSQL que não são compatíveis com a versão de destino da instância.
  • Dependências não suportadas: identifique dependências que já não são suportadas ou que têm de ser atualizadas.
  • Incompatibilidades de formato de dados: verifique as inconsistências de dados que surgem devido a vários fatores, incluindo diferenças nas estruturas de dados específicas da versão, alterações na codificação e na ordenação, modificações nos tipos de dados e ajustes ao catálogo do sistema.

A tabela seguinte apresenta as falhas de verificação pré-atualização e as respetivas mensagens de erro:

Falha na verificação pré-atualização Mensagem de erro
O Cloud SQL deteta um tipo de dados desconhecido. Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Quando atualiza para o PostgreSQL 12 ou versões posteriores, o Cloud SQL deteta o tipo de dados 'sql_identifier'. Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
O Cloud SQL deteta o tipo de dados reg*. Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
O Cloud SQL deteta que o valor
LC_COLLATE para a base de dados postgres é um conjunto de carateres diferente de en_US.UTF8.		 Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
O Cloud SQL deteta tabelas que têm identificadores de objetos (OIDs). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
O Cloud SQL deteta tipos de dados compostos. Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
O Cloud SQL deteta operadores postfix definidos pelo utilizador. Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name)
O Cloud SQL deteta funções polimórficas incompatíveis. Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name)
O Cloud SQL deteta conversões de codificação definidas pelo utilizador. Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name)
O Cloud SQL deteta um caminho de pesquisa vazio para a função ll_to_earth Please update the search path of the 'll_to_earth' function
O Cloud SQL deteta a presença de ficheiros raster PostGIS descomprimidos. PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade.

Corrija o problema do caminho de pesquisa vazio

Isto acontece porque a extensão earthdistance usa tipos de terra e cubo sem especificar o caminho de pesquisa da função. Tem de especificar este caminho, que é necessário durante o processo de atualização.

Para evitar este problema, o Cloud SQL executa uma verificação pré-atualização automática que verifica se a função ll_to_earth tem uma definição search_path para garantir que as respetivas dependências podem ser resolvidas. Se não for definido nenhum search_path específico da função, a verificação falha com a seguinte mensagem de erro:

Please update the search path of the 'll_to_earth' function
(database: [your-db], search path: )

Para resolver este problema, corrija o caminho de pesquisa da função ll_to_earth executando esta consulta: ALTER FUNCTION ll_to_earth SET search_path = public;

Veja registos de erros

Se ocorrerem problemas com um pedido de atualização válido, o Cloud SQL publica registos de erros em projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Cada entrada do registo contém uma etiqueta com o identificador da instância para ajudar a identificar a instância com o erro de atualização. Procure esses erros de atualização e resolva-os.

Para ver os registos de erros, use a Google Cloud consola::

  1. Na Google Cloud consola, aceda à página Instâncias do Cloud SQL.

    Aceda a Instâncias do Cloud SQL

  2. Para abrir a página Vista geral de uma instância, clique no nome da instância.

  3. No painel Operações e registos da página Vista geral da instância, clique no link Ver registos de erros do PostgreSQL.

    É apresentada a página Explorador de registos.

  4. Veja os registos da seguinte forma:

    • Para listar todos os registos de erros num projeto, selecione o nome do registo no filtro de registo Nome do registo.

    Para mais informações sobre filtros de consultas, consulte o artigo Consultas avançadas.

    • Para filtrar os registos de erros de atualização de uma única instância, introduza a seguinte consulta na caixa Pesquisar todos os campos, depois de substituir DATABASE_ID

    com o ID do projeto seguido do nome da instância neste 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 exemplo, para filtrar os registos de erros de atualização por uma instância denominada shopping-db em execução no projeto buylots, use o seguinte filtro de consulta:

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

    Pode rever todos os registos comunicados num determinado período ou filtrar os registos por gravidade. Uma opção comum para a resolução de problemas pode incluir a seleção dos seguintes filtros:

    • Emergência
    • Alerta
    • Crítico
    • Erro

As entradas de registo com o prefixo pg_upgrade_dump indicam que ocorreu um erro de atualização. Por exemplo:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

Além disso, as entradas de registo etiquetadas com um nome de ficheiro secundário .txt podem apresentar outros erros que pode querer resolver antes de tentar a atualização novamente.

Todos os nomes de ficheiros encontram-se no ficheiro postgres-upgrade.log. Para localizar um nome de ficheiro, consulte o campo labels.FILE_NAME.

Os nomes de ficheiros que podem conter erros a resolver incluem:

  • tables_with_oids.txt: Este ficheiro contém tabelas que estão listadas com identificadores de objetos (OIDs). Elimine as tabelas ou modifique-as para que não usem OIDs.
  • tables_using_composite.txt: Este ficheiro contém tabelas que estão listadas através de tipos compostos definidos pelo sistema. Elimine as tabelas ou modifique-as para que não usem estes tipos compostos.
  • tables_using_unknown.txt: Este ficheiro contém tabelas que são apresentadas através do tipo de dados UNKNOWN. Elimine as tabelas ou modifique-as para que não usem este tipo de dados.
  • tables_using_sql_identifier.txt: Este ficheiro contém tabelas que são apresentadas através do tipo de dados SQL_IDENTIFIER. Elimine as tabelas ou modifique-as para que não usem este tipo de dados.
  • tables_using_reg.txt: Este ficheiro contém tabelas que estão listadas com o tipo de dados REG* (por exemplo, REGCOLLATION ou REGNAMESPACE). Elimine as tabelas ou modifique-as para que não usem este tipo de dados.
  • postfix_ops.txt: Este ficheiro contém tabelas listadas com operadores de sufixo (unários à direita). Elimine as tabelas ou modifique-as para que não usem estes operadores.

Verifique a memória

Se a instância tiver memória partilhada insuficiente, pode ver esta mensagem de erro: ERROR: out of shared memory. É mais provável que este erro ocorra se tiver mais de 10 000 tabelas.

Antes de tentar uma atualização, defina o valor da flag max_locks_per_transaction para aproximadamente o dobro do número de tabelas na instância. A instância é reiniciada quando altera o valor deste sinalizador.

Verifique a capacidade das ligações

Se a sua instância tiver uma capacidade de ligação insuficiente, pode ver esta mensagem de erro: ERROR: Insufficient connections.

O Cloud SQL recomenda que aumente o valor da flag max_connections pelo número de bases de dados na sua instância. A instância é reiniciada quando altera o valor deste sinalizador.

Verifique se existe uma referência de coluna ambígua

O Cloud SQL executa automaticamente uma verificação pré-atualização para identificar vistas definidas pelo utilizador que dependem de vistas do catálogo do sistema, como pg_stat_activity ou pg_stat_replication. A estrutura das colunas destas vistas do catálogo do sistema pode mudar entre as versões principais do PostgreSQL. Se tiver vistas que select * ou dependam da ordem das colunas destas vistas do sistema, podem tornar-se incompatíveis após uma atualização, o que resulta num erro, como ERROR: column reference "column_name" is ambiguous.

A verificação pré-atualização deteta essas vistas verificando as dependências. Se forem encontradas visualizações incompatíveis, o processo de atualização é interrompido e é apresentada uma mensagem de erro. Esta mensagem apresenta as vistas incompatíveis em cada base de dados que têm de ser resolvidas.

Exemplo de mensagem de erro

  • Para problemas relacionados com pg_stat_activity: 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • Para problemas relacionados com pg_stat_replication:

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

Para resolver estes problemas e continuar com a atualização: 1. Identifique as visualizações indicadas na mensagem de erro da verificação pré-atualização.

  1. Elimine estas vistas com o DROP VIEW view_name;.

  2. Volte a tentar a atualização da versão principal.

  3. Quando a atualização estiver concluída, recrie as vistas. Certifique-se de que as novas definições de visualização são compatíveis com o esquema das visualizações do catálogo do sistema na versão atual do PostgreSQL. Pode ter de listar explicitamente as colunas em vez de usar select * para evitar problemas futuros.

Para ver um exemplo mais detalhado do problema e mais estatísticas, consulte esta discussão no Stack Overflow

Verifique se existem SRFs em declarações CASE

Se estiver a atualizar a sua instância a partir da versão 9.6 e a usar funções de devolução definidas nas suas declarações CASE, pode ver esta mensagem de erro ERROR: set-returning functions are not allowed in CASE. Este problema ocorre porque, a partir da versão 10, a utilização de funções de devolução de conjuntos em instruções CASE não é permitida.

Para resolver este problema e atualizar a sua instância com êxito, certifique-se de que todas as declarações CASE que usam funções de devolução de conjuntos são modificadas para evitar a sua utilização antes de tentar novamente a atualização. Seguem-se alguns SRFs usados frequentemente:

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

Verifique as visualizações criadas em transmissões personalizadas

Se tiver uma visualização criada num elenco personalizado, é apresentada uma mensagem de erro semelhante à seguinte: ERROR: cannot cast type <type_1> to <type_2>. Este problema ocorre devido a problemas de autorização em transmissões criadas personalizadamente.

Para resolver este problema, atualize a sua instância para a versão [PostgreSQL version].R20240910.01_02

Para mais informações, consulte o artigo Manutenção self-service.

Verifique a propriedade do acionador de eventos

No Cloud SQL, todos os acionadores de eventos têm de ser propriedade de um utilizador com a função cloudsqlsuperuser. O Cloud SQL executa uma verificação pré-atualização para validar a propriedade de todos os acionadores de eventos. Se um acionador de evento for propriedade de um utilizador que não tem a função cloudsqlsuperuser, o processo de atualização é interrompido e pode receber uma mensagem de erro, como:

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

Para resolver este problema, altere o proprietário do acionador de eventos para um utilizador que tenha a função cloudsqlsuperuser, como postgres, ou conceda a função cloudsqlsuperuser ao proprietário atual.

Para identificar acionadores de eventos com proprietários que não têm a função necessária, execute o seguinte comando:

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

Os resultados mostram qualquer acionador de eventos com um proprietário que não tenha a função cloudsqlsuperuser.

Verifique as colunas geradas a partir de tabelas não registadas

Se tiver uma tabela não registada com colunas geradas, pode ver a mensagem de erro ERROR: unexpected request for new relfilenumber in binary upgrade mode. Este problema ocorre devido a discrepâncias nas caraterísticas de persistência entre as tabelas e as respetivas sequências para colunas geradas.

Para resolver este problema, faça o seguinte:

  1. Elimine tabelas não registadas: se possível, elimine todas as tabelas não registadas associadas a colunas geradas. Certifique-se de que a perda de dados pode ser mitigada em segurança antes de continuar.
  2. Converta em tabelas permanentes: converta temporariamente tabelas não registadas em tabelas permanentes através dos seguintes passos:
    1. Converta a tabela numa tabela registada ALTER TABLE SET LOGGED;
    2. Faça a atualização da versão principal
    3. Converta a tabela novamente numa tabela não registada ALTER TABLE SET UNLOGGED

Pode identificar todas estas tabelas através da seguinte consulta :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

Verifique as flags personalizadas da sua instância do PostgreSQL

Se estiver a atualizar para uma instância do PostgreSQL, versão 14 ou superior, verifique os nomes de quaisquer indicadores da base de dados personalizados que configurou para a instância. Isto acontece porque o PostgreSQL impôs restrições adicionais aos nomes permitidos para parâmetros personalizados.

O primeiro caráter de uma flag de base de dados personalizada tem de ser alfabético (A-Z ou a-z). Todos os carateres subsequentes podem ser alfanuméricos, o carater especial de sublinhado (_) ou o carater especial de cifrão ($).

Remova extensões

Se estiver a atualizar a sua instância do Cloud SQL, pode ver esta mensagem de erro: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Para resolver este problema, siga estes passos:

  1. Remova as extensões pg_stat_statements e pgstattuple.
  2. Faça a atualização.
  3. Reinstale as extensões.

Restaure a instância principal para a versão principal anterior

Se o sistema de base de dados atualizado não tiver o desempenho esperado, pode ter de restaurar a instância principal para a versão anterior. Para tal, restaure a cópia de segurança anterior à atualização para uma instância de recuperação do Cloud SQL, que é uma nova instância que executa a versão anterior à atualização.

Para restaurar uma instância principal para a versão anterior, siga estes passos:

  1. Identifique a cópia de segurança anterior à atualização.

    Consulte o artigo Cópias de segurança de atualizações automáticas.

  2. Crie uma instância de recuperação.

    Crie uma nova instância do Cloud SQLcom a versão principal que o Cloud SQL estava a executar quando foi feita a cópia de segurança pré-atualização. Defina as mesmas sinalizações e definições de instância que a instância original usa.

  3. Restaure a cópia de segurança anterior à atualização.

    Restaure a cópia de segurança anterior à atualização na instância de recuperação. Este processo pode demorar alguns minutos.

  4. Adicione as réplicas de leitura.

    Se estiver a usar réplicas de leitura, adicione-as individualmente.

  5. Associe a sua aplicação.

    Depois de recuperar o sistema de base de dados, atualize a aplicação com detalhes sobre a instância de recuperação e as respetivas réplicas de leitura. Pode retomar a publicação de tráfego na versão anterior à atualização da sua base de dados.

Perguntas frequentes

As seguintes perguntas podem surgir quando atualizar a versão principal da base de dados.

A minha instância fica indisponível durante uma atualização?
Sim. A sua instância permanece indisponível durante um período enquanto o Cloud SQL realiza a atualização.
Quanto tempo demora uma atualização?

Normalmente, a atualização de uma única instância demora menos de 10 minutos. Se a configuração da instância tiver um número reduzido de vCPUs ou memória, a atualização pode demorar mais tempo.

Se a sua instância alojar demasiadas bases de dados ou tabelas, ou se as suas bases de dados forem muito grandes, a atualização pode demorar horas ou até expirar, uma vez que o tempo total de atualização corresponde ao número de objetos nas suas bases de dados. Se tiver várias instâncias que precisam de ser atualizadas, o tempo de atualização aumenta proporcionalmente. Se incluir réplicas na atualização, a operação de atualização pode demorar até uma hora a ser concluída, consoante o número de réplicas que a instância principal tem.

Posso monitorizar cada passo no meu processo de atualização?
Embora o Cloud SQL lhe permita monitorizar se uma operação de atualização ainda está em curso, não pode acompanhar os passos individuais em cada atualização.
Posso cancelar a atualização depois de a iniciar?
Não, não pode cancelar uma atualização depois de esta ter começado. Se a atualização falhar, o Cloud SQL recupera automaticamente a sua instância na versão anterior.
O que acontece às minhas definições durante uma atualização?

Quando faz uma atualização da versão principal no local, o Cloud SQL retém as definições da base de dados, incluindo o nome da instância, o endereço IP, os valores de flags configurados explicitamente e os dados do utilizador. No entanto, o valor predefinido das variáveis do sistema pode mudar. Por exemplo, o valor predefinido da flag password_encryption no PostgreSQL 13 e anterior é md5. Quando atualiza para o PostgreSQL 14, o valor predefinido deste sinalizador é alterado para scram-sha-256.

Para saber mais, consulte o artigo Configure flags da base de dados. Se uma determinada flag ou valor deixar de ser suportado na versão de destino, o Cloud SQL remove automaticamente a flag durante a atualização.

O que se segue?