Fazer upgrade para uma nova versão principal

A partir de dezembro de 2025, Databases for PostgreSQL oferece três caminhos de atualização diferentes:

Atualização no local para uma nova versão principal.
Restaurando a partir do backup.
Atualização de uma réplica somente leitura.

Quando uma versão principal de um banco de dados estiver chegando ao fim da vida útil (EOL), é recomendável fazer o upgrade para uma versão principal atual.

Localize as versões disponíveis do Databases for PostgreSQL na página do IBM Cloud catálogo, na Cloud Databases comando de plug-in da CLI ibmcloud cdb deployables-showou na Cloud Databases API /deployables terminal.

Ao fazer upgrade para uma nova instância, também é necessário mudar as informações de conexão no aplicativo.

Nos comandos de exemplo a seguir, o CRN completo da instância do banco de dados é necessário para o comando {id}. Como o CRN contém caracteres especiais, ele deve ser codificado em URL para evitar um erro “not_found”.

Requisitos para atualizar para uma versão principal mais PostgreSQL recente a partir de PostgreSQL v14

Se você tiver o pg_repack instalado, é necessário removê-lo antes de executar o upgrade. Isso pode ser feito com um comando como:

DROP EXTENSION pg_repack;

Após o upgrade, reinstale pg_repack. Isso pode ser feito com o seguinte comando:

CREATE EXTENSION pg_repack;

Se você estiver usando, primeiro PostGIS, é necessário atualizar para PostGIS antes de atualizar PostgreSQL. Isso pode ser feito executando o seguinte comando em um banco de dados com o site PostGIS instalado.

SELECT postgis_extensions_upgrade();

Use a consulta a seguir para validar a atualização da extensão PostGIS.

SELECT postgis_full_version();

Atualizações de versão principal no local

A atualização da versão principal no local permite que você atualize sua implantação para a próxima versão principal, eliminando a necessidade de restaurar um backup em uma nova implantação. Essa abordagem mantém as mesmas cadeias de conexão, sem a necessidade de reconfigurar a implantação. No entanto, se a nova versão principal exigir ajustes na aplicação, estes devem ser resolvidos.

Durante a janela de atualização da versão principal no local, sua implantação passará por um breve período de inatividade. Isso é esperado, pois o processo segue a abordagem de atualização recomendada pelo fornecedor. A duração exata pode variar de acordo com o tamanho e a complexidade do esquema de sua implantação. Se o seu serviço precisar ler dados da instância atualizada durante esse período, você poderá criar uma instância em espera e atualizar os detalhes de conexão do seu aplicativo para apontar para a instância em espera. Isso garante que você tenha uma cópia atualizada do seu banco de dados antes de iniciar a atualização. A instância em espera também pode ser promovida e usada como instância primária se a atualização no local não for concluída com sucesso. Para obter mais informações, consulte Status da réplica somente leitura em upgrades de versões principais no local.

Databases for PostgreSQL oferece aos clientes flexibilidade no gerenciamento de seus próprios backups. O processo de atualização da versão principal no local não cria automaticamente um backup antes ou depois da tarefa. Se a atualização não for bem-sucedida, talvez seja necessário restaurar sua implantação a partir do backup mais recente em uma nova instância.

Embora as atualizações no local sejam suportadas, não é recomendável realizá-las sem um backup recente. Ter um backup atualizado antes e depois de iniciar a atualização oferece uma camada adicional de proteção e ajuda a garantir uma recuperação tranquila, se necessário. Portanto, considere fazer um backup novo antes e depois da tarefa de atualização da versão principal no local.

Antes de Iniciar

Considere os seguintes aspectos antes de iniciar o procedimento de atualização.

Verifique se há atualização de versão disponível para sua versão de implantação, verificando as informações de capacidade de implantação por meio da interface do usuário, API, CLI ou Terraform.

Exemplo: Consultar informações sobre atualização de versão com CLI.
```
ibmcloud cdb capability-show versions postgresql
```
Sua implantação deve estar em um estado saudável antes da atualização.
Sua implantação deve ter pelo menos 10% do espaço em disco disponível.
Sua implantação não deve estar sob forte pressão de E/S (máximo permitido: 90%).
Nesta fase, só é possível atualizar da PostgreSQL versão 14 para a versão PostgreSQL 15.
Cada versão principal contém alguns recursos que podem não ser compatíveis com versões anteriores. Verifique as notas de lançamento do fornecedor do banco de dados para ver se há alterações que possam afetar seus aplicativos.
O downgrade de uma implantação para uma versão anterior não é suportado.
A atualização da versão principal no local não pode ser cancelada depois de iniciada.
Se você não tiver um backup recente, considere fazer um antes de atualizar.

Observe também que, após a conclusão da atualização, seu banco de dados estará executando uma nova versão PostgreSQL principal. Como PostgreSQL armazena dados em formatos específicos de cada versão, o novo PostgreSQL diretório de dados não pode ser usado com versões anteriores. Isso significa que os backups feitos antes da atualização não podem ser usados para restaurar a nova PostgreSQL versão. Para manter os recursos completos de restauração e PITR (Recuperação em um ponto no tempo) no futuro, faça um novo backup após a atualização. Este novo backup torna-se a linha de base para todas as operações de recuperação futuras na linha PostgreSQL do tempo.

Fazendo upgrade na IU

Crie um novo Databases for PostgreSQL para testar o processo de atualização.
Crie a implantação restaurando um backup da sua implantação existente com a mesma versão.
Direcione sua aplicação de teste para a implantação de teste.
Atualize seu aplicativo de teste para apontar para a implantação de teste. Confirme se o seu aplicativo de teste consegue se conectar com sucesso à implantação de teste e se o aplicativo funciona conforme o esperado. Realize todos os testes de desempenho e operacionais necessários no ambiente de teste.
Atualize a versão principal da sua implantação de teste clicando no botão Atualizar versão principal na página Visão geral.
Anote quanto tempo leva para concluir a atualização, para que você possa usar a configuração de expiração da atualização para conter as atualizações dentro da sua janela de manutenção.
Confirme se o seu aplicativo de teste funciona com a nova versão do banco de dados.
Se o seu aplicativo funcionar, esta etapa confirma que é seguro atualizar seu banco de dados de produção.
Atualize a implantação do seu banco de dados de produção para a nova versão.
Depois de confirmar que seu aplicativo funciona corretamente usando a nova versão do banco de dados, você pode retornar ao console de gerenciamento e iniciar o processo de atualização de sua implantação de produção. Na seção Detalhes da implantação da página Visão geral, clique no botão Atualizar versão principal e siga as etapas.

Uma vez iniciado, o processo de atualização no local não pode ser interrompido ou revertido. Portanto, na improvável eventualidade de ocorrer um erro, a implantação do seu banco de dados poderá se tornar irrecuperável. Portanto, crie um backup que você possa usar para restaurar uma nova implantação.

O expiration for starting upgrade permite configurar um período de “timeout” dentro do qual a tarefa de atualização deve ser iniciada antes de ser automaticamente cancelada. Além disso, teste a atualização em um ambiente de teste antecipadamente para garantir que ela seja concluída dentro do prazo desejado. Se, por exemplo, você deseja concluir a atualização em 1 hora e testou a atualização e sabe que ela leva 30 minutos, então sua tarefa de atualização deve começar dentro de 30 minutos após você confirmar que deseja atualizar. Portanto, defina o prazo de validade para 30 minutos, para que, se não iniciar dentro desse tempo, não ultrapasse o seu prazo.

Fazendo upgrade por meio da API

Use o seguinte comando para atualizar no local:

curl -X PATCH https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/version -H 'Authorization: Bearer <>' -H 'Content-Type: application/json' -d '{"version": "15"}'

O expiration for starting upgrade permite configurar um período de “timeout” dentro do qual a tarefa de atualização deve ser iniciada antes de ser automaticamente cancelada. Além disso, teste a atualização em um ambiente de teste antecipadamente para garantir que ela seja concluída dentro do prazo desejado. Se, por exemplo, você deseja concluir a atualização em 1 hora e testou a atualização e sabe que ela leva 30 minutos, então sua tarefa de atualização deve começar dentro de 30 minutos após você confirmar que deseja atualizar. Portanto, defina a expiração para um carimbo de data/hora de 30 minutos a partir de agora, para que, se não iniciar dentro desse tempo, não ultrapasse sua janela. A expiração deve ser entre 5 minutos (padrão) e 24 horas a partir de agora. Para obter mais informações, consulte a Cloud Databases API.

Fazendo upgrade por meio da CLI

Disponível na versão do plugin CDB >= 0.20.0.

Para visualizar a lista de transições de atualização e restauração permitidas para a implantação:

ibmcloud cdb deployment-capability-show <NAME|CRN> versions

Para atualizar o comando com os parâmetros necessários:

ibmcloud cdb deployment-version-upgrade <NAME|CRN> <TARGET_VERSION>

Para visualizar todos os detalhes dos parâmetros de comando:

ibmcloud cdb deployment-version-upgrade --help

Atualização através do Terraform

Disponível na versão do provedor Terraform >= 1.79.2.

Para atualizar, basta adicionar ou alterar o version valor na sua configuração.

Ignorar um backup antes de uma atualização de versão é perigoso e pode resultar em perda de dados se a atualização falhar em qualquer etapa — não haverá um backup imediato para restaurar. Portanto, considere fazer um backup recente antes de iniciar uma tarefa de atualização de versão principal no local.

A atualização pode exigir mais tempo do que o tempo limite padrão. É possível definir um valor de tempo limite mais longo usando o atributo timeouts.

O Terraform tem tempos limite em vez de carimbos de data/hora de expiração. Portanto, aumente seu tempo limite, pois o valor atualizado do tempo limite é usado como prazo de validade. Por exemplo, se você definir um tempo limite de 20 minutos, a expiração será definida para 20 minutos e, se a atualização não iniciar nesse período, ela expirará e a atualização não será iniciada. Observe que o prazo máximo de validade é de 24 horas — portanto, mesmo que você defina um tempo limite de 36 horas, a atualização expirará se não tiver sido iniciada nas primeiras 24 horas.

Se uma atualização estiver em andamento, observe que algumas tarefas podem ficar em fila e não serão executadas até que a atualização da versão seja concluída.

Resolução de problemas

Se seus aplicativos apresentarem problemas inesperados após uma atualização bem-sucedida da versão principal no local e você precisar retornar à versão PostgreSQL anterior, entre em contato com nossa equipe de suporte para obter orientação. Evite iniciar um PITR ou restaurar um backup por conta própria, pois isso pode complicar a recuperação.

Uma atualização importante no local não será realizada até que todas as verificações prévias tenham sido aprovadas. Essas proteções existem para proteger sua implantação, uma vez que a atualização opera diretamente na instância de origem. Se a atualização estiver bloqueada, verifique as seguintes áreas:

Estado do cluster: Certifique-se de que o cluster Patroni está em bom estado e que existe um estado claro de líder/réplica. As atualizações não podem prosseguir se o Patroni relatar instabilidade ou condições de failover.
Espaço em disco: verifique se há espaço livre suficiente disponível. O processo utiliza o modo pg_upgrade de ligação, que requer espaço livre adequado. Se o uso do disco exceder o limite configurado (padrão: 90%), libere espaço antes de tentar novamente.
Carga de E/S do disco: verifique a utilização atual de E/S e IOPS. As atualizações são pausadas quando o sistema está sob carga pesada para evitar a degradação do desempenho ou falha na atualização.
Tamanho do esquema e contagem de objetos: conforme mencionado, o tamanho do esquema afeta diretamente a duração de uma atualização de versão principal no local. Certifique-se de que nenhum esquema individual exceda o tamanho máximo (padrão: 100 GB) e que o número total de objetos de índice e sequência permaneça abaixo do limite (padrão: 50.000). Esquemas grandes ou contagens de objetos excepcionalmente altas podem exigir limpeza ou otimização antes de prosseguir com a atualização. pg_upgrade realiza atualizações rápidas criando novas tabelas do sistema e simplesmente reutilizando os arquivos de dados antigos do usuário. O tempo necessário para criar essas tabelas do sistema varia de acordo com o número de objetos do banco de dados. O consumo de recursos pode ser avaliado usando a integração de monitoramento. Se nem todos os componentes do banco de dados estiverem disponíveis para atualização, a tarefa de atualização falhará. Isso pode ocorrer devido à manutenção. As tarefas que falharam devido a verificações de integridade com falha podem ser repetidas mais tarde. Se a tarefa continuar falhando, abra um ticket de suporte com IBM Cloud o suporte. Se determinadas verificações não forem relevantes para o seu ambiente e a atualização ainda estiver bloqueada, crie um ticket de suporte para obter mais assistência.

Manuseio da extensão `anon` antes da atualização

Se a extensão anon estiver instalada, siga as etapas abaixo e execute os comandos como usuário administrador antes de fazer o upgrade.

Remover todas as regras de mascaramento (se ativadas).
```
SELECT anon.remove_masks_for_all_columns();
```
Desative as funções de mascaramento (a atualização poderá falhar se alguma função estiver marcada como mascarada).
```
SECURITY LABEL FOR anon ON ROLE <role_name> IS NULL;
```
Elimine a extensão anon com a opção em cascata.
```
DROP EXTENSION anon CASCADE;
```
Se a extensão anon estiver instalada em vários bancos de dados em uma instância, siga as etapas descritas para cada banco de dados.
Etapas pós-atualização:

Após a conclusão da atualização, reative a extensão anon e reaplique as regras de mascaramento conforme necessário.

É altamente recomendável validar os dados antes e depois de eliminar a extensão para garantir a consistência do mascaramento antes de realizar a atualização.

Fazendo upgrade por meio de uma réplica somente leitura

Faça o upgrade configurando uma réplica somente leitura Provisione uma réplica somente leitura com a mesma versão de banco de dados da sua implantação e aguarde enquanto ela replica todos os seus dados. Quando a implantação e a réplica estiverem sincronizadas, promova e atualize a réplica somente leitura para uma implantação completa e autônoma que esteja executando a nova versão do banco de dados. Para executar a etapa de upgrade e promoção, use uma solicitação POST para o ponto de extremidade /deployments/{id}/remotes/promotion com a versão para a qual você deseja fazer upgrade no corpo da solicitação.

Esta solicitação é semelhante a:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{
    "promotion": {
        "version": "14",
        "skip_initial_backup": false
    }
}' \

skip_initial_backup é opcional. Se configurado como true, a nova implementação não fará um backup inicial quando a promoção for concluída. Sua nova implementação é disponibilizada em menos tempo, mas o backup dela não ocorre até a execução do próximo backup automático ou da realização de um sob demanda.

Simulando a promoção e o upgrade

Para avaliar os efeitos dos principais upgrades de versão, acione uma execução seca. Uma simulação simula a promoção e o upgrade, com os resultados impressos nos logs do banco de dados. Acesse e visualize os registros do seu banco de dados por meio da integração de análise de registro. Isso garante que a versão que você está executando atualmente com suas extensões possa ser atualizada com sucesso para a versão pretendida.

A simulação deve ser executada com skip_initial_backup configurado como false e version definida.

O comando é semelhante a:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{
    "promotion": {
        "version": "14",
        "skip_initial_backup": false,
        "dry_run": true
    }
}' \

Upgrade de backup e restauração

É possível fazer upgrade de sua versão do banco de dados restaurando um backup de seus dados em uma nova implementação que esteja executando a nova versão do banco de dados

Fazendo upgrade na IU

Faça upgrade para uma nova versão ao restaurar um backup do menu Backups de seu Painel de implementação. Clique em Restore em um backup para acessar a página de provisionamento em uma nova guia, onde você pode alterar algumas opções para a nova implantação. Uma das opções é a versão do banco de dados, que é preenchida automaticamente com as versões disponíveis para upgrade. Selecione uma versão e clique em Create (Criar ) para iniciar o processo de provisionamento e restauração.

Fazendo upgrade por meio da CLI

Para atualizar e restaurar a partir de um backup por meio da CLI do site IBM Cloud, use o comando de provisionamento no controlador de recursos.

ibmcloud resource service-instance-create <DEPLOYMENT_NAME_OR_CRN> <SERVICE_ID> <SERVICE_PLAN_ID> <REGION>

Os parâmetros service-name, service-id, service-plan-id e region são todos necessários. Você também fornece o -p com a versão e os parâmetros de ID de backup em um objeto JSON. A nova implementação é dimensionada automaticamente com o mesmo disco e a memória que a implementação de origem no momento do backup.

Este comando é semelhante a:

ibmcloud resource service-instance-create example-upgrade databases-for-postgresql standard us-south \
-p \ '{
  "backup_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
  "version":14
}'

Fazendo upgrade por meio da API

Conclua as etapas necessárias para usar a API do controlador de recursos antes de usá-la para fazer upgrade de um backup. Em seguida, envie à API uma solicitação POST. Os parâmetros name, target, resource_group e resource_plan_id são todos necessários. Você também fornece a versão e o ID de backup. A nova implementação tem a mesma alocação de memória e de disco que a implementação de origem no momento do backup.

Este comando é semelhante a:

curl -X POST \
  https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H 'Authorization: Bearer <>' \
  -H 'Content-Type: application/json' \
    -d '{
    "name": "my-instance",
    "target": "bluemix-us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-postgresql-standard",
    "backup_id": "crn:v1:bluemix:public:databases-for-postgresql:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
    "version":14
  }'

Atualização forçada

Após a data de fim de vida útil, todas as Databases for PostgreSQL implantações ativas na versão obsoleta serão atualizadas compulsoriamente para a próxima versão suportada. Por exemplo, PostgreSQL a versão 13 (obsoleta) é atualizada para a versão 14.

Faça o upgrade antes da data de fim de vida útil para evitar os seguintes riscos:

Não são fornecidos SLAs para esse tipo de upgrade forçado.
Pode ocorrer alguma perda de dados.
Seu aplicativo pode passar por um tempo de inatividade prolongado.
Seu aplicativo pode parar de funcionar se for incompatível com a nova versão.
Não é possível controlar o momento em que esse upgrade ocorrerá em sua implementação.
Não há processo de reversão para essa atualização forçada.

Para saber as datas de fim de vida útil, consulte a página de política de versão.

Problemas com o usuário administrador durante as atualizações de versão

A partir da PostgreSQL versão 16, a aplicação de privilégios de função tornou-se mais rigorosa. Em contrapartida, as versões anteriores permitiam que as funções com o atributo CREATEROLE gerenciassem outras funções; a versão 16 e posteriores exigem que uma função tenha o atributo ADMIN OPTION em outra função para concedê-la ou revogá-la.

Se você estiver atualizando o banco de dados de PostgreSQL v15 ou anterior para PostgreSQL v16 ou superior, poderá encontrar erros relacionados a privilégios, como:

ERROR: only roles with the ADMIN OPTION on role "some_role" may grant this role
DETAIL: role "admin" is not permitted to grant role "some_role"

Para resolver esse problema, fornecemos uma função auxiliar integrada grant_admin_option_to_roles que foi projetada para restaurar o comportamento esperado do gerenciamento de funções.

Essa função:

Aplica-se somente a bancos de dados atualizados de PostgreSQL v15 e versões anteriores para PostgreSQL 16 e posteriores (se você estiver encontrando o erro descrito acima).
Aceita uma lista arbitrária de funções às quais aplicar a correção.
Só pode ser executado pelo site admin user.
É seguro executar várias vezes (idempotente).

Amostra de uso:

SELECT grant_admin_option_to_roles('role1', 'role2', 'role3');

Isso garante que o admin user mantenha os privilégios ADMIN OPTION apropriados para gerenciar as funções designadas em instâncias atualizadas.

Fazer upgrade para uma nova versão principal

Requisitos para atualizar para uma versão principal mais PostgreSQL recente a partir de PostgreSQL v14

Atualizações de versão principal no local

Antes de Iniciar

Fazendo upgrade na IU

Fazendo upgrade por meio da API

Fazendo upgrade por meio da CLI

Atualização através do Terraform

Resolução de problemas

Manuseio da extensão anon antes da atualização

Fazendo upgrade por meio de uma réplica somente leitura

Simulando a promoção e o upgrade

Upgrade de backup e restauração

Fazendo upgrade na IU

Fazendo upgrade por meio da CLI

Fazendo upgrade por meio da API

Atualização forçada

Problemas com o usuário administrador durante as atualizações de versão

Log de mudanças para versões principais do PostgreSQL

Manuseio da extensão `anon` antes da atualização