Atualizar a versão principal do banco de dados no local

Nesta página, descrevemos como fazer upgrade da versão principal do banco de dados fazendo upgrade da instância do Cloud SQL no local, em vez de migrar os dados.

Introdução

Os provedores de software de banco de dados lançam periodicamente novas versões principais que contêm novos recursos, melhorias de desempenho e melhorias de segurança. O Cloud SQL recebe novas versões após o lançamento delas. Depois que o Cloud SQL passar a oferecer suporte para uma nova versão principal, será possível fazer upgrade das instâncias para manter o banco de dados atualizado.

Para fazer upgrade da versão do banco de dados de uma instância no local, basta migrar os dados. Os upgrades no local são uma maneira mais simples de fazer upgrade da versão principal da instância. Não é necessário migrar os dados ou mudar as strings de conexão do aplicativo. Com os upgrades no local, é possível manter o nome, o endereço IP e outras configurações da instância atual após o upgrade. Os upgrades no local não exigem a movimentação de arquivos de dados e podem ser concluídos mais rapidamente. Em alguns casos, o tempo de inatividade é menor do que o exigido pela migração de dados.

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

Planejar um upgrade da versão principal

  1. Escolha uma versão principal de destino.

    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.

    Para verificar as versões do banco de dados que podem ser segmentadas para um upgrade no local da sua instância, faça o seguinte:

    1. Execute o comando a seguir.
      2. gcloud sql instances describe INSTANCE_NAME

      Substitua INSTANCE_NAME pelo nome da instância.

    2. Na saída do comando, localize a seção identificada como upgradableDatabaseVersions.
    3. Cada subseção retorna uma versão do banco de dados disponível para upgrade. Em cada subseção, revise os seguintes campos.
      • majorVersion: a versão principal que pode ser segmentada para o upgrade no local.
      • name: a string da versão do banco de dados que inclui a versão principal.
      • displayName: o nome de exibição da versão do banco de dados.

    REST v1

    Para verificar quais versões do banco de dados de destino estão disponíveis para um upgrade no local de uma versão principal, use o método instances.get da API Cloud SQL Admin.

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

    • 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 a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    
upgradableDatabaseVersions:

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

    REST v1beta4

    Para verificar quais versões do banco de dados de destino estão disponíveis para os principais upgrades de versão no local de uma instância, use o Método instances.get da API Cloud SQL Admin.

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

    • 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 a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    
upgradableDatabaseVersions:

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

    Para ver a lista completa das versões de bancos de dados com suporte do Cloud SQL, consulte Versões do banco de dados e políticas de versão.

  2. Considere os recursos oferecidos em cada versão principal do banco de dados e as incompatibilidades de endereço.

    As novas versões principais apresentam 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. Antes de fazer upgrade da instância do banco de dados, analise as notas da versão principal de destino para determinar as incompatibilidades que você precisa resolver.

  3. Teste o upgrade com uma simulação.

    Faça uma simulação do processo de upgrade de ponta a ponta em um ambiente de teste antes de fazer upgrade do banco de dados de produção. Você pode clonar sua instância para criar uma cópia idêntica dos dados em que o processo de upgrade será testado.

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

  4. Escolha um horário para o upgrade.

    O upgrade exige que a instância fique indisponível por um período. Planeje o upgrade durante um período em que a atividade do banco de dados estiver baixa.

Preparar-se para um upgrade de versão principal

Antes de fazer upgrade, siga estas etapas.

  1. Verifique o valor LC_COLLATE para os bancos de dados template e postgres. O conjunto de caracteres para cada banco de dados precisa ser en_US.UTF8.

    Se o valor de LC_COLLATE para os bancos de dados template e postgres não for en_US.UTF8, o upgrade da versão principal falhará. Para corrigir isso, se algum dos bancos de dados tiver um conjunto de caracteres diferente de en_US.UTF8, altere o valor LC_COLLATE para en_US.UTF8 antes de realizar o upgrade.

    Para alterar a codificação de um banco de dados:

    1. Despeje o banco de dados.
    2. Remova o banco de dados.
    3. Crie um novo banco de dados com uma codificação diferente. Neste exemplo, en_US.UTF8.
    4. Recarregue os dados.

    Outra opção é renomear o banco de dados:

    1. Feche todas as conexões ao banco de dados.
    2. Renomeie o banco de dados.
    3. Atualize as configurações do aplicativo para usar o novo nome do banco de dados.
    4. Crie um banco de dados vazio com a codificação padrão.

    Recomendamos que você execute essas etapas em uma instância clonada antes de aplicá-las a uma instância de produção.

  2. Gerencie suas réplicas de leitura.

    O Cloud SQL para PostgreSQL não é compatível com a replicação de várias versões. Isso significa que não é possível fazer upgrade da instância principal enquanto a instância estiver se replicando para as réplicas de leitura. Antes de fazer upgrade, desative a replicação para cada réplica de leitura ou exclua as réplicas de leitura.

  3. Se o Cloud SQL for a origem de replicação lógica, desative a replicação de extensão pglogical da seguinte maneira. É possível ativá-la novamente após o upgrade. Se o Cloud SQL for o destino de replicação lógica, essas etapas não serão necessárias.
    1. Desative a assinatura e desconecte a réplica do provedor usando o seguinte comando: 
      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      Substitua name pelo nome da assinatura atual.

      Defina o valor do parâmetro immediate como true se a assinatura precisar ser desativada imediatamente. 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)
    2. Solte o slot de replicação. Para isso, conecte-se ao editor ou à instância principal do Cloud SQL e execute o seguinte comando: 
      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
  WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      Exemplo:

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
-[ RECORD 1 ]------------+-
pg_drop_replication_slot |

postgres=>

  4. Gerencie suas extensões do PostgreSQL restantes.

    A maioria das extensões funciona na versão principal atualizada do banco de dados. Solte as extensões que não são mais compatíveis com sua versão de destino. Por exemplo, solte a extensão chkpass se estiver fazendo upgrade para o PostgreSQL 11 ou versões mais recentes.

    É possível fazer upgrade do PostGIS e das extensões relacionadas manualmente para as versões compatíveis mais recentes.

    Às vezes, o upgrade do PostGIS versão 2.x pode criar uma situação em que há objetos de banco de dados restantes que não estão associados à extensão PostGIS. Isso pode bloquear a operação de upgrade. Para mais informações sobre como resolver esse problema, consulte Como corrigir a instalação de uma varredura do Postgis.

    Às vezes, não é possível concluir o upgrade para o PostGIS versão 3.1.7 ou posterior devido a objetos que usam funções descontinuadas. Isso pode bloquear a operação de upgrade. Para verificar o status do upgrade, execute SELECT PostGIS_full_version();. Se houver avisos, exclua todos os objetos que usam as funções descontinuadas e atualize a extensão PostGIS para uma versão intermediária ou mais recente. Depois de concluir essas ações, execute o comando SELECT PostGIS_full_version(); novamente. Verifique se nenhum aviso é exibido. Em seguida, continue com a operação de upgrade.

    Para saber mais sobre como fazer upgrade das extensões PostGIS, consulte Como fazer upgrade do PostGIS. Para problemas associados ao upgrade do PostGIS, consulte Verificar a versão da instância do PostgreSQL.
  5. Gerencie suas sinalizações personalizadas de banco de dados. Verifique os nomes de qualquer sinalização personalizada de banco de dados configurada para a instância do PostgreSQL. Para problemas associados a essas sinalizações, consulte Verificar as sinalizações personalizadas da instância do PostgreSQL.
  6. Ao fazer upgrade de uma versão principal para outra, tente se conectar a cada banco de dados para ver se há algum problema de compatibilidade. Verifique se os bancos de dados podem se conectar uns aos outros. Verifique o campo datallowconn de cada banco de dados para garantir que uma conexão seja permitida. Um valor t significa que ele é permitido, e um valor f indica que não é possível estabelecer uma conexão.
  7. Se você usar a instalação do Datadog para fazer upgrade da sua instância do Cloud SQL para o PostgreSQL 10 ou versões posteriores, antes de realizar o upgrade, descarte a função pg_stat_activity().

Limitações conhecidas

As limitações a seguir afetam os upgrades de versões principais do local para o Cloud SQL para PostgreSQL:

  • Não é possível realizar um upgrade de versão principal no local em uma réplica externa.
  • O upgrade de instâncias com mais de 1.000 bancos de dados de uma versão para outra pode demorar muito e expirar.
  • Use a instrução select * from pg_largeobject_metadata; para consultar o número de objetos grandes em cada banco de dados PostgreSQL da instância do Cloud SQL. Se o resultado de todos os seus bancos de dados for mais de 10 milhões de objetos grandes, o upgrade falhará. O Cloud SQL reverte para a versão anterior do banco de dados.
  • Antes de fazer um upgrade local da versão principal para o PostgreSQL 16 e versões mais recentes, faça upgrade da extensão PostGIS de todos os seus bancos de dados para a versão 3.4.0.
  • Se você estiver usando as versões 9.6, 10, 11 ou 12 do PostgreSQL, a versão 3.4.0 da extensão PostGIS não será compatível. Portanto, para realizar um upgrade de versão principal no local para o PostgreSQL 16 e versões mais recentes, primeiro é necessário fazer upgrade para uma versão intermediária do PostgreSQL (versões 13, 14 ou 15).

  • Se você instalar as extensões pgRouting e pg_squeeze na sua instância, não será possível fazer upgrade da versão principal. Para corrigir isso, desinstale essas extensões e faça o upgrade. Para mais informações sobre as extensões, consulte Configurar extensões do PostgreSQL.

  • Se você ativar as sinalizações vacuum_defer_cleanup_age e force_parallel_mode, não será possível fazer upgrade da versão principal. Para corrigir isso, exclua essas flags e faça o upgrade. Para mais informações sobre as flags, incluindo como excluí-las, consulte Configurar flags do banco de dados.

Atualizar a versão principal do banco de dados no local

Quando você inicia uma operação de upgrade, o Cloud SQL verifica primeiro a configuração da sua instância para garantir que ela seja compatível com um upgrade. Depois de verificar a configuração, o Cloud SQL disponibiliza a instância, faz um backup pré-upgrade, executa o upgrade, disponibiliza a instância e depois faz um backup pós-upgrade.

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse Instâncias do Cloud SQL

  2. Para abrir a página Visão geral de uma instância, clique no nome dela.
  3. Clique em Editar.
  4. Na seção Informações da instância, clique no botão Fazer upgrade e confirme que você quer acessar a página de upgrade.
  5. Na página Escolha uma versão de banco de dados, clique no campo Versão do banco de dados para upgrade e selecione uma das versões principais disponíveis do banco de dados.
  6. Clique em Continuar.
  7. Na caixa ID da instância, insira o nome da instância e clique no botão Iniciar upgrade.
A consulta leva alguns minutos para ser concluída.

Verifique se a versão principal atualizada do banco de dados aparece abaixo do nome da instância na página Visão geral da instância.

gcloud

  1. Iniciar o upgrade.

    Use o comando gcloud sql instances patch com a sinalização --database-version.

    Antes de executar o comando, substitua o seguinte:

    • INSTANCE_NAME: o nome da instância
    • DATABASE_VERSION: o tipo enumerado da versão principal do banco de dados, que precisa ser superior à versão atual. Especificar uma versão do banco de dados para uma versão principal disponível como um upgrade para a instância. Esse tipo enumerado pode ser obtido como a primeira etapa para Planejar o upgrade. Se você precisar de uma lista completa de tipos enumerados de versão do banco de dados, consulte SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Os upgrades das versões principais levam vários minutos para serem concluídos. Talvez você veja uma mensagem indicando que a operação está demorando mais que o esperado. Você pode ignorar essa mensagem ou executar o comando gcloud sql operations wait para dispensá-la.

  2. Recebe o nome da operação de upgrade.

    Use o comando gcloud sql operations list com a sinalização --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. Monitore o status do upgrade.

    Use o comando gcloud sql operations describe:

    Antes de executar o comando, substitua a variável OPERATION pelo nome da operação de upgrade recuperada na etapa anterior. 

    gcloud sql operations describe OPERATION

REST v1

  1. Inicie o upgrade no local.

    Use uma solicitação PATCH com o método instances:patch.

    Antes de usar qualquer um dos dados da solicitação, 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 da solicitação:

    {
  "databaseVersion": DATABASE_VERSION
}

    Substitua DATABASE_VERSION pelo tipo enumerado da versão principal do banco de dados, que precisa ser superior à versão atual. Especificar uma versão do banco de dados para uma versão principal disponível como um upgrade para a instância. Esse tipo enumerado pode ser obtido como a primeira etapa para Planejar o upgrade. Se você precisar de uma lista completa de tipos enumerados de versões do banco de dados, consulte SqlDatabaseVersion.

  2. Recebe o nome da operação de upgrade.

    Use uma solicitação GET com o método operations.list após substituir PROJECT_ID pelo ID do projeto.

    Método HTTP e URL: 

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

  3. Monitore o status do upgrade.

    Use uma solicitação GET com o método operations.get após substituir as seguintes variáveis:

    • PROJECT_ID: o ID do projeto
    • OPERATION_NAME: o nome da operação de upgrade recuperada na etapa anterior.

    Método HTTP e URL: 

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

Terraform

Para atualizar a versão do banco de dados, use um recurso do Terraform e o provedor do Terraform para o 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 em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

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

    terraform init -upgrade

Aplique as alterações

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

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

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

  1. Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Para aplicar a configuração atualizada do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

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

    terraform destroy

Quando você faz uma solicitação de upgrade no local, o Cloud SQL realiza uma verificação de pré-upgrade. Se o Cloud SQL determinar que a instância não está pronta para upgrade, a solicitação de upgrade falhará com uma mensagem sugerindo como resolver o problema. Consulte também Resolver problemas com um upgrade de versão principal.

Backups automáticos de upgrade

Quando você realiza um upgrade de versão principal, o Cloud SQL faz automaticamente dois backups sob demanda, chamados de backups de upgrade:

  • O primeiro é o backup pré-upgrade, que é feito imediatamente antes do início do upgrade. É possível usar esse backup para restaurar a instância do banco de dados para o estado na versão anterior.
  • O segundo backup de upgrade é o backup de pós-upgrade, que é feito imediatamente após as novas gravações serem permitidas para a instância de banco de dados atualizada.

Quando você visualiza a lista de backups, os backups de upgrade são listados com o tipo On-demand. Os backups de upgrade são rotulados para ser possível identificá-los com rapidez. Por exemplo, se você estiver fazendo upgrade do PostgreSQL 14 para o PostgreSQL 15, o backup pré-upgrade será rotulado Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. e o backup pós-upgrade será Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

Assim como acontece com outros backups sob demanda, os backups de upgrade permanecem até que você os exclua ou exclua a instância. Se a PITR estiver ativada, não será possível excluir os backups de upgrade enquanto eles estiverem na janela de retenção. Caso precise excluir seus backups de upgrade, desative a PITR ou aguarde até que os backups de upgrade não estejam mais na sua janela de retenção.

Concluir o upgrade da versão principal

Quando terminar de fazer upgrade da instância principal, execute as seguintes etapas para concluir o upgrade:

  1. Ative a replicação pglogical se a instância a usava antes do upgrade. Isso 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 (réplica) fornecendo detalhes de conexão da seguinte forma à instância principal do Cloud SQL: 
      SELECT pglogical.create_subscription(
    subscription_name := 'test_sub',
    provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
);

      Exemplo:

      postgres=> SELECT pglogical.create_subscription(
postgres(>     subscription_name := 'test_sub',
postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
postgres(> );
-[ RECORD 1 ]-------+-----------
create_subscription | 2769129391
    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. Faça upgrade das réplicas de leitura.

    Se você parou a replicação para ler as réplicas, faça upgrade uma por uma. Use qualquer um dos métodos utilizados para fazer upgrade da instância principal. Quando você faz o upgrade de uma réplica, o Cloud SQL a recria com os endereços IP, os atualiza com os dados mais recentes da principal e reinicia a réplica.

    Se você tiver excluído as réplicas de leitura antes de fazer upgrade da principal, crie novas réplicas de leitura, que serão provisionadas automaticamente na versão de upgrade do banco de dados.

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

    Execute ANALYZE na instância principal para atualizar as estatísticas do sistema após o upgrade. Estatísticas precisas garantem que o planejador de consultas do PostgreSQL processe as consultas de maneira ideal. Estatísticas ausentes podem levar a planos de consulta inadequados, o que, por sua vez, pode prejudicar o desempenho e consumir muita memória.

  4. Faça testes de aceitação.

    Execute testes para garantir que o sistema atualizado tenha o desempenho esperado.

Resolver problemas de upgrade da versão principal

O Cloud SQL retornará uma mensagem de erro se você tentar utilizar um comando de upgrade inválido, por exemplo, se a instância contiver flags de banco de dados inválidas para a nova versão.

Se a solicitação de upgrade falhar, confira a sintaxe dela. Se a solicitação tiver uma estrutura válida, tente analisar as sugestões a seguir.

Conferir falhas na verificação anterior ao upgrade

As falhas na verificação pré-upgrade são problemas ou erros que o Cloud SQL detecta durante o processo de verificação ou validação pré-upgrade. Essas falhas ocorrem antes do processo de upgrade real começar e têm como objetivo identificar possíveis problemas ou incompatibilidades que podem afetar o sucesso do upgrade.

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

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

A tabela a seguir lista as falhas de verificação pré-upgrade e as mensagens de erro delas:

Falha na verificação pré-upgrade Mensagem de erro
O Cloud SQL detecta 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)
Ao fazer upgrade para o PostgreSQL 12 ou versões mais recentes, o Cloud SQL detecta 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 detecta 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 detecta que o valor
LC_COLLATE do banco de dados postgres é um conjunto de caracteres 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 detecta tabelas que têm identificadores de objeto (OIDs). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
O Cloud SQL detecta 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 detecta operadores postfix definidos pelo usuário. 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 detecta 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 detecta conversões de codificação definidas pelo usuário. 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 detecta 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 detecta a presença de arquivos raster do PostGIS descompactados. 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.

Corrigir o problema do caminho de pesquisa vazio

Isso acontece porque a extensão earthdistance usa tipos de cubo e Terra sem especificar o caminho de pesquisa da função. Você precisa especificar esse caminho, que é necessário durante o processo de upgrade.

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

Ver registros de upgrade

Se ocorrer algum problema com uma solicitação de upgrade válida, o Cloud SQL publicará registros de erro em projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Cada entrada de registro contém um rótulo com o identificador da instância para ajudar você a identificá-la com o erro de upgrade. Procure esses erros de upgrade e resolva-os.

Para ver os registros de erro, siga estas etapas:

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse Instâncias do Cloud SQL

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

  3. No painel Operações e registros da página Visão geral da instância, clique no link Verificar registros de erros do PostgreSQL.

    A página Análise de registros é aberta.

  4. Para ver os registros, faça o seguinte:

    • Para listar todos os registros de erro em um projeto, selecione o nome do registro no filtro de registro Nome do registro.

    Para mais informações sobre filtros de consulta, confira Consultas avançadas.

    • Para filtrar os registros de erro de upgrade de uma única instância, digite a seguinte consulta na caixa Pesquisar todos os campos depois de substituir DATABASE_ID

    pelo 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 registros de erro de upgrade por uma instância chamada 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"

As entradas de registro com o prefixo pg_upgrade_dump indicam que ocorreu um erro de upgrade. 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 registro rotuladas com um nome de arquivo secundário .txt podem listar outros erros que talvez você queira resolver antes de tentar o upgrade novamente.

Todos os nomes de arquivos estão no arquivo postgres-upgrade.log. Para localizar um nome de arquivo, consulte o campo labels.FILE_NAME.

Os nomes dos arquivos que podem conter erros incluem:

  • tables_with_oids.txt: Esse arquivo contém tabelas listadas com identificadores de objetos (OIDs). Exclua as tabelas ou modifique-as para que não usem OIDs.
  • tables_using_composite.txt: Esse arquivo contém tabelas listadas usando tipos compostos definidos pelo sistema. Exclua as tabelas ou as modifique para que não usem esses tipos compostos.
  • tables_using_unknown.txt: Esse arquivo contém tabelas listadas com o tipo de dados UNKNOWN. Exclua ou modifique as tabelas para que não usem esse tipo de dado.
  • tables_using_sql_identifier.txt: Esse arquivo contém tabelas listadas com o tipo de dados SQL_IDENTIFIER. Exclua ou modifique as tabelas para que não usem esse tipo de dado.
  • tables_using_reg.txt: Esse arquivo contém tabelas listadas usando o tipo de dados REG* (por exemplo, REGCOLLATION ou REGNAMESPACE). Exclua as tabelas ou modifique-as para que não usem esse tipo de dado.
  • postfix_ops.txt: Esse arquivo contém tabelas listadas com operadores pós-fixo (uniário direito). Exclua as tabelas ou modifique-as para que não usem esses operadores.

Verificar a memóri

Se a instância não tiver memória compartilhada suficiente, será possível ver esta mensagem de erro: ERROR: out of shared memory. É mais provável que esse erro ocorra se você tiver um excesso de 10.000 tabelas.

Antes de tentar fazer upgrade, defina o valor da sinalização max_locks_per_transaction como aproximadamente o dobro do número de tabelas na instância. A instância é reiniciada quando você altera o valor dessa sinalização.

Verificar a capacidade das conexões

Se a instância não tiver capacidade de conexão suficiente, esta mensagem de erro poderá ser exibida: ERROR: Insufficient connections.

O Cloud SQL recomenda aumentar o valor da sinalização max_connections pelo número de bancos de dados na instância. A instância é reiniciada quando você altera o valor dessa sinalização.

Verificar se há uma referência de coluna ambígua

Se você tiver uma referência de coluna ambígua nas suas visualizações, talvez apareça esta mensagem de erro: ERROR: column reference "<column_name>" is ambiguous. Esse problema ocorre quando uma nova versão do PostgreSQL introduz mudanças na estrutura das visualizações do catálogo do sistema, como pg_stat_activity e pg_stat_replication. Isso pode interromper as visualizações personalizadas que dependem da ordem das colunas.

Para verificar essa mensagem de erro, adicione esta consulta ao editor de consultas: textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

Resolva esse problema das seguintes maneiras:

  1. Adapte suas visualizações personalizadas.

    Atualize as referências de coluna nas suas visualizações personalizadas para alinhar com a nova definição de visualização do catálogo do sistema (como pg_stat_activity e pg_stat_replication) na versão do PostgreSQL de destino.

  2. Recrie suas visualizações.

    Remova suas visualizações personalizadas antes de fazer um upgrade de versão principal. Recrie as visualizações depois que o upgrade for concluído, garantindo que elas sejam compatíveis com a nova estrutura.

Para um exemplo mais detalhado do problema e outros insights, consulte esta discussão sobre o stack overflow.

Verificar SRFs em instruções CASE

Se você estiver fazendo upgrade da sua instância da versão 9.6 e usando funções de retorno definido nas instruções CASE, poderá receber esta mensagem de erro ERROR: set-returning functions are not allowed in CASE. Esse problema ocorre porque a partir da versão 10, o uso de funções que retornam conjuntos em instruções CASE não é permitido.

Para resolver esse problema e fazer upgrade da sua instância, verifique se todas as instruções CASE que usam funções que retornam conjuntos são modificadas para evitar o uso antes de tentar o upgrade novamente. Alguns SRFs usados com frequência incluem:

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

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

Se você tiver uma visualização criada em uma transmissão personalizada, uma mensagem de erro semelhante a esta vai aparecer: ERROR: cannot cast type <type_1> to <type_2>. Esse problema ocorre devido a problemas de permissão em transmissões personalizadas.

Para resolver esse problema, atualize a instância para [PostgreSQL version].R20240910.01_02

Para mais informações, consulte Manutenção de autoatendimento.

Verificar a propriedade do acionador de evento

Se um acionador de evento for de um usuário que não tem o papel de superusuário do CloudSQL, você poderá receber uma mensagem de erro como ERROR: permission denied to change owner of event trigger "<trigger_name>". Esse problema é causado por problemas de permissão ao tentar recriar esses gatilhos durante o upgrade. Você pode usar a consulta abaixo no editor de consultas para verificar esta mensagem de erro: textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

Para resolver isso, verifique a propriedade de todos os acionadores de eventos na sua instância. Verifique se o proprietário de cada acionador é um superusuário do Cloud SQL. Se algum acionador for de outros usuários, atualize a propriedade deles para um superusuário do CloudSQL antes de tentar o upgrade novamente. Use a consulta a seguir para mudar a propriedade ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

Use a consulta a seguir para receber uma lista de acionadores de eventos e os detalhes do proprietário. SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

Verificar colunas geradas de tabelas não registradas

Se você tiver uma tabela não registrada com colunas geradas, poderá aparecer a mensagem de erro ERROR: unexpected request for new relfilenumber in binary upgrade mode. Esse problema ocorre devido a discrepâncias nas características de persistência entre as tabelas e as sequências delas para colunas geradas.

Para resolver esse problema, faça o seguinte:

  1. Elimine as tabelas não registradas: se possível, exclua as tabelas não registradas que estão vinculadas a colunas geradas. Verifique se a perda de dados pode ser mitigada com segurança antes de continuar.
  2. Converter em tabelas permanentes: temporariamente, converta tabelas não registradas em permanentes seguindo estas etapas:
    1. Converter a tabela em uma tabela registrada ALTER TABLE SET LOGGED;
    2. Fazer upgrade de versão principal
    3. Converter a tabela de volta em uma tabela não registrada ALTER TABLE SET UNLOGGED

É possível identificar todas essas tabelas usando a consulta a seguir :

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 sinalizações personalizadas da sua instância do PostgreSQL

Se você estiver fazendo upgrade para uma instância do PostgreSQL, versão 14 ou posterior, verifique os nomes de qualquer sinalização de banco de dados configurada personalizada para a instância. Isso ocorre porque o PostgreSQL colocou restrições adicionais nos nomes permitidos para parâmetros personalizados.

O primeiro caractere de uma flag de banco de dados personalizada precisa ser alfabético (A-Z ou a-z). Todos os caracteres subsequentes podem ser alfanuméricos, o caractere especial de sublinhado (_) ou o caractere especial de cifrão ($).

Remover extensões

Se você estiver fazendo upgrade da instância do Cloud SQL, poderá receber esta mensagem de erro: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Para resolver o problema, siga estas etapas:

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

Restaurar para a versão principal anterior

Se o sistema de banco de dados atualizado não tiver o desempenho esperado, talvez seja necessário restaurar sua instância para a versão anterior. Para fazer isso, restaure seu backup de pré-upgrade para uma instância de recuperação do Cloud SQL, que é uma nova instância que executa a versão de pré-upgrade.

Para restaurar a versão anterior, siga estas etapas:

  1. Identifique seu backup pré-upgrade.

    Consulte Backups automáticos de upgrade.

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

    Crie uma nova instância do Cloud SQL usando a versão principal que o Cloud SQL estava executando quando foi feito o backup pré-upgrade. Defina as mesmas flags e configurações de instância usadas pela instância original.

  3. Restaure o backup pré-upgrade.

    Restaure o backup de pré-upgrade para a instância de recuperação. Esse comando pode levar alguns minutos para ser concluído.

  4. Adicione suas réplicas de leitura.

    Se você estava usando réplicas de leitura, adicione-as individualmente.

  5. Conecte o aplicativo.

    Depois de recuperar o sistema de banco de dados, atualize o aplicativo com detalhes sobre a instância de recuperação e as réplicas de leitura. É possível retomar a exibição de tráfego na versão de pré-upgrade do seu banco de dados.

Perguntas frequentes

As seguintes perguntas podem surgir durante o upgrade da versão principal do banco de dados.

Minha instância fica indisponível durante um upgrade?
Sim. Enquanto o Cloud SQL realiza o upgrade, a instância permanece indisponível por um período.
Quanto tempo leva um upgrade?

O upgrade de uma única instância normalmente leva menos de 10 minutos. Se a configuração da instância usar poucas vCPUs ou memória, o upgrade poderá levar mais tempo.

Se a instância hospedar muitos bancos de dados ou tabelas, ou se os bancos de dados forem muito grandes, o upgrade pode levar horas ou até mesmo expirar porque o tempo do upgrade corresponde ao número de objetos nos bancos de dados. Se você tiver várias instâncias que precisam ser atualizadas, o tempo total do upgrade aumentará proporcionalmente.

Posso monitorar cada etapa do meu processo de upgrade?
Embora o Cloud SQL permita monitorar se uma operação de upgrade ainda está em andamento, não é possível rastrear as etapas individuais de cada upgrade.
Posso cancelar meu upgrade após iniciá-lo?
Não é possível cancelar um upgrade após o início do processo. Se o upgrade falhar, o Cloud SQL recuperará automaticamente a instância na versão anterior.
O que acontece com minhas configurações durante um upgrade?

Quando você executa um upgrade de versão principal no local, o Cloud SQL mantém as configurações do banco de dados, incluindo o nome da instância, o endereço IP, os valores de flags configurados explicitamente e os dados do usuário. No entanto, o valor padrão das variáveis do sistema pode mudar. Por exemplo, o valor padrão da flag password_encryption no PostgreSQL 13 e anterior é md5. Quando você faz upgrade para o PostgreSQL 14, o valor padrão dessa flag muda para scram-sha-256.

Para saber mais, consulte Configurar flags do banco de dados. Se uma determinada flag ou um valor não for mais aceito na sua versão de destino, o Cloud SQL removerá automaticamente a flag durante o upgrade.

A seguir