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

Artigo
04/07/2024

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 do PostgreSQL local para o Banco de Dados do Azure para PostgreSQL com o mínimo de tempo de inatividade. Em outras palavras, a migração pode ser alcançada com o mínimo de tempo de inatividade para o aplicativo. Neste tutorial, você migra o banco de dados de exemplo de aluguel de DVD de uma instância local do PostgreSQL 9.6 para o Banco de Dados do Azure para PostgreSQL usando a atividade de migração online no Serviço de Migração de Banco de Dados do Azure.

Neste tutorial, irá aprender a:

Migre o esquema de exemplo usando pg_dump utilitário.
Criar uma instância do Azure Database Migration Service.
Utilizar o Azure Database Migration Service para criar um projeto de migração.
Executar a migração.
Monitorizar a migração.

Nota

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

Importante

Para uma experiência de migração ideal, 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 que o banco de dados de destino. Mover dados entre regiões ou geografias pode retardar o processo de migração e introduzir erros.

Pré-requisitos

Para concluir este tutorial, precisa de:

Baixe e instale o PostgreSQL community edition 9.4, 9.5, 9.6 ou 10. A versão de origem do PostgreSQL Server deve ser 9.4, 9.5, 9.6, 10, 11, 12 ou 13. Para obter mais informações, veja Versões suportadas da base de dados do PostgreSQL.

Observe também que a versão de destino do Banco de Dados do Azure para PostgreSQL deve ser igual ou posterior à versão local do PostgreSQL. Por exemplo, o PostgreSQL 9.6 só pode migrar 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.
Crie uma instância no Banco de Dados do Azure para PostgreSQL ou Crie um Banco de Dados do Azure para o servidor PostgreSQL - Hyperscale (Citus).
Criar uma Rede Virtual do Microsoft Azure para o Azure Database Migration Service com o modelo de implementação Azure Resource Manager, que proporciona conectividade site a site aos seus servidores de origem no local através do ExpressRoute ou de uma VPN. Para obter mais informações sobre como criar uma rede virtual, consulte a Documentação da Rede Virtual e, especialmente, os artigos de início rápido com detalhes passo a passo.
Nota

Durante a configuração da rede virtual, se você usar a Rota Expressa com emparelhamento de rede para a Microsoft, adicione os seguintes pontos de extremidade de serviço à sub-rede na qual o serviço será provisionado:
- Ponto final da base de dados de destino (por exemplo, ponto final do SQL, ponto final do Azure Cosmos DB, etc.)
- Ponto final de armazenamento
- Ponto final do Service Bus
Esta configuração é necessária porque o Azure Database Migration Service não tem conectividade à Internet.
Certifique-se de que as regras do NSG (Network Security Group) da rede virtual não bloqueiem a porta de saída 443 do ServiceTag para ServiceBus, Storage e AzureMonitor. Para obter mais detalhes sobre a filtragem de tráfego do NSG da rede virtual, veja o artigo Filtrar o tráfego de rede com grupos de segurança de rede.
Configurar a sua Firewall do Windows para acesso ao motor de bases de dados.
Abra a firewall do Windows para permitir ao Azure Database Migration Service aceder ao Servidor PostgreSQL de origem, que, por predefinição, é a porta TCP 5432.
Se estiver a utilizar uma aplicação de firewall à frente da base ou bases de dados, poderá ter de adicionar regras de firewall para permitir que o Azure Database Migration Service aceda à base ou bases de dados de origem para migração.
Crie uma regra de firewall ao nível do servidor para a Base de Dados do Azure para PostgreSQL para permitir que o Azure Database Migration Service aceda às bases de dados de destino. Forneça o intervalo de sub-redes da rede virtual utilizada no Azure Database Migration Service.
Existem 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. A versão CLI 2.18 ou superior da ferramenta de linha de comando é necessária 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 oferecem suporte à CLI do Azure.
  
  Para configurar o Subsistema Windows para Linux (WSL), siga as instruções no Windows 10 Installation Guide (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 = logical
- max_replication_slots = [número de slots], recomendo a configuração para 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, definição recomendada de 10 tarefas

Migrar o esquema de exemplo

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

Utilize o comando pg_dump -s para criar um ficheiro de captura de esquema para uma base de dados.
```
pg_dump -O -h hostname -U db_username -d db_name -s > your_schema.sql
```
Por exemplo, para capturar um ficheiro de esquema para uma base de dados dvdrental:
```
pg_dump -O -h localhost -U postgres -d dvdrental -s  > dvdrentalSchema.sql
```
Para obter mais informações sobre como utilizar o utilitário pg_dump, veja os exemplos no tutorial pg-dump.
Crie uma base de dados vazia no ambiente de destino, que é a Base de Dados do Azure para PostgreSQL.

Para obter detalhes sobre como conectar e criar um banco de dados, consulte o artigo Criar um banco de dados do Azure para o servidor PostgreSQL no portal do Azure ou Criar um banco de dados do Azure para o servidor PostgreSQL - Hyperscale (Citus) no portal do Azure.

Importe o esquema para a base de dados de destino que criou ao restaurar o ficheiro de captura de 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

Nota

O serviço de migração lida internamente com a habilitação/desativação de chaves e gatilhos estrangeiros para garantir uma migração de dados confiável e robusta. Como resultado, você não precisa se preocupar em fazer modificações no esquema do banco de dados de destino.

Provisionando uma instância do DMS usando a CLI do Azure

Instale a extensão dms sync:
- Inicie sessão no Azure ao executar o seguinte comando:
```
az login
```
- Quando lhe for pedido, abra um browser e introduza um código para autenticar o dispositivo. Siga as instruções tal como indicadas.
- A migração on-line do PostgreSQL agora está disponível dentro do pacote CLI regular (versão 2.18.0 e superior) sem a necessidade da dms-preview extensão. Se você tiver instalado a extensão no passado, você pode removê-lo usando as seguintes etapas:
  - Para verificar se você já tem dms-preview a extensão instalada, execute o seguinte comando:
```
az extension list -o table
```
  - Se dms-preview a extensão estiver instalada, para desinstalá-la, execute o seguinte comando:
```
az extension remove --name dms-preview
```
  - Para verificar se você desinstalou dms-preview a extensão corretamente, execute o seguinte comando e você não deve ver a dms-preview extensão na lista:
```
az extension list -o table
```
  Importante
  
  dms-preview ainda pode ser necessária para outros caminhos de migração suportados pelo Azure DMS. Verifique a documentação do caminho de migração específico para determinar se a extensão é necessária. Esta documentação aborda o requisito de extensão, específico do PostgreSQL para o Banco de Dados do Azure para PostgreSQL online.
- Em qualquer altura, veja todos os comandos suportados no DMS ao executar:
```
az dms -h
```
- Se tiver várias subscrições do Azure, execute o comando seguinte para definir a subscrição com que pretende aprovisionar uma instância do serviço DMS.
```
az account set -s 97181df2-909d-420b-ab93-1bff15acb6b7
```

Aprovisione uma instância do DMS ao executar 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 vai criar um serviço em:

Localização: E.U.A. Leste 2
Subscrição: 97181df2-909d-420b-ab93-1bff15acb6b7
Nome de 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

Demora cerca de 10 a 12 minutos para criar a instância do serviço DMS.

Para identificar o endereço IP do agente do DMS, para que o possa adicionar ao ficheiro pg_hba.conf do Postgres, execute o seguinte comando:
```
az network nic list -g <ResourceGroupName>--query '[].ipConfigurations | [].privateIpAddress'
```
Por exemplo:
```
az network nic list -g PostgresDemo --query '[].ipConfigurations | [].privateIpAddress'
```
Deverá obter um resultado semelhante ao endereço seguinte:
```
[
  "172.16.136.18"
]
```
Adicione o endereço IP do agente DMS ao ficheiro pg_hba.conf do Postgres.
- Anote o endereço IP do DMS depois de concluir o aprovisionamento no DMS.
- Adicione o endereço IP ao ficheiro pg_hba.conf 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 ao executar 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 seguinte cria um projeto que utiliza estes parâmetros:
- Localização: E.U.A. Centro-Oeste
- Nome de 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 com os seguintes passos.

Este passo inclui a utilização do IP de origem, UserID e palavra-passe, IP de destino, UserID, palavra-passe e o tipo de tarefa para estabelecer conectividade.
- Para ver uma lista completa de opções, execute o comando:
```
az dms project task create -h
```
  Para a ligação de origem e de destino, o parâmetro de entrada refere-se a um ficheiro json que tem a lista de objetos.
  
  O formato do objeto JSON de ligação para ligaçõ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 de base de dados é mostrado abaixo:
```
[
    {
        "name": "source database",
        "target_database_name": "target database",
        "selectedTables": [
            "schemaName1.tableName1",
            ...n
        ]
    },
    ...n
]
```
- Para criar a conexão de origem json, abra o Bloco de Notas, copie o seguinte json e cole-o no arquivo. Salve o arquivo em C:\DMS\source.json depois de modificá-lo de acordo com seu servidor de origem.
```
{
    "userName": "postgres",    
    "password": null,
    "serverName": "13.51.14.222",
    "databaseName": "dvdrental", 
    "port": 5432                
}
```
- Para criar a conexão de destino json, abra o Bloco de Notas, copie o seguinte json e cole-o no arquivo. Salve o arquivo em C:\DMS\target.json depois de modificá-lo de acordo com seu 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 liste o inventário e o mapeamento dos bancos de dados a serem migrados:
  - Crie uma lista de tabelas a serem migradas ou você pode usar uma consulta SQL para gerar a lista a partir do banco de dados de origem. Uma consulta de exemplo para gerar a lista de tabelas é dada abaixo apenas como um exemplo. Se estiver usando essa consulta, lembre-se de remover a última vírgula no final do nome da última 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 dos bancos de dados de origem e destino 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á todas as tabelas para migração que tenham esquemas e nomes de tabelas correspondentes.
```
[
    {
        "name": "dvdrental",
        "target_database_name": "dvdrental",
        "selectedTables": [
            "schemaName1.tableName1",
            "schemaName1.tableName2",                    
            ...
            "schemaNameN.tableNameM"
        ]
    },
    ... n
]
```
- Execute o comando a seguir, que inclui a conexão de origem, a conexão 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    
```
Chegado a este ponto, já submeteu com êxito uma tarefa de migração.

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

Para ver o status geral da tarefa em resumo

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 expandir:

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

Na saída, há vários parâmetros que indicam o progresso de diferentes etapas de migração. Por exemplo, veja 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 transferência

A base de dados está pronta para transferência quando o carregamento completo estiver concluído. Consoante o estado de disponibilidade do servidor de origem com novas transações a entrar, a tarefa DMS pode estar ainda a aplicar as alterações após a conclusão do carregamento completo.

Para garantir que todos os dados são capturados, valide as contagens de linhas entre as bases 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 da base de dados de transferência com o seguinte comando:

az dms project task cutover -h

Por exemplo, o comando a seguir iniciará a transferência para o banco de dados 'Inventário':

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

Para monitorizar o progresso da transferência, execute o seguinte comando:

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

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

Limpeza de serviços, projetos, tarefas

Se precisar de cancelar ou eliminar qualquer tarefa, projeto ou serviço do DMS, execute o cancelamento na sequência seguinte:

Cancele a tarefa em execução
Elimine a tarefa
Elimine o projeto
Elimine o serviço DMS

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

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

Para eliminar uma tarefa em execução, utilize 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 eliminar o serviço DMS, utilize o seguinte comando:
```
az dms delete -g ProgresDemo -n PostgresCLI
```

Próximos passos

Para obter informações sobre problemas conhecidos e limitações ao realizar migrações online para a Base de Dados do Azure para PostgreSQL, veja o artigo Problemas conhecidos e soluções alternativas das migrações online da Base de Dados do Azure para PostgreSQL.
Para obter informações sobre o Azure Database Migration Service, leia o artigo O que é o Azure Database Migration Service?.
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?.