Resolver problemas de migração

Este documento ajuda você a resolver problemas comuns ao migrar seu data warehouse (como Teradata, Amazon Redshift, Oracle ou Apache Hive) para o BigQuery, incluindo problemas com avaliação de migração, tradução interativa e em lote de SQL e geração de metadados usando a ferramenta de extração de linha de comando dwh-migration-dumper.

Para inspecionar detalhes da execução do job, códigos de erro e uso de slots para consultas e jobs migrados, também é possível consultar a visualização INFORMATION_SCHEMA.JOBS.

Avaliação da migração

As seções a seguir explicam problemas comuns e técnicas de solução de problemas para migrar seu data warehouse para o BigQuery.

dwh-migration-dumper erros da ferramenta

Para solucionar erros e avisos na saída do terminal da ferramenta dwh-migration-dumper que ocorreram durante a extração de registros de consulta ou metadados, consulte Gerar solução de problemas de metadados.

Erros de migração do Hive

As seções a seguir descrevem problemas comuns que podem ser encontrados ao planejar a migração do seu data warehouse do Hive para o BigQuery.

O hook de geração de registros para extração de registros de consulta hadoop-migration-assessment grava mensagens de registro de depuração nos registros hive-server2. Se você encontrar algum problema, consulte os registros de depuração do hook de geração de registros, que contêm a string MigrationAssessmentLoggingHook.

Solucione o erro ClassNotFoundException

Esse erro pode ser causado pela posição incorreta do arquivo JAR do hook de geração de registros. Verifique se você adicionou o arquivo JAR à pasta auxlib no cluster do Hive. Outra possibilidade é especificar o caminho completo do arquivo JAR na propriedade hive.aux.jars.path, por exemplo, file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar.

A pasta configurada não mostra subpastas

Esse problema pode ser causado por uma configuração incorreta ou por problemas durante a inicialização do hook de geração de registros.

Nos registros de depuração hive-server2, procure as seguintes mensagens do hook de geração de registros:

Unable to initialize logger, logging disabled

Log dir configuration key 'dwhassessment.hook.base-directory' is not set,
logging disabled.

Error while trying to set permission

Analise os detalhes do problema e veja se há algo que você precisa corrigir para resolver o problema.

A pasta não mostra arquivos

Esse problema pode ser causado por problemas encontrados durante o processamento de eventos ou a gravação em um arquivo.

Nos registros de depuração hive-server2, procure as seguintes mensagens do hook de geração de registros:

Failed to close writer for file

Got exception while processing event

Error writing record for query

Analise os detalhes do problema e veja se há algo que você precisa corrigir para resolver o problema.

Alguns eventos de consulta estão perdidos

Esse problema pode ser causado por um excesso de filas de linhas de execução do hook de geração de registros.

Nos registros de depuração hive-server2, procure a seguinte mensagem do hook de geração de registros:

Writer queue is full. Ignoring event

Se você encontrar essa mensagem, aumente o parâmetro dwhassessment.hook.queue.capacity.

Tradutor de SQL interativo

As seções a seguir descrevem erros comuns encontrados ao usar o conversor de SQL interativo.

Problemas de tradução do RelationNotFound ou AttributeNotFound

Depois de traduzir uma consulta usando o tradutor de SQL interativo, você pode encontrar uma tradução com falha com o erro RelationNotFound ou AttributeNotFound.

Para encontrar traduções com falha, acesse a página Detalhes da tradução no BigQuery no console Google Cloud e abra a guia Mensagens de registro.

Para garantir a conversão mais precisa, insira as instruções da linguagem de definição de dados (DDL) para todas as tabelas usadas em uma consulta antes da consulta em si. Por exemplo, para traduzir a consulta do Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, insira as seguintes instruções SQL no tradutor de SQL interativo:

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Corrigir problemas de tradução com o Gemini

Para corrigir jobs de tradução com falha com os erros RelationNotFound ou AttributeNotFound, também é possível usar o Gemini para resolver esses problemas:

  1. No BigQuery do console Google Cloud , acesse a página Detalhes da tradução e abra a guia Mensagens de registro.
  2. Clique na consulta que tem a mensagem RelationNotFound ou AttributeNotFound na coluna Categoria.
  3. Clique em Correção sugerida.
  4. Clique em Aplicar.
  5. Para traduzir a consulta de novo, clique em Traduzir.

Tradutor de SQL em lote

As seções a seguir descrevem erros comuns encontrados ao usar o conversor de SQL em lote.

Problemas de tradução do RelationNotFound ou AttributeNotFound

Depois de traduzir uma consulta usando o tradutor de SQL em lote, você pode encontrar uma tradução com falha com o erro RelationNotFound ou AttributeNotFound.

Para encontrar traduções com falha, acesse a página Detalhes da tradução no BigQuery no console Google Cloud e abra a guia Mensagens de registro.

A tradução funciona melhor com DDLs de metadados. Quando as definições de objetos SQL não são encontradas, o mecanismo de tradução gera problemas RelationNotFound ou AttributeNotFound. Recomendamos o uso do extrator de metadados para gerar pacotes de metadados e garantir que todas as definições de objetos estejam presentes. Adicionar metadados é a primeira etapa recomendada para resolver a maioria dos erros de tradução, porque geralmente corrige muitos outros erros causados indiretamente pela falta de metadados.

Para mais informações, consulte Gerar metadados para tradução e avaliação.

Corrigir problemas de tradução com o Gemini

Para corrigir jobs de tradução com falha com os erros RelationNotFound ou AttributeNotFound, também é possível usar o Gemini para resolver esses problemas:

  1. Acesse a página Detalhes da tradução e abra a guia Mensagens de registro.
  2. Clique na consulta que tem a mensagem RelationNotFound ou AttributeNotFound na coluna Categoria.

  3. Para acessar o arquivo e a linha que contêm o erro na guia "Código", clique no

    mensagem de erro.

  4. Na coluna Ação, clique em Correção sugerida.

  5. Selecione uma das seguintes opções: Aplicar ou Aplicar e executar novamente:

    • Para copiar o arquivo de esquema gerado do diretório de saída para o de entrada, clique em Aplicar.
    • Para copiar o arquivo de esquema gerado do diretório de saída para o de entrada e abrir uma janela de nova execução, clique em Aplicar e executar novamente.

Gerar metadados para tradução e avaliação

As seções a seguir explicam alguns problemas comuns e técnicas de resolução para a ferramenta dwh-migration-dumper.

Erro por falta de memória

O erro java.lang.OutOfMemoryError na saída do terminal da ferramenta dwh-migration-dumper geralmente está relacionado à memória insuficiente para processar os dados recuperados. Para resolver esse problema, aumente a memória disponível ou reduza o número de linhas de execução de processamento.

É possível aumentar a memória máxima exportando a variável de ambiente JAVA_OPTS:

Linux 

export JAVA_OPTS="-Xmx4G"

Windows 

set JAVA_OPTS="-Xmx4G"

Reduza o número de linhas de execução de processamento (o padrão é 32) incluindo o valor da flag --thread-pool-size. Essa opção é compatível apenas com os conectores hiveql e redshift*:

dwh-migration-dumper --thread-pool-size=1

Como processar um erro WARN...Task failed

Às vezes, pode ser exibido um erro WARN [main] o.c.a.d.MetadataDumper [MetadataDumper.java:107] Task failed: … na saída do terminal da ferramenta dwh-migration-dumper. A ferramenta de extração envia várias consultas ao sistema de origem, e a saída de cada consulta é gravada no próprio arquivo. Esse problema indica que uma dessas consultas falhou. No entanto, a falha de uma consulta não impede a execução das outras. Se você encontrar mais de alguns erros WARN, analise os detalhes do problema e confira se há algo que precisa ser corrigido para que a consulta seja executada corretamente. Por exemplo, se o usuário do banco de dados especificado ao executar a ferramenta de extração não tiver permissões para ler todos os metadados, tente de novo com um usuário com as permissões corretas.

Arquivo ZIP corrompido

Para validar o arquivo ZIP da ferramenta dwh-migration-dumper, faça o download do arquivo SHA256SUMS.txt e execute o seguinte comando:

Bash 

sha256sum --check SHA256SUMS.txt

O resultado OK confirma a verificação com êxito do checksum. Qualquer outra mensagem indica um erro de verificação:

  • FAILED: computed checksum did NOT match: o arquivo ZIP está corrompido e precisa ser baixado novamente.
  • FAILED: listed file could not be read: não é possível localizar a versão do arquivo ZIP. Faça o download do checksum e dos arquivos ZIP da mesma versão de lançamento e coloque-os no mesmo diretório.

Windows PowerShell 

(Get-FileHash RELEASE_ZIP_FILENAME).Hash -eq ((Get-Content SHA256SUMS.txt) -Split " ")[0]

Substitua RELEASE_ZIP_FILENAME pelo nome de arquivo ZIP baixado da versão da ferramenta de extração de linha de comando dwh-migration-dumper, por exemplo, dwh-migration-tools-v1.0.52.zip.

O resultado True confirma a verificação com êxito do checksum.

O resultado False indica um erro de verificação. Faça o download do checksum e dos arquivos ZIP da mesma versão de lançamento e coloque-os no mesmo diretório.

A extração de registros de consulta do Teradata é lenta

Para melhorar o desempenho da mesclagem de tabelas especificadas pelas flags -Dteradata-logs.query-logs-table e -Dteradata-logs.sql-logs-table, inclua mais uma coluna do tipo DATE na condição JOIN. Essa coluna precisa ser definida em ambas as tabelas e fazer parte do índice primário particionado. Para incluir essa coluna, use a flag -Dteradata-logs.log-date-column.

O exemplo a seguir mostra como usar a flag -Dteradata-logs.log-date-column:

Bash

dwh-migration-dumper \
  -Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV \
  -Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl \
  -Dteradata-logs.log-date-column=ArchiveLogDate

Windows PowerShell

dwh-migration-dumper `
  "-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV" `
  "-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl" `
  "-Dteradata-logs.log-date-column=ArchiveLogDate"

O limite de tamanho das linhas do Teradata foi excedido

O Teradata versão 15 tem um limite de tamanho de linha de 64 KB. Se o limite for excedido, a ferramenta de extração vai falhar com a seguinte mensagem:

[Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

Para resolver esse erro, aumente o limite para 1 MB ou divida as linhas em várias linhas:

  • Instale e ative o recurso de linhas de resposta e de permissões de 1 MB e o software TTU atual. Para mais informações, consulte a mensagem 9804 do banco de dados do Teradata.
  • Divida o texto longo de consulta em várias linhas usando as flags -Dteradata.metadata.max-text-length e -Dteradata-logs.max-sql-length.

O comando a seguir mostra como usar a flag -Dteradata.metadata.max-text-length para dividir o texto de consulta longo em várias linhas de, no máximo, 10.000 caracteres cada:

Bash

dwh-migration-dumper \
  --connector teradata \
  -Dteradata.metadata.max-text-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata `
  "-Dteradata.metadata.max-text-length=10000"

O comando a seguir mostra como usar a flag -Dteradata-logs.max-sql-length para dividir o texto de consulta longo em várias linhas de, no máximo, 10.000 caracteres cada:

Bash

dwh-migration-dumper \
  --connector teradata-logs \
  -Dteradata-logs.max-sql-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata-logs `
  "-Dteradata-logs.max-sql-length=10000"

Problema de conexão com o Oracle

Em casos comuns, como uma senha ou um nome de host inválido, a ferramenta dwh-migration-dumper imprime uma mensagem de erro significativa descrevendo o problema principal. No entanto, em alguns casos, a mensagem de erro retornada pelo servidor Oracle pode ser genérica e difícil de investigar.

Um desses problemas é IO Error: Got minus one from a read call. Esse erro indica que a conexão com o servidor Oracle foi estabelecida, mas o servidor não aceitou o cliente e fechou a conexão. Esse problema geralmente ocorre quando o servidor aceita apenas conexões TCPS. Por padrão, a ferramenta dwh-migration-dumper usa o protocolo TCP. Para resolver esse problema, você precisa substituir o URL de conexão JDBC do Oracle.

Em vez de fornecer as flags oracle-service, host e port, resolva esse problema fornecendo a flag url no seguinte formato: jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE. Normalmente, o número da porta TCPS usado pelo servidor Oracle é 2484.

O exemplo a seguir mostra como especificar o URL de conexão no comando:

dwh-migration-dumper \
  --connector oracle-stats \
  --url "jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE" \
  --assessment \
  --driver "JDBC_DRIVER_PATH" \
  --user "USER" \
  --password

Além de mudar o protocolo de conexão para TCPS, talvez seja necessário fornecer a configuração SSL trustStore necessária para verificar o certificado do servidor Oracle. Uma configuração SSL ausente resulta em uma mensagem de erro Unable to find valid certification path. Para resolver esse problema, defina a variável de ambiente JAVA_OPTS:

set JAVA_OPTS=-Djavax.net.ssl.trustStore="JKS_FILE_LOCATION" -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword="PASSWORD"

Dependendo da configuração do servidor Oracle, talvez seja necessário fornecer a configuração do keyStore. Para mais informações sobre opções de configuração, consulte SSL com o driver JDBC do Oracle.

A seguir