Diagnostique problemas de migrações homogéneas para o Cloud SQL para PostgreSQL

O processo da tarefa de migração pode incorrer em erros durante o tempo de execução.

  • Alguns erros, como uma palavra-passe incorreta na base de dados de origem, são recuperáveis, o que significa que podem ser corrigidos e a tarefa de migração é retomada automaticamente.
  • Alguns são irrecuperáveis, como erros na replicação de dados, o que significa que a tarefa de migração tem de ser reiniciada desde o início.

Quando ocorre um erro, o estado da tarefa de migração muda para Failed e o subestado reflete o último estado antes da falha.

Para resolver um erro, navegue para a tarefa de migração com falha para ver o erro e siga os passos descritos na mensagem de erro.

Para ver mais detalhes sobre o erro, navegue para o Cloud Monitoring através do link na tarefa de migração. Os registos são filtrados para a tarefa de migração específica.

Na tabela seguinte, pode encontrar alguns exemplos de problemas e como podem ser resolvidos:

Para este problema… O problema pode ser... Experimente isto…
Quando migra para uma instância de destino existente, recebe a seguinte mensagem de erro: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. A instância do Cloud SQL de destino contém dados adicionais. Só pode migrar para instâncias existentes que estejam vazias. Consulte as Limitações conhecidas. Promova a instância de destino para a tornar uma instância de leitura/escrita, remova os dados adicionais e tente novamente a tarefa de migração. Consulte Limpe dados adicionais da instância de destino existente.
Falha ao estabelecer ligação à instância da base de dados de origem. Ocorreu um problema de conetividade entre a instância da base de dados de origem e a instância de destino. Siga os passos em Depurar a conetividade.
Falha na execução da tarefa de migração devido a versões de base de dados de origem e de destino incompatíveis. As versões da base de dados de origem e de destino não são uma combinação suportada. Especificamente, a versão da base de dados de origem fornecida é incompatível com a versão da base de dados de destino. Certifique-se de que a versão da base de dados de destino é igual ou uma versão principal superior à versão da base de dados de origem. Em seguida, crie uma nova tarefa de migração.
As linguagens de definição de dados (LDDs) ou as linguagens de manipulação de dados (LMDs) estão bloqueadas na origem. As DDLs que requerem o ACCESS EXCLUSIVE bloqueio e estão em execução durante a fase de descarga completa são bloqueadas.

Durante o processo de sincronização inicial (transferência completa), deve evitar DDLs ou programas que exijam ACCESS EXCLUSIVE bloqueios, como ALTER TABLE ou DROP TABLE, nas tabelas. Caso contrário, os DDLs ou os programas aguardam até a sincronização inicial terminar.

Por exemplo, se uma tabela ainda estiver no processo de sincronização inicial e for executado um comando ALTER TABLE na mesma tabela, o comando não é executado e os comandos DDL e DML subsequentes são bloqueados até a sincronização inicial terminar.
Mensagem de erro: No pglogical extension installed on databases (X) Uma ou mais bases de dados de origem não têm o pglogical instalado. Siga estas diretrizes para instalar o pglogical nas bases de dados na instância de origem.
Quando migra para a versão 15 do PostgreSQL, após várias tentativas de repetição de ligação subsequentes, ocorre um dos seguintes sintomas: Este problema é frequentemente atribuído ao problema de impasse na extensão pglogical. Para mais informações, consulte o pglogicalcontrolador de problemas no GitHub. Tente novamente a tarefa de migração ou migre primeiro para uma versão intermédia 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 utilizador que está a usar o serviço de migração de bases de dados não tem os privilégios necessários para realizar a operação designada. Siga estas diretrizes para garantir que este utilizador tem os privilégios necessários.
Mensagem de erro: Unable to connect to source database server. O serviço de migração de bases de dados não consegue estabelecer uma ligação ao servidor da base de dados de origem. Certifique-se de que as instâncias da base de dados de origem e de destino conseguem comunicar entre si e que concluiu todos os pré-requisitos necessários que apareceram quando definiu as definições da tarefa de migração.
Mensagem de erro: The source database 'wal_level' configuration must be equal to 'logical'. O wal_level da base de dados de origem está definido para um valor diferente de logical. Definir o wal_level para logical.
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 este 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 este 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 este 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.

Não é possível limpar as definições necessárias para a replicação durante a promoção de uma tarefa de migração.

Para cada base de dados, execute comandos como um utilizador com o privilégio superuser.

Para mais informações sobre os comandos a executar, consulte o artigo Limpe as posições de replicação.

Mensagem de erro: x509 certificate signed by unknown authority.

O certificado da AC de origem fornecido ao serviço de migração de base de dados pode conter apenas o certificado de raiz. No entanto, o certificado de origem requer o certificado de raiz e todos os certificados intermédios.

Por exemplo, para o Amazon Relational Database Service, a utilização do certificado rds-ca-2019-root.pem pode resultar neste problema.

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

Para o exemplo de utilização do Amazon Relational Database Service, em vez do certificado rds-ca-2019-root.pem, use o certificado rds-combined-ca-bundle.pem.

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 deste parâmetro para, 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 corretamente este pacote, consulte o artigo Instale o pacote pglogical na instância 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. O destino do Cloud SQL pode ser lento na importação de grandes quantidades de dados da base de dados de origem.
  • Quando criar o destino, defina o tamanho do disco de dados de modo que seja próximo do tamanho final. A fase de descarga completa usa uma carga de trabalho com escrita intensiva de E/S e um tamanho de disco maior tem um melhor desempenho de E/S. Para mais informações, consulte o artigo Desempenho do armazenamento de blocos.
  • Escolha um nível superior para o destino do Cloud SQL para obter a largura de banda de rede e de disco máxima disponível.
  • Ajuste a flag max_wal_size do destino do Cloud SQL. Normalmente, 32 GB ou 64 GB é um bom valor para definir para esta flag. A atualização desta flag não requer o reinício do servidor.
Mensagem de erro: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

A tarefa de migração falhou durante a fase de descarga completa e não é possível recuperar a tarefa. A instância da base de dados de origem foi reiniciada ou está no modo de recuperação, ou as ligações de replicação terminaram devido a um valor insuficiente definido para o parâmetro wal_sender_timeout.

Para encontrar a causa principal do problema:

  1. Aceda à página Explorador de registos na Google Cloud consola.
  2. Na lista de recursos, selecione a réplica do Cloud SQL. É apresentada uma lista dos registos mais recentes da réplica.
  3. Nos nomes dos ficheiros de registo, selecione postgres.log.
  4. Defina o nível de gravidade do registo para todos os níveis acima de Warning. Os registos de erros iniciais podem ser a causa principal da falha.
  • Certifique-se de que o Database Migration Service consegue sempre estabelecer ligação à instância da base de dados de origem durante a fase de descarga completa.
  • Verifique se o valor do parâmetro wal_sender_timeout está definido para um número superior (por exemplo, 0) na instância da base de dados de origem.
  • Reinicie a tarefa de migração e, em seguida, tente novamente.
Mensagem de erro: ERROR: unknown column name {column_name}

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

Apenas as alterações da linguagem de manipulação de dados (DML) são atualizadas automaticamente durante as migrações contínuas. A gestão das alterações da linguagem de definição de dados (DDL) para que as bases de dados de origem e de destino permaneçam compatíveis é da responsabilidade do utilizador e pode ser alcançada de duas formas:

  • Pare as gravações na base de dados de origem e execute os comandos DDL na origem e no destino. Antes de executar os comandos DDL no destino, conceda a função cloudsqlexternalsync ao utilizador do Cloud SQL que aplica as alterações DDL.
  • Use o pglogical.replicate_ddl_command para permitir que os comandos LDD sejam executados na origem e no destino num ponto consistente. O utilizador que executa os comandos tem de ter o mesmo nome de utilizador na origem e no destino, e deve ser o superutilizador ou o proprietário do artefacto que está a ser migrado (por exemplo, a tabela, a sequência, a vista ou a base de dados).

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

O utilizador tentou truncar uma tabela que tem uma restrição de chave externa.

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

A ligação de replicação terminou devido a um valor insuficiente definido para o elemento wal_sender_timeout parameter. Normalmente, o erro ocorre durante a fase de replicação após o êxito da descarga inicial.

Considere aumentar o valor do parâmetro wal_sender_timeout ou desativar o mecanismo de limite de tempo definindo o respetivo valor como 0 na instância da base 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. Pode continuar com a migração, mas tenha em atenção que as entidades não suportadas (por exemplo, tabelas sem chaves primárias) não são migradas. Para mais informações, reveja o artigo Configure as bases de dados de origem.

Quando migra bases de dados selecionadas e a tarefa de migração não consegue replicar dados para uma ou mais bases de dados, é apresentado o estado Falhou na lista de bases de dados. Vários erros de tarefas de migração.

Na coluna Erros, clique em Ver erros e corrija-os. Também pode remover as bases de dados com falhas da tarefa de migração.

Para mais informações sobre como remover uma base de dados com falhas de uma tarefa de migração, consulte o artigo Gerir tarefas de migração.

Limpe dados adicionais da instância de destino existente

Quando migra para uma instância de destino existente, recebe a seguinte mensagem de erro: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

Este problema pode ocorrer se a instância de destino contiver dados adicionais. Só pode migrar para instâncias existentes que estejam vazias. Consulte as Limitações conhecidas.

Coisas a experimentar

Limpe os dados adicionais da instância de destino e inicie novamente a tarefa de migração seguindo estes passos:

  1. Pare a tarefa de migração.
  2. Neste ponto, a instância do Cloud SQL de destino está no modo `read-only`. Promova a instância de destino para obter acesso de escrita.
  3. Estabeleça ligação à instância do Cloud SQL de destino.
  4. Remova dados adicionais das bases de dados da instância de destino. O destino só pode conter dados de configuração do sistema. As bases de dados de destino não podem conter dados do utilizador (como tabelas). Existem diferentes declarações SQL que pode executar nas suas bases de dados para encontrar dados não relacionados com o sistema, por exemplo:

    Exemplo de declaração SQL para obter bases de dados não pertencentes ao sistema (clique para expandir)

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

    Exemplo de declaração SQL para obter dados não relacionados com o sistema na base de dados postgres (clique para expandir)

    A base de dados postgres é uma base de dados do sistema, mas pode conter dados que não são do sistema. Certifique-se de que executa estas declarações na base de dados postgres. Se usar o cliente psql para se ligar à instância de destino, pode mudar para outra base de dados sem repor a ligação através do 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 != 'plpgsql';
  5. Inicie a tarefa de migração.

Limpe as posições de replicação

É apresentada 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

Quando promove uma instância do Cloud SQL, se a instância de origem não estiver acessível a partir da instância do Cloud SQL (por exemplo, a instância de origem não estiver em execução ou tiver removido a instância do Cloud SQL da lista de autorizações de instâncias de origem), não é possível limpar as definições necessárias para a replicação durante a promoção de uma tarefa de migração. Tem de limpar manualmente os espaços de replicação.

Coisas a experimentar

Para cada base de dados, execute os seguintes comandos como um utilizador com o privilégio superuser:

  1. Obtenha os nomes dos slots de replicação a partir da mensagem de erro e, em seguida, execute o seguinte comando para eliminar os slots, um a 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 existentes:

    select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';

  3. Se não existirem réplicas do Cloud SQL a usar a instância de origem, execute o seguinte comando para limpar as definições de pglogical:

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';

  4. Se já não precisar da extensão pglogical, execute o seguinte comando para a desinstalar:

    DROP EXTENSION IF EXISTS pglogical;

Mensagem de erro: Cannot connect to invalid database

Quando migra para a versão 15 do PostgreSQL, após várias tentativas de repetição de ligação subsequentes, ocorre um dos seguintes sintomas:

O problema pode ser

Este problema é frequentemente atribuído ao problema de impasse na extensão pglogical. Para mais informações, consulte o pglogical rastreador de problemas no GitHub.

Coisas a experimentar

Execute novamente a tarefa de migração com uma nova instância de destino

Experimente eliminar a base de dados de destino onde teve o problema e recrie a tarefa de migração. Siga estes passos:

  1. Elimine a instância de destino onde teve os problemas. Consulte o artigo Eliminar instâncias na documentação do Cloud SQL para PostgreSQL.
  2. Elimine a tarefa de migração com falha. Consulte o artigo Reveja uma tarefa de migração.
  3. Recrie a tarefa de migração. Consulte o artigo Crie uma tarefa de migração.

Migre para uma versão intermédia

Pondere migrar para uma versão anterior do PostgreSQL, como o PostgreSQL 14. Após uma migração bem-sucedida, pode tentar atualizar para a instância do PostgreSQL 15 desejada. Consulte o artigo Atualize a versão principal da base de dados migrando dados na documentação do Cloud SQL para PostgreSQL.

Faça a gestão de utilizadores e funções

Migre utilizadores existentes

Atualmente, o serviço de migração de base de dados não suporta a migração de utilizadores existentes de uma instância de origem para uma instância do Cloud SQL de destino. Pode gerir esta migração criando os utilizadores no Cloud SQL manualmente.

Acerca do utilizador do cloudsqlexternalsync

Durante a migração, todos os objetos na réplica do Cloud SQL são propriedade do utilizador cloudsqlexternalsync. Após a migração dos dados, pode modificar a propriedade dos objetos para outros utilizadores seguindo estes passos:

  • Execute o comando GRANT cloudsqlexternalsync to {USER}.
  • Em cada base de dados, execute o comando reassign owned by cloudsqlexternalsync to {USER};.
  • Para remover o utilizador cloudsqlexternalsync, execute o comando drop role cloudsqlexternalsync.

Importe dados para uma nova instância do Cloud SQL

Se primeiro exportar dados de uma instância do Cloud SQL que o serviço de migração de base de dados migrou para o Cloud Storage e, em seguida, importar os dados do Cloud Storage para uma instância autónoma do Cloud SQL, a importação pode falhar porque o utilizador cloudsqlexternalsync não existe na instância de destino.

Para mitigar o problema, crie o utilizador cloudsqlexternalsync na instância de destino ou remova o utilizador da instância migrada.