Fazer upgrade da versão principal do servidor de um cluster

Esta página detalha o processo do AlloyDB para PostgreSQL para atualizar as versões do servidor de banco de dados e explica como migrar seus dados para um cluster compatível com uma versão mais recente do PostgreSQL.

Para mais informações sobre como criar um cluster, consulte Criar um cluster e a instância principal dele.

Clusters e compatibilidade de versão do PostgreSQL

Ao criar um cluster do AlloyDB, você escolhe a versão principal do PostgreSQL compatível com as instâncias no cluster. Por padrão, é a 17.

O AlloyDB realiza upgrades automáticos de versões secundárias do banco de dados durante a manutenção periódica. Por exemplo, se você criou um cluster com compatibilidade 17, o AlloyDB mantém os servidores de banco de dados atualizados para a versão secundária mais recente da 17.

No entanto, um upgrade de versão principal do PostgreSQL exige que você planeje, teste e realize o upgrade.

Há vários métodos para realizar upgrades de versão principal do cluster:

Um upgrade de versão principal no local que recomendamos usar.
Migração dos dados com uma exportação de dados baseada em arquivos.
Uso do Database Migration Service.

Cada solução de upgrade oferece vantagens e desvantagens diferentes. Consulte a tabela a seguir para uma breve comparação que vai ajudar você a escolher a abordagem certa para seu cenário.

Upgrade de versão principal no local	Exportação de dados baseada em arquivos	Migração com o Database Migration Service
O cluster, incluindo instâncias de leitura, é atualizado para a versão principal mais alta escolhida.	As exportações baseadas em arquivos movem um snapshot único dos seus bancos de dados.	O Database Migration Service oferece recursos de replicação contínua durante o processo de migração, reduzindo a chance de perder dados no novo cluster.
Você pode continuar trabalhando no cluster durante o estágio de pré-upgrade.	O aplicativo passa por um tempo de inatividade mais longo que começa quando você exporta os dados. Não é possível aceitar gravações de banco de dados no cluster original até que o novo cluster esteja totalmente operacional.	O aplicativo passa por um tempo de inatividade mais curto que começa quando você quer mudar o aplicativo para usar o novo cluster.
Você pode esperar aproximadamente 20 minutos ou mais de inatividade durante o processo de upgrade, dependendo do esquema. Após o upgrade, é possível acessar o cluster com o mesmo endereço IP.	Você tem maior controle granular sobre quais dados incluir na sua exportação e pode optar por não migrar determinadas tabelas ou outras entidades.	O Database Migration Service migra automaticamente todos os bancos de dados presentes em suas instâncias e todas as instâncias no cluster. Não é possível excluir determinadas tabelas ou visualizações dos dados de migração.
	O cluster pode ter o modo de aplicação obrigatória de SSL ativado.	Para fins de migração, o Database Migration Service exige que você desative o modo de aplicação obrigatória de SSL no cluster de origem.

A próxima seção detalha o processo de realização de um upgrade de versão principal, incluindo a migração dos dados.

Upgrade de versão principal no local

Isso oferece uma experiência de upgrade integrada sem exigir que você configure clusters adicionais. Para mais informações, consulte Fazer upgrade de uma versão principal do banco de dados no local.

Migrar usando a exportação de dados baseada em arquivos

Para usar um servidor de banco de dados compatível com uma versão principal mais recente do PostgreSQL, é necessário criar um cluster funcionalmente idêntico na mesma região e migrar os dados para ele.

Siga estas etapas:

Crie um cluster configurado com a versão principal da compatibilidade do PostgreSQL que você quer usar. Crie o cluster na mesma região do cluster atual.
Configure o novo cluster com a nova versão principal para corresponder à configuração do cluster atual:
1. Crie outras instâncias do pool de leitura conforme necessário.
2. Crie clusters secundários conforme necessário.
  
  Ao criar clusters secundários, não é necessário especificar um número de versão principal do PostgreSQL. O AlloyDB aplica a versão do PostgreSQL do cluster principal a todos os clusters secundários.
3. Atualize as flags do banco de dados do novo cluster para corresponder às configurações de flag do cluster atual.
4. Ative todas as extensões necessárias para seus aplicativos.
Exporte os dados do cluster antigo para arquivos usando psql ou pg_dump.
Importe os dados dos arquivos para o novo cluster.

Agora, seus aplicativos podem se conectar às instâncias do novo cluster nos novos endereços IP.

Migrar usando o Database Migration Service

É possível usar o Database Migration Service para mover dados de bancos de dados PostgreSQL para clusters do AlloyDB. O Database Migration Service não oferece configuração dedicada especificamente para fontes de dados do AlloyDB, mas o AlloyDB é compatível com o PostgreSQL. Portanto, é possível usar a configuração destinada a fontes genéricas do PostgreSQL.

Esse caminho de migração não é um upgrade no local e resulta na criação de um novo cluster com um endereço IP diferente. Recomendamos que você primeiro clone o cluster e realize uma migração de teste para verificar se o aplicativo é compatível com essa abordagem.

Considerações importantes

Antes de se preparar para migrar com o Database Migration Service, considere cuidadosamente as limitações a seguir para garantir que esse caminho de migração se ajuste ao cenário de upgrade.

Limitações

As instâncias do AlloyDB configuradas com Private Service Connect não são compatíveis.
Não é possível realizar atualizações de instâncias ou solicitações de failover no cluster de origem durante a migração. Essas operações podem causar falha no job de migração.
Todas as limitações padrão para migrações do PostgreSQL para o AlloyDB se aplicam a esse cenário. Para conferir a lista completa de outras limitações, consulte Limitações conhecidas na documentação do Database Migration Service.

Fidelidade de migração

Alguns tipos de dados, como objetos grandes, não são migrados. Para conferir a lista completa de dados compatíveis, consulte Fidelidade de migração na documentação do Database Migration Service.

Bloqueio e tempo de inatividade do banco de dados de origem

O Database Migration Service usa migrações contínuas para mover dados para clusters do AlloyDB. Esse tipo de migração incorre em um bloqueio curto (menos de 10 segundos) nas tabelas do banco de dados de origem, uma de cada vez, à medida que o despejo de dados inicial é criado.

Quando a migração for concluída, será necessário interromper todas as gravações no banco de dados de origem antes de mudar o aplicativo para o novo cluster. Esse procedimento exige um tempo de inatividade. Para uma visão geral mais detalhada, consulte Migrações contínuas na documentação do Database Migration Service.

Limitações de replicação

Depois que o job de migração passa para a fase de captura de dados alterados (CDC), o Database Migration Service replica continuamente novos dados gravados nos bancos de dados de origem.

Para tabelas que não têm chaves primárias, somente INSERT instruções são replicadas durante a fase de CDC. Todas as ações CREATE, UPDATE ou DELETE realizadas em tabelas que não têm chaves primárias durante a fase de CDC precisam ser recriadas manualmente no banco de dados de destino para evitar a perda de dados.

Antes de começar

Ative a API Database Migration Service.
Papéis necessários para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
Ativar a API

Verifique se você tem os seguintes papéis no projeto:
- Uma das seguintes opções:
  - Cloud AlloyDB > Administrador do Cloud AlloyDB
  - Básico > Proprietário
  - Básico > Editor
- Você também precisa ter a permissão compute.networks.list no Google Cloud projeto que está usando. Para conseguir essa permissão seguindo o princípio de privilégio mínimo, peça ao administrador para conceder a você o papel de usuário da rede do Compute Engine (roles/compute.networkUser).
- Administrador de migração de banco de dados
Verificar os papéis
1. No Google Cloud console, acesse a página IAM.
  Acessar IAM
2. Selecione o projeto.
3. Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.
4. Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.
Conceder os papéis
1. No Google Cloud console, acesse a página IAM.
  Acessar IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.
4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.
5. Clique em Selecionar um papel e pesquise o papel.
6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
7. Clique em Salvar.
Verifique se a rede VPC no Google Cloud projeto que você está usando está configurada para serviços particulares acesso ao AlloyDB.
Decida em qual região você quer criar o cluster de destino. Todas as entidades do Database Migration Service (perfis de conexão, jobs de migração) precisam ser criadas na mesma região do cluster de destino.
Prepare um usuário de banco de dados que você quer conectar ao seu cluster e execute instruções de migração nos bancos de dados de origem. Esse usuário de banco de dados exige um conjunto específico de permissões e papéis. Recomendamos que você crie um novo usuário de banco de dados e o designe especificamente para realizar a migração.

Configurar as instâncias de origem

O Database Migration Service exige uma configuração específica para se conectar e copiar dados do cluster de origem para o novo cluster de destino.

Para configurar as instâncias de origem do AlloyDB, siga estas etapas:

Configure as flags do banco de dados em cada instância do cluster de origem. Use os valores a seguir:

Sinalização	Valor
`alloydb.logical_decoding`	Defina como `on`.
`alloydb.enable_pglogical`	Defina como `on`.
`max_replication_slots`	Essa flag define o número máximo de slots de replicação que a instância de origem pode oferecer suporte. O valor mínimo para esta flag é `50`. Calcule o valor mínimo usando a seguinte fórmula: `(the number of databases in your instance) * (the number of simultaneous migration jobs you want to perform) + (slots reserved for table synchronization) + (the number of replication slots you currently use for your read replicas)` Considere um exemplo em que o seguinte é verdadeiro: Você não tem réplicas de leitura na origem. Você tem 30 bancos de dados na instância de origem principal. Você quer criar dois jobs de migração para o cluster de origem. Você quer usar 10 slots para replicação de tabelas. Nesse caso, o número de `max_replication_slots` precisa ser de pelo menos `70`, calculado como `30 * 2 + 10 + 0`.
`max_wal_senders`	Defina essa flag como pelo menos 10 a mais que o `max_replication_slots` valor mais o número de remetentes já usados na instância. Por exemplo, se você definir a `max_replication_slots flag` como `70` e já usar dois remetentes, então `max_wal_senders` precisará ser de pelo menos `82` (calculado como `70 + 10 + 2 = 82`).
`max_worker_processes`	Defina essa flag como, pelo menos, o número de bancos de dados na sua instância mais o número de `max_worker_processes` que você já usa. Por exemplo, se você tiver 30 bancos de dados na instância de origem e não usar nenhum processo de worker, defina essa flag como `30`.

Desative o modo de aplicação obrigatória de SSL em cada instância do cluster de origem.

Configurar os bancos de dados de origem

É necessário instalar a extensão pglogical e conceder as permissões necessárias ao usuário do banco de dados que você designar como usuário de migração em cada banco de dados nas instâncias.

Para configurar os bancos de dados, siga estas etapas:

Conecte-se ao banco de dados postgres padrão usando o cliente psql.
Instale a extensão pglogical executando o seguinte comando:
```
CREATE EXTENSION IF NOT EXISTS pglogical;
```
Conceda permissões ao usuário do banco de dados de migração em todos os esquemas exceto o esquema information e os esquemas cujos nomes começam com o prefixo pg_. Execute as seguintes instruções:
```
GRANT USAGE on SCHEMA SCHEMA_NAME to USER_NAME;
GRANT SELECT on ALL TABLES in SCHEMA SCHEMA_NAME to USER_NAME;
GRANT SELECT on ALL SEQUENCES in SCHEMA SCHEMA_NAME to USER_NAME;
```
Substitua:
- SCHEMA_NAME: o nome de um esquema presente no seu banco de dados
- USER_NAME: o nome do usuário do banco de dados que você preparou na seção Antes de começar
Repita essa etapa para cada esquema no banco de dados exceto o esquema information e os esquemas cujos nomes começam com o prefixo pg_. É possível listar todos os esquemas de banco de dados com o \dn meta-comando.
Conceda as permissões necessárias restantes. Execute as seguintes instruções:
```
GRANT USAGE on SCHEMA pglogical to PUBLIC;
GRANT SELECT on ALL TABLES in SCHEMA pglogical to USER_NAME;
ALTER USER USER_NAME with REPLICATION;
```
Substitua USER_NAME pelo nome do usuário do banco de dados que você preparou na seção Antes de começar.
Conecte-se a todos os outros bancos de dados na instância e repita as etapas 2, 3 e 4.
- É possível listar todos os bancos de dados na instância com o \list meta-comando.
- É possível mudar para outro banco de dados sem redefinir a conexão do cliente psql \connect {database_name_here} usando o comando.
Repita esse procedimento para cada instância no cluster de origem do AlloyDB.

Executar a migração no Database Migration Service