Tutorial: migrar o PostgreSQL para o Banco de Dados do Azure para PostgreSQL online usando o DMS (clássico) por meio da CLI do Azure

Artigo
03/09/2023

Você pode usar o Serviço de Migração de Banco de Dados do Azure para migrar os bancos de dados de uma instância local do PostgreSQL para o Banco de Dados do Azure para PostgreSQL com um tempo de inatividade mínimo. Em outras palavras, a migração pode ser feita com o mínimo de tempo de inatividade para o aplicativo. Neste tutorial, você vai migrar o banco de dados de exemplo DVD Rental de uma instância local do PostgreSQL 9.6 para o Banco de Dados do Azure para PostgreSQL usando uma atividade de migração online no Serviço de Migração de Banco de Dados do Azure.

Neste tutorial, você aprenderá como:

Migrar o esquema de exemplo usando o utilitário pg_dump.
Criar uma instância do Serviço de Migração de Banco de Dados do Azure.
Criar um projeto de migração usando o Serviço de Migração de Banco de Dados do Azure.
Executar a migração.
Monitorar a migração.

Observação

Usar o Serviço de Migração de Banco de Dados do Azure para executar uma migração online exige a criação de uma instância com base no tipo de preço Premium. Criptografamos o disco para evitar o roubo de dados durante o processo de migração.

Importante

Para obter uma experiência ideal de migração, a Microsoft recomenda a criação de uma instância do Serviço de Migração de Banco de Dados do Azure na mesma região do Azure como o banco de dados de destino. Mover dados entre regiões ou áreas geográficas pode desacelerar o processo de migração e introduzir erros.

Pré-requisitos

Para concluir este tutorial, você precisará:

Baixar e instalar o PostgreSQL Community Edition 9.4, 9.5, 9.6 ou 10. A versão do PostgreSQL Server de origem precisa ser 9.4, 9.5, 9.6, 10, 11, 12 ou 13. Para saber mais, confira Versões do banco de dados PostgreSQL com suporte.

Observe também que a versão do Banco de Dados de destino do Azure para PostgreSQL precisa ser igual ou posterior à versão local do PostgreSQL. Por exemplo, o PostgreSQL 9.6 pode somente fazer a migração para o Banco de Dados do Azure para PostgreSQL 9.6, 10 ou 11, mas não para o Banco de Dados do Azure para PostgreSQL 9.5.
Criar uma instância no Banco de Dados do Azure para PostgreSQL ou Criar um Banco de Dados do Azure para PostgreSQL – Hiperescala (Citus).
Criar uma Rede Virtual do Microsoft Azure para o Serviço de Migração de Banco de Dados do Azure usando o modelo de implantação do Azure Resource Manager, que fornece conectividade site a site aos servidores de origem locais usando o ExpressRoute ou a VPN. Para obter mais informações sobre como criar uma rede virtual, confira a Documentação da Rede Virtual e, especificamente, os artigos de Início Rápido com detalhes passo a passo.
Observação

Durante a configuração da rede virtual, se você usar o ExpressRoute com emparelhamento de rede com a Microsoft, adicione os seguintes pontos de extremidade de serviço à sub-rede na qual o serviço será provisionado:
- Ponto de extremidade do banco de dados de destino (por exemplo, ponto de extremidade do SQL, ponto de extremidade do Azure Cosmos DB e assim por diante)
- Ponto de extremidade de armazenamento
- Ponto de extremidade do barramento de serviço
Essa configuração é necessária porque o Serviço de Migração de Banco de Dados do Azure não tem conectividade com a internet.
Verifique se as regras do NSG (grupo de segurança de rede) da rede virtual não bloqueiam a porta de saída 443 de ServiceTag para ServiceBus, Storage e AzureMonitor. Para obter mais detalhes sobre a filtragem de tráfego do NSG da rede virtual, confira o artigo Filtrar o tráfego de rede com grupos de segurança de rede.
Configurar o Firewall do Windows para acesso ao mecanismo de banco de dados.
Abra o firewall do Windows para permitir que o Serviço de Migração de Banco de Dados do Azure acesse o servidor PostgreSQL de origem, que por padrão é a porta TCP 5432.
Ao usar um dispositivo de firewall na frente de seus bancos de dados de origem, talvez seja necessário adicionar regras de firewall para permitir que o Serviço de Migração de Banco de Dados do Azure acesse os bancos de dados de origem para migração.
Crie uma regra de firewall no nível de servidor para o Banco de Dados do Azure para PostgreSQL a fim de permitir o acesso do Serviço de Migração de Banco de Dados do Azure aos bancos de dados de destino. Forneça o intervalo de sub-redes da rede virtual usado para o Serviço de Migração de Banco de Dados do Azure.
Há dois métodos para invocar a CLI:
- No canto superior direito do portal do Azure, selecione o botão Cloud Shell:
- Instale e execute a CLI localmente. É preciso ter a CLI 2.18 ou uma versão superior da ferramenta de linha de comando para gerenciar os recursos do Azure necessários para essa migração.
  
  Para baixar a CLI, siga as instruções no artigo Instalar a CLI do Azure. O artigo também lista as plataformas que dão suporte à CLI do Azure.
  
  Para configurar o WSL (Subsistema do Windows para Linux), siga as instruções no Guia de instalação do Windows 10
Habilite a replicação lógica no servidor de origem editando o arquivo postgresql.config e definindo os seguintes parâmetros:
- wal_level = lógico
- max_replication_slots = [número de slots]; é recomendável configurar como cinco slots
- max_wal_senders =[número de tarefas simultâneas] – O parâmetro max_wal_senders define o número de tarefas simultâneas que podem ser executadas; é recomendável definir como 10 tarefas

Migrar o esquema de exemplo

Para concluir todos os objetos de banco de dados, como procedimentos armazenados, índices e esquemas de tabela, é necessário extrair o esquema do banco de dados de origem e aplicar ao banco de dados.

Use o comando pg_dump -s para criar um arquivo de despejo de esquema para um banco de dados.
```
pg_dump -O -h hostname -U db_username -d db_name -s > your_schema.sql
```
Por exemplo, para despejar o arquivo de esquema do banco de dados dvdrental:
```
pg_dump -O -h localhost -U postgres -d dvdrental -s  > dvdrentalSchema.sql
```
Para obter mais informações sobre como usar o utilitário pg_dump, confira os exemplos do tutorial pg-dump.
Crie um banco de dados vazio no ambiente de destino, que é o Banco de Dados do Azure para PostgreSQL.

Para obter detalhes sobre como conectar e criar um banco de dados, confira o artigo Criar um servidor de Banco de Dados do Azure para PostgreSQL no portal do Azure ou Criar um servidor de Banco de Dados do Azure para PostgreSQL – Hiperescala (Citus) no portal do Azure.

Importe o esquema para o banco de dados de destino criado restaurando o arquivo de despejo do esquema.

psql -h hostname -U db_username -d db_name < your_schema.sql

Por exemplo:

psql -h mypgserver-20170401.postgres.database.azure.com  -U postgres -d dvdrental < dvdrentalSchema.sql

Observação

O serviço de migração habilita ou desabilita internamente as chaves estrangeiras e os gatilhos para garantir a confiabilidade e a solidez da migração de dados. Por isso, você não precisa se preocupar em fazer modificações no esquema de banco de dados de destino.

Como provisionar uma instância do DMS usando a CLI do Azure

Instale a extensão de sincronização do DMS:
- Execute o seguinte comando para entrar no Azure:
```
az login
```
- Quando solicitado, abra um navegador da Web e insira um código para autenticar o dispositivo. Siga as instruções conforme listadas.
- A migração online do PostgreSQL agora está disponível no pacote da CLI regular (versão 2.18.0 e posterior) sem a necessidade da extensão dms-preview. Se você tiver instalado a extensão anteriormente, poderá removê-la seguindo estas etapas:
  - Para verificar se você já tem a extensão dms-preview instalada, execute o seguinte comando:
```
az extension list -o table
```
  - Se a extensão dms-preview estiver instalada, execute o seguinte comando para desinstalá-la:
```
az extension remove --name dms-preview
```
  - Para verificar se você desinstalou corretamente a extensão dms-preview, execute o seguinte comando e a extensão dms-preview não deve aparecer na lista:
```
az extension list -o table
```
  Importante
  
  A extensão dms-preview ainda pode ser necessária para outros caminhos de migração com suporte do Azure DMS. Consulte a documentação do caminho de migração específico para determinar se a extensão é necessária. Esta documentação aborda o requisito da extensão, específico do PostgreSQL para o Banco de Dados do Azure para PostgreSQL online.
- É possível exibir todos os comandos com suporte no DMS a qualquer momento executando:
```
az dms -h
```
- Se você tiver várias assinaturas do Azure, execute o comando a seguir para definir a assinatura que deseja usar para provisionar uma instância do serviço DMS.
```
az account set -s 97181df2-909d-420b-ab93-1bff15acb6b7
```

Provisione uma instância do DMS executando o seguinte comando:

az dms create -l <location> -n <newServiceName> -g <yourResourceGroupName> --sku-name Premium_4vCores --subnet/subscriptions/{vnet subscription id}/resourceGroups/{vnet resource group}/providers/Microsoft.Network/virtualNetworks/{vnet name}/subnets/{subnet name} –tags tagName1=tagValue1 tagWithNoValue

Por exemplo, o seguinte comando criará um serviço em:

Localização: Leste dos EUA2
Assinatura: 97181df2-909d-420b-ab93-1bff15acb6b7
Nome do grupo de recursos: PostgresDemo
Nome do serviço DMS: PostgresCLI

az dms create -l eastus2 -g PostgresDemo -n PostgresCLI --subnet /subscriptions/97181df2-909d-420b-ab93-1bff15acb6b7/resourceGroups/ERNetwork/providers/Microsoft.Network/virtualNetworks/AzureDMS-CORP-USC-VNET-5044/subnets/Subnet-1 --sku-name Premium_4vCores

A criação da instância do serviço DMS leva cerca de 10 a 12 minutos.

Para identificar o endereço IP do agente do DMS para e poder adicioná-lo ao arquivo Postgres pg_hba, execute o seguinte comando:

az network nic list -g <ResourceGroupName>--query '[].ipConfigurations | [].privateIpAddress'

Por exemplo:

az network nic list -g PostgresDemo --query '[].ipConfigurations | [].privateIpAddress'

Você verá um resultado semelhante ao seguinte endereço:

[
  "172.16.136.18"
]

Adicione o endereço IP do agente do DMS ao arquivo Postgres pg_hba.
- Anote o endereço IP do DMS depois de concluir o provisionamento no DMS.
- Adicione o endereço IP ao arquivo pg_hba na origem, semelhante à seguinte entrada:
```
host     all            all        172.16.136.18/10    md5
host     replication    postgres   172.16.136.18/10    md5
```
Em seguida, crie um projeto de migração do PostgreSQL executando o seguinte comando:
```
az dms project create -l <location> -g <ResourceGroupName> --service-name <yourServiceName> --source-platform PostgreSQL --target-platform AzureDbforPostgreSQL -n <newProjectName>
```
Por exemplo, o comando abaixo cria um projeto usando estes parâmetros:
- Localização: Centro-oeste dos EUA
- Nome do grupo de recursos: PostgresDemo
- Nome do serviço: PostgresCLI
- Nome do projeto: PGMigration
- Plataforma de origem: PostgreSQL
- Plataforma de destino: AzureDbForPostgreSql
```
az dms project create -l westcentralus -n PGMigration -g PostgresDemo --service-name PostgresCLI --source-platform PostgreSQL --target-platform AzureDbForPostgreSql
```
Crie uma tarefa de migração do PostgreSQL usando as etapas a seguir.

Esta etapa inclui o uso do IP de origem, da ID de usuário e da senha, do IP de destino, da ID de usuário, da senha e do tipo de tarefa para estabelecer a conectividade.
- Para ver uma lista completa de opções, execute o comando:
```
az dms project task create -h
```
  No caso das conexões de origem e de destino, o parâmetro de entrada se refere a um arquivo JSON que contém a lista de objetos.
  
  O formato do objeto JSON de conexão para conexões do PostgreSQL.
```
{
    // if this is missing or null, you will be prompted
    "userName": "user name",
    // if this is missing or null (highly recommended) you will  be prompted  
    "password": null,
    "serverName": "server name",
    // if this is missing, it will default to the 'postgres' database
    "databaseName": "database name",
    // if this is missing, it will default to 5432 
    "port": 5432                
}
```
  Há também um arquivo JSON de opção de banco de dados que lista os objetos JSON. Para o PostgreSQL, o formato do objeto JSON de opções do banco de dados é mostrado abaixo:
```
[
    {
        "name": "source database",
        "target_database_name": "target database",
        "selectedTables": [
            "schemaName1.tableName1",
            ...n
        ]
    },
    ...n
]
```
- Para criar o JSON da conexão de origem, abra o Bloco de notas e copie o JSON a seguir no arquivo. Salve o arquivo em C:\DMS\source.json depois de modificá-lo de acordo com o servidor de origem.
```
{
    "userName": "postgres",    
    "password": null,
    "serverName": "13.51.14.222",
    "databaseName": "dvdrental", 
    "port": 5432                
}
```
- Para criar o JSON da conexão de destino, abra o Bloco de notas e copie o JSON a seguir no arquivo. Salve o arquivo em C:\DMS\target.json depois de modificá-lo de acordo com o servidor de destino.
```
{
    "userName": " dms@builddemotarget",    
    "password": null,           
    "serverName": " builddemotarget.postgres.database.azure.com",
    "databaseName": "inventory", 
    "port": 5432                
}
```
- Crie um arquivo JSON de opções de banco de dados que lista o inventário e o mapeamento dos bancos de dados a serem migrados:
  - Crie uma lista de tabelas a serem migradas ou use uma consulta SQL para gerar a lista a partir do banco de dados de origem. Veja abaixo um exemplo de consulta para gerar a lista de tabelas. Ao usar essa consulta, lembre-se de remover a última vírgula no final do último nome de tabela para torná-la uma matriz JSON válida.
```
SELECT
    FORMAT('%s,', REPLACE(FORMAT('%I.%I', schemaname, tablename), '"', '\"')) AS SelectedTables
FROM 
    pg_tables
WHERE 
    schemaname NOT IN ('pg_catalog', 'information_schema');
```
  - Crie o arquivo JSON de opções de banco de dados com uma entrada para cada banco de dados, com os nomes de origem e de destino desses bancos de dados e a lista de tabelas selecionadas a serem migradas. Você pode usar a saída da consulta SQL acima para preencher a matriz "selectedTables" . Observe que, se a lista de tabelas selecionadas estiver vazia, o serviço incluirá para migração todas as tabelas que têm nomes e esquemas correspondentes.
```
[
    {
        "name": "dvdrental",
        "target_database_name": "dvdrental",
        "selectedTables": [
            "schemaName1.tableName1",
            "schemaName1.tableName2",                    
            ...
            "schemaNameN.tableNameM"
        ]
    },
    ... n
]
```
- Execute o seguinte comando, que obtém as conexões de origem e de destino e os arquivos JSON de opções de banco de dados.
```
az dms project task create -g PostgresDemo --project-name PGMigration --source-connection-json c:\DMS\source.json --database-options-json C:\DMS\option.json --service-name PostgresCLI --target-connection-json c:\DMS\target.json --task-type OnlineMigration -n runnowtask    
```
Neste ponto, você enviou com sucesso uma tarefa de migração.

Para mostrar o progresso da tarefa, execute o seguinte comando:

Para ver um resumo do status geral da tarefa

az dms project task show --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask

Para ver o status detalhado da tarefa, incluindo as informações de progresso da migração

az dms project task show --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask --expand output

Você também pode usar o formato de consulta JMESPath para extrair apenas o migrationState da saída expandida:

az dms project task show --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask --expand output --query 'properties.output[].migrationState'

Há vários parâmetros na saída que indicam o progresso de diferentes etapas da migração. Por exemplo, confira a saída abaixo:

{
    "output": [
        // Database Level
        {
            "appliedChanges": 0, // Total incremental sync applied after full load
            "cdcDeleteCounter": 0, // Total delete operation  applied after full load
            "cdcInsertCounter": 0, // Total insert operation applied after full load
            "cdcUpdateCounter": 0, // Total update operation applied after full load
            "databaseName": "inventory",
            "endedOn": null,
            "fullLoadCompletedTables": 2, //Number of tables completed full load
            "fullLoadErroredTables": 0, //Number of tables that contain migration error
            "fullLoadLoadingTables": 0, //Number of tables that are in loading status
            "fullLoadQueuedTables": 0, //Number of tables that are in queued status
            "id": "db|inventory",
            "incomingChanges": 0, //Number of changes after full load
            "initializationCompleted": true,
            "latency": 0,
            //Status of migration task
            "migrationState": "READY_TO_COMPLETE", //READY_TO_COMPLETE => the database is ready for cutover
            "resultType": "DatabaseLevelOutput",
            "startedOn": "2018-07-05T23:36:02.27839+00:00"
        }, {
            "databaseCount": 1,
            "endedOn": null,
            "id": "dd27aa3a-ed71-4bff-ab34-77db4261101c",
            "resultType": "MigrationLevelOutput",
            "sourceServer": "138.91.123.10",
            "sourceVersion": "PostgreSQL",
            "startedOn": "2018-07-05T23:36:02.27839+00:00",
            "state": "PENDING",
            "targetServer": "builddemotarget.postgres.database.azure.com",
            "targetVersion": "Azure Database for PostgreSQL"
        },
        // Table 1
        {
            "cdcDeleteCounter": 0,
            "cdcInsertCounter": 0,
            "cdcUpdateCounter": 0,
            "dataErrorsCount": 0,
            "databaseName": "inventory",
            "fullLoadEndedOn": "2018-07-05T23:36:20.740701+00:00", //Full load completed time
            "fullLoadEstFinishTime": "1970-01-01T00:00:00+00:00",
            "fullLoadStartedOn": "2018-07-05T23:36:15.864552+00:00", //Full load started time
            "fullLoadTotalRows": 10, //Number of rows loaded in full load
            "fullLoadTotalVolumeBytes": 7056, //Volume in Bytes in full load
            "id": "or|inventory|public|actor",
            "lastModifiedTime": "2018-07-05T23:36:16.880174+00:00",
            "resultType": "TableLevelOutput",
            "state": "COMPLETED", //State of migration for this table
            "tableName": "public.catalog", //Table name
            "totalChangesApplied": 0 //Total sync changes that applied after full load
        },
        //Table 2
        {
            "cdcDeleteCounter": 0,
            "cdcInsertCounter": 50,
            "cdcUpdateCounter": 0,
            "dataErrorsCount": 0,
            "databaseName": "inventory",
            "fullLoadEndedOn": "2018-07-05T23:36:23.963138+00:00",
            "fullLoadEstFinishTime": "1970-01-01T00:00:00+00:00",
            "fullLoadStartedOn": "2018-07-05T23:36:19.302013+00:00",
            "fullLoadTotalRows": 112,
            "fullLoadTotalVolumeBytes": 46592,
            "id": "or|inventory|public|address",
            "lastModifiedTime": "2018-07-05T23:36:20.308646+00:00",
            "resultType": "TableLevelOutput",
            "state": "COMPLETED",
            "tableName": "public.orders",
            "totalChangesApplied": 0
        }
    ],
    // DMS migration task state
    "state": "Running", //Running => service is still listening to any changes that might come in
    "taskType": null
}

Tarefa de migração de substituição

O banco de dados estará pronto para substituição quando o carregamento completo terminar. Dependendo do estado de ocupação do servidor de origem com as novas transações, a tarefa do DMS poderá continuar a aplicar as alterações após a conclusão do carregamento completo.

Para verificar se todos os dados estão atualizados, valide as contagens de linhas entre os bancos de dados de origem e de destino. Por exemplo, você pode validar os seguintes detalhes da saída de status:

Database Level
"migrationState": "READY_TO_COMPLETE" => Status of migration task. READY_TO_COMPLETE means database is ready for cutover
"incomingChanges": 0 => Check for a period of 5-10 minutes to ensure no new incoming changes need to be applied to the target server

Table Level (for each table)
"fullLoadTotalRows": 10    => The row count matches the initial row count of the table
"cdcDeleteCounter": 0      => Number of deletes after the full load
"cdcInsertCounter": 50     => Number of inserts after the full load
"cdcUpdateCounter": 0      => Number of updates after the full load

Execute a tarefa de migração de substituição do banco de dados usando o seguinte comando:

az dms project task cutover -h

Por exemplo, o comando a seguir iniciará o corte para o banco de dados 'Inventory':

az dms project task cutover --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask  --object-name Inventory

Para monitorar o progresso da substituição, execute o seguinte comando:

az dms project task show --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask

Quando o status da migração de banco de dados mostrar Concluído, recrie sequências (se aplicável) e conecte seus aplicativos à nova instância do Banco de Dados do Azure para PostgreSQL de destino.

Limpeza de tarefa, projeto, serviço

Se você precisar cancelar ou excluir uma tarefa, um projeto ou um serviço DMS, execute o cancelamento na sequência a seguir:

Cancelar as tarefas em execução
Excluir a tarefa
Excluir o projeto
Excluir o serviço DMS

Para cancelar uma tarefa em execução, use o seguinte comando:

az dms project task cancel --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask

Para excluir uma tarefa em execução, use o seguinte comando:

az dms project task delete --service-name PostgresCLI --project-name PGMigration --resource-group PostgresDemo --name runnowtask

Para excluir um projeto, use o seguinte comando:

az dms project delete -n PGMigration -g PostgresDemo --service-name PostgresCLI

Para excluir o serviço DMS, use o seguinte comando:
```
az dms delete -g ProgresDemo -n PostgresCLI
```

Próximas etapas

Para obter informações sobre problemas conhecidos e limitações na realização de migrações online para o Banco de Dados do Azure para PostgreSQL, confira o artigo Problemas conhecidos e soluções alternativas nas migrações online de Banco de Dados do Azure para PostgreSQL.
Para obter informações sobre o Serviço de Migração de Banco de Dados do Azure, consulte o artigo O que é o Serviço de Migração de Banco de Dados do Azure?.
Para obter informações sobre o Banco de Dados do Azure para PostgreSQL, consulte o artigo O que é o Banco de Dados do Azure para PostgreSQL?.