Diagnosticar problemas em migrações do PostgreSQL para o AlloyDB para PostgreSQL

O processo do job de migração pode apresentar erros durante o ambiente de execução.

  • Alguns erros, como uma senha incorreta no banco de dados de origem, são recuperáveis, ou seja, podem ser corrigidos, e o job de migração é retomado automaticamente.
  • Alguns são irrecuperáveis, como corrupção de dados ou incompatibilidades de esquema, o que significa que o job de migração precisa ser reiniciado do início.

Quando ocorre um erro, o status do job de migração muda para Failed, e o substatus reflete o último status antes da falha.

Para resolver problemas de um erro, acesse o job de migração com falha para conferir o erro e siga as etapas descritas na mensagem de erro.

Para ver mais detalhes sobre o erro, acesse o Cloud Monitoring usando o link no job de migração. Os registros são filtrados para o job de migração específico.

A tabela a seguir lista problemas comuns e as soluções para eles:

Para este problema... O problema pode ser... Tente o seguinte...
Ao migrar para um cluster de destino atual, você recebe a seguinte mensagem de erro: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. Seu cluster de destino do AlloyDB para PostgreSQL contém dados extras do usuário. Só é possível migrar para clusters vazios. Consulte Limitações conhecidas. Limpe os dados conflitantes ou extras do cluster de destino e tente novamente o job de migração. Consulte Limpar dados extras do cluster de destino atual.
Falha ao se conectar à instância do banco de dados de origem. Houve um problema de conectividade entre a instância do banco de dados de origem e o cluster de destino do AlloyDB para PostgreSQL. Siga as etapas em Como depurar a conectividade.
Falha ao executar o job de migração devido a versões incompatíveis do banco de dados de origem e de destino. As versões dos bancos de dados de origem e destino não são uma combinação compatível. Especificamente, a versão do banco de dados de origem fornecida é incompatível com a versão do banco de dados de destino. Verifique se a versão do banco de dados de destino é igual ou posterior à versão principal compatível do banco de dados de origem. Em seguida, crie um job de migração.
As linguagens de definição de dados (DDLs) ou linguagens de manipulação de dados (DMLs) estão bloqueadas na origem. As DDLs que exigem o bloqueio ACCESS EXCLUSIVE e estão em execução durante a fase de despejo completo são bloqueadas.

Durante o processo de sincronização inicial (despejo completo), evite DDLs ou programas que exijam bloqueios de ACCESS EXCLUSIVE, como ALTER TABLE ou DROP TABLE, nas tabelas. Caso contrário, as DDLs ou os programas vão aguardar até que a sincronização inicial seja concluída.

Por exemplo, se uma tabela ainda estiver no processo de sincronização inicial e um comando ALTER TABLE for executado na mesma tabela, o comando não será executado, e os comandos DDL e DML subsequentes serão bloqueados até que a sincronização inicial seja concluída.
Mensagem de erro: No pglogical extension installed on databases (X) Um ou mais bancos de dados de origem não têm o pglogical instalado. Siga estas diretrizes para instalar o pglogical nos bancos de dados da instância de origem.
Ao migrar para o PostgreSQL versão 15, após várias tentativas de conexão, um dos seguintes sintomas ocorre: Esse problema geralmente é atribuído ao problema de deadlock na extensão pglogical. Para mais informações, consulte o Issue Tracker do pglogical no GitHub. Tente novamente o job de migração ou migre primeiro para uma versão intermediária do PostgreSQL. Para mais detalhes, consulte Mensagem de erro: Cannot connect to invalid database.
Mensagem de erro: Replication user 'x' doesn't have sufficient privileges. O usuário que está usando o Database Migration Service não tem os privilégios necessários para realizar a operação designada. Siga estas diretrizes para garantir que esse usuário tenha os privilégios necessários.
Mensagem de erro: Unable to connect to source database server. O Database Migration Service não consegue estabelecer uma conexão com o servidor de banco de dados de origem. Verifique se as instâncias de banco de dados de origem e destino podem se comunicar entre si e se você atende a todos os pré-requisitos que apareceram quando você definiu as configurações do job de migração.
Mensagem de erro: The source database 'wal_level' configuration must be equal to 'logical'. O wal_level do banco de dados de origem está definido com um valor diferente de logical. Defina wal_level como logical. Consulte Configuração do nível de WAL.
Mensagem de erro: The source database 'max_replication_slots' configuration is not sufficient. O parâmetro max_replication_slots não foi configurado corretamente. Siga estas diretrizes para definir esse parâmetro corretamente.
Mensagem de erro: The source database 'max_wal_senders' configuration is not sufficient. O parâmetro max_wal_senders não foi configurado corretamente. Siga estas diretrizes para definir esse parâmetro corretamente.
Mensagem de erro: The source database 'max_worker_processes' configuration is not sufficient. O parâmetro max_worker_processes não foi configurado corretamente. Siga estas diretrizes para definir esse parâmetro corretamente.

Mensagem de erro: Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

OU

Mensagem de erro: Error promoting EM replica: finished drop replication with errors.

As configurações necessárias para a replicação não podem ser limpas durante a promoção de um job de migração.

Para cada banco de dados, execute comandos como um usuário com o privilégio superuser.

Para mais informações sobre quais comandos executar, consulte Limpar slots de replicação.

Mensagem de erro: x509 certificate signed by unknown authority.

O certificado de CA de origem fornecido ao Database Migration Service pode conter apenas o certificado raiz. No entanto, o certificado de origem requer o certificado raiz e todos os certificados intermediários.

Por exemplo, no Amazon RDS, usar um certificado raiz independente em vez de um pacote de certificados pode resultar nesse problema.

Crie um certificado de CA de origem combinado que contenha o certificado raiz e todos os certificados intermediários necessários.

Para fontes do Amazon RDS, use um pacote de certificados que inclua os certificados intermediários e raiz. Para mais informações, consulte Fazer o download de pacotes de certificados na documentação do Amazon RDS.

Mensagem de erro: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

O valor definido para o parâmetro max_locks_per_transaction não é suficiente. Defina o valor desse parâmetro como pelo menos {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions).

Mensagem de erro: ERROR: no data left in message.

O pacote pglogical não está instalado corretamente na instância de origem. Para mais informações sobre como instalar esse pacote corretamente, consulte Configurar o banco de dados de origem.

Mensagem de erro: Cannot assign TransactionIds during recovery.

A origem configurada está no modo de recuperação. Configure uma origem que não esteja no modo de recuperação.
O despejo completo é lento. A instância principal do cluster de destino do AlloyDB para PostgreSQL pode ser lenta ao importar dados grandes do banco de dados de origem.
  • Escolha um nível de máquina mais alto para a instância principal de destino do AlloyDB para PostgreSQL para ter a largura de banda de rede e a capacidade de CPU máximas disponíveis.
  • Ajuste a flag max_wal_size do destino. Normalmente, 32 GB ou 64 GB é um bom valor para essa flag. Não é necessário reiniciar o servidor de banco de dados para atualizar essa flag.
Mensagem de erro: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

O job de migração falhou durante a fase de despejo completo e não é recuperável. A instância do banco de dados de origem foi reiniciada ou estava no modo de recuperação, ou as conexões de replicação foram encerradas devido a um valor insuficiente definido para o parâmetro wal_sender_timeout.

Para descobrir a causa raiz do problema:

  1. Acesse a página da Análise de Registros no console do Google Cloud .
  2. Na lista de recursos, selecione sua instância do AlloyDB para PostgreSQL. Uma lista dos registros mais recentes da instância será exibida.
  3. Nos nomes dos arquivos de registro, selecione postgres.log.
  4. Defina o nível de gravidade do registro como todos os níveis acima de Warning. Os primeiros registros de erro podem ser a causa raiz da falha.
  • Verifique se o Database Migration Service sempre pode se conectar à instância do banco de dados de origem durante a fase de despejo completo.
  • Verifique se o valor do parâmetro wal_sender_timeout está definido como um número maior (por exemplo, 0) na instância do banco de dados de origem.
  • Reinicie o job de migração e tente de novo.
Mensagem de erro: ERROR: unknown column name {column_name}

Uma coluna foi adicionada a uma tabela replicada no nó principal, mas não no nó de réplica.

Somente as alterações da linguagem de manipulação de dados (DML) são atualizadas automaticamente durante as migrações contínuas. É necessário gerenciar as mudanças na linguagem de definição de dados (DDL) para que os bancos de dados de origem e de destino permaneçam compatíveis. Há duas maneiras de fazer isso:

  • Interrompa as gravações no banco de dados de origem e execute os comandos DDL na origem e no destino. Antes de executar os comandos DDL no destino, conceda o papel alloydbexternalsync ao usuário do AlloyDB para PostgreSQL que está aplicando as mudanças de DDL.
  • Use pglogical.replicate_ddl_command para permitir que os comandos DDL sejam executados na origem e no destino em um ponto consistente. O usuário que executa os comandos precisa ter o mesmo nome de usuário na origem e no destino e ser o superusuário ou o proprietário do artefato que está sendo migrado (por exemplo, a tabela, a sequência, a visualização ou o banco de dados).

Consulte Migração contínua para encontrar exemplos de uso de pglogical.replicate_ddl_command.
Mensagem de erro: ERROR: cannot truncate a table referenced in a foreign key constraint

Um usuário tentou truncar uma tabela que tem uma restrição de chave externa.

Remova a restrição de chave externa primeiro e, em seguida, trunque a tabela.
Mensagem de erro: ERROR: connection to other side has died

A conexão de replicação foi encerrada devido a um valor insuficiente definido para o parâmetro wal_sender_timeout. O erro geralmente ocorre durante a fase de replicação após o sucesso do despejo inicial.

Considere aumentar o valor do parâmetro wal_sender_timeout ou desativar o mecanismo de tempo limite definindo o valor como 0 na instância do banco de dados de origem.
Mensagem de aviso: migration job test configuration has returned the following warnings: Some table(s) have limited support.

A origem tem tabelas com suporte limitado, por exemplo, tabelas sem chaves primárias.

Esta é uma mensagem de aviso. É possível prosseguir com a migração, mas observe que, em migrações padrão, as tabelas sem chaves primárias replicam apenas o snapshot inicial e as instruções INSERT durante a fase de captura de dados alterados (CDC). As instruções UPDATE e DELETE não são replicadas. Para mais informações, consulte Configurar o banco de dados de origem.

Quando você migra bancos de dados selecionados e o job de migração não consegue replicar dados para um ou mais bancos de dados, o status Falha é exibido na lista de bancos de dados. Vários erros de job de migração.

Na coluna Erros, clique em Ver erros e corrija-os. Também é possível remover os bancos de dados com falha do job de migração.

Para mais informações sobre como remover um banco de dados com falha de um job de migração, consulte Gerenciar jobs de migração.

Limpar dados extras do cluster de destino atual

Ao migrar para um cluster de destino, você recebe a seguinte mensagem de erro: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.

Esse problema pode ocorrer se o cluster de destino tiver dados extras. Só é possível migrar para clusters vazios. Consulte Limitações conhecidas.

O que você pode tentar

Limpe os dados conflitantes ou extras do cluster de destino e inicie o job de migração novamente seguindo estas etapas:

  1. Interrompa o job de migração.
  2. Conecte-se à instância principal do cluster de destino do AlloyDB para PostgreSQL usando o psql ou o AlloyDB Studio.
  3. Remova os dados extras dos bancos de dados do cluster de destino. O destino só pode conter dados de configuração do sistema. Os bancos de dados de destino não podem conter dados do usuário (como tabelas ou rotinas definidas pelo usuário). Há diferentes instruções SQL que podem ser executadas nos bancos de dados para encontrar dados que não são do sistema:

    Exemplo de instrução SQL para recuperar bancos de dados que não são do sistema (clique para abrir)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('alloydbadmin', 'template1', 'template0', 'postgres');

    Exemplo de instrução SQL para recuperar dados que não são do sistema no banco de dados postgres (clique para abrir)

    O banco de dados postgres é um banco de dados do sistema, mas pode conter dados que não são do sistema. Execute essas instruções no banco de dados postgres. Se você usar o cliente psql para se conectar ao cluster de destino, poderá alternar para outro banco de dados sem redefinir a conexão usando o comando \connect {database_name_here}.

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname NOT IN ('plpgsql', 'alloydb_utility');
  4. Remova todos os bancos de dados que não são do sistema, tabelas de usuário e funções definidas pelo usuário identificadas na etapa anterior.
  5. Inicie o job de migração.

Limpar slots de replicação

Você verá uma das seguintes mensagens:

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

O problema pode ser

Ao promover um cluster de destino do AlloyDB para PostgreSQL, se a instância de origem não estiver acessível pelo cluster do AlloyDB para PostgreSQL (por exemplo, a instância de origem não está em execução ou você removeu o cluster do AlloyDB para PostgreSQL da lista de permissões de instâncias de origem), as configurações necessárias para a replicação não poderão ser limpas durante a promoção de um job de migração. É preciso limpar os slots de replicação manualmente.

O que você pode tentar

Para cada banco de dados, execute os seguintes comandos como um usuário com o privilégio superuser:

  1. Encontre os nomes dos slots de replicação na mensagem de erro e execute o seguinte comando para descartar os slots, um por um:

    SELECT pg_drop_replication_slot('slot_name');

  2. Se os nomes dos slots de replicação não estiverem disponíveis na mensagem de erro, execute o seguinte comando para consultar os slots de replicação atuais:

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

  3. Se não houver réplicas do AlloyDB para PostgreSQL usando a instância de origem, execute o seguinte comando para limpar as configurações de pglogical:

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  4. Se a extensão pglogical não for mais necessária, execute o seguinte comando para desinstalá-la:

    DROP EXTENSION IF EXISTS pglogical;

Mensagem de erro: Cannot connect to invalid database

Ao migrar para o PostgreSQL versão 15, após várias tentativas de conexão subsequentes, um dos seguintes sintomas ocorre:

O problema pode ser

Esse problema geralmente é atribuído ao problema de deadlock na extensão pglogical. Para mais informações, consulte o Issue Tracker do pglogical no GitHub.

O que você pode tentar

Realizar o job de migração novamente com um novo cluster de destino

Tente excluir o cluster de destino em que você teve o problema e recrie o job de migração. Siga estas etapas:

  1. Exclua o job de migração com falha. Consulte Analisar um job de migração.
  2. Exclua o cluster de destino em que o problema ocorreu. Consulte Gerenciamento de clusters do AlloyDB.
  3. Recrie o job de migração. Consulte Criar um job de migração.
Migrar para uma versão intermediária

Considere migrar para uma versão anterior do PostgreSQL, como o PostgreSQL 14. Após uma migração bem-sucedida, é possível fazer upgrade para a instância desejada do PostgreSQL 15. Consulte Fazer upgrade de uma versão principal do banco de dados na documentação do AlloyDB para PostgreSQL.

Excluir clusters órfãos do AlloyDB para PostgreSQL no modo de inicialização

Em casos raros, pode ser que o job de migração tenha sido excluído, mas o cluster do AlloyDB para PostgreSQL associado não, e ainda esteja no modo de inicialização. É possível excluir o cluster usando o comando gcloud alloydb clusters delete com a opção --force:

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

A exclusão de um cluster de inicialização enquanto ele está sendo usado por um job de migração ativo resulta em um comportamento indefinido.

Gerenciar usuários e papéis

Migrar usuários atuais

No momento, o Database Migration Service não oferece suporte à migração automática de usuários e papéis de uma instância de origem para um cluster de destino do AlloyDB para PostgreSQL. Para gerenciar essa migração, crie os usuários no AlloyDB para PostgreSQL manualmente.

Sobre o usuário alloydbexternalsync

Durante uma migração padrão, todos os objetos de banco de dados na réplica do AlloyDB para PostgreSQL pertencem ao usuário alloydbexternalsync. As migrações de início rápido usam o usuário postgres. Depois que os dados forem migrados e o job de migração for promovido, você poderá modificar a propriedade dos objetos para outros usuários do aplicativo seguindo estas etapas:

  • Execute o comando GRANT alloydbexternalsync TO USER;.
  • Em cada banco de dados, execute o comando REASSIGN OWNED BY alloydbexternalsync TO USER;.
  • Para remover o usuário alloydbexternalsync, execute o comando DROP ROLE alloydbexternalsync;.