Importar arquivos Avro do Spanner

Nesta página, descrevemos como importar bancos de dados do Spanner para o Spanner usando o console Google Cloud . Para importar arquivos Avro de outra fonte, consulte Importar dados de bancos de dados que não são do Spanner.

O processo usa o Dataflow. Ele importa dados de uma pasta de bucket do Cloud Storage que contém um conjunto de arquivos Avro (em inglês) e arquivos de manifesto JSON. O processo de importação só é compatível com arquivos Avro exportados do Spanner.

Para importar um banco de dados do Spanner usando a API REST ou o gcloud CLI, conclua as etapas na seção Antes de começar desta página e consulte as instruções detalhadas em Avro do Cloud Storage para Spanner.

Antes de começar

Para importar um banco de dados do Spanner, primeiro você precisa ativar as APIs Spanner, Cloud Storage, Compute Engine e Dataflow:

Enable the APIs

É preciso também ter cota suficiente e as permissões obrigatórias do IAM.

Requisitos de cota

Os requisitos de cota para jobs de importação são os seguintes:

• Spanner: é preciso ter capacidade de computação suficiente para aceitar a quantidade de dados que você está importando. Nenhuma capacidade de computação extra é necessária para importar um banco de dados, mas talvez seja necessário adicionar mais capacidade de computação para que o job seja concluído em um período razoável. Consulte Otimizar jobs para mais detalhes.
• Cloud Storage: para importar, é preciso ter um bucket contendo os arquivos exportados anteriormente. Não é necessário definir um tamanho para o bucket.
• Dataflow: os jobs de importação estão sujeitos às mesmas cotas do Compute Engine para endereço IP, uso da CPU e do disco aplicadas a outros jobs do Dataflow.

• Compute Engine: antes de executar um job de importação, é necessário configurar cotas iniciais para o Compute Engine, que serão usadas pelo Dataflow. Essas cotas representam o número máximo de recursos que você permite que o Dataflow use para seu job. Os valores iniciais recomendados são:

  • CPUs: 200
  • Endereços IP em uso: 200
  • Disco permanente padrão: 50 TB

  Geralmente, não é necessário fazer nenhum outro ajuste. O Dataflow fornece escalonamento automático para que você pague apenas pelos recursos efetivamente utilizados durante a importação. Se seu job puder usar mais recursos, a IU do Dataflow exibirá um ícone de aviso. O job será concluído, mesmo que um ícone de aviso seja exibido.

Funções exigidas

Para receber as permissões necessárias para exportar um banco de dados, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço do worker do Dataflow:

• Leitor do Cloud Spanner (roles/spanner.viewer)
• Worker do Dataflow (roles/dataflow.worker)
• Administrador do Storage (roles/storage.admin)
• Leitor de banco de dados do Spanner (roles/spanner.databaseReader)
• Administrador de banco de dados (roles/spanner.databaseAdmin)

Opcional: como localizar sua pasta de banco de dados no Cloud Storage

Para encontrar a pasta que contém o banco de dados exportado no console doGoogle Cloud , acesse o navegador do Cloud Storage e clique no bucket que contém a pasta exportada.

Acessar o navegador do Cloud Storage

O nome da pasta que contém os dados exportados começa com o código da instância, o nome do banco de dados e o carimbo de data/hora do job de exportação. A pasta contém:

• Um arquivo spanner-export.json
• Um arquivo TableName-manifest.json para cada tabela do banco de dados exportado

• Um ou mais arquivos TableName.avro-#####-of-##### O primeiro número na extensão .avro-#####-of-##### representa o índice do arquivo Avro, a partir de zero. O segundo representa o número de arquivos Avro gerados para cada tabela.

  Por exemplo, Songs.avro-00001-of-00002 é o segundo de dois arquivos que contêm os dados da tabela Songs.

• Um arquivo ChangeStreamName-manifest.json para cada fluxo de alterações no banco de dados exportado.

• Um arquivo ChangeStreamName.avro-00000-of-00001 para cada fluxo de mudanças. Esse arquivo contém dados vazios com apenas o esquema Avro do fluxo de alterações.

Importar um banco de dados

Para importar um banco de dados do Spanner do Cloud Storage para sua instância, siga estas etapas.

1. Acesse a página Instâncias do Spanner.

   Acesse a página "Instâncias".

2. Clique no nome da instância que conterá o banco de dados importado.

3. Clique no item de menu Import/Export no painel esquerdo e clique no botão Import.

4. Em Escolher uma pasta de origem, clique em Procurar.

5. Encontre o bucket que contém a exportação na lista inicial ou clique em Pesquisar para filtrar a lista e localizar o bucket. Clique duas vezes no bucket para ver as pastas dele.

6. Encontre a pasta com os arquivos exportados e clique para selecioná-la.

7. Clique em Selecionar.

8. Digite um nome para o novo banco de dados que o Spanner cria durante o processo de importação. O nome escolhido para o banco de dados não pode ser um que já exista em sua instância.

9. Escolha o dialeto do novo banco de dados (GoogleSQL ou PostgreSQL).

10. (Opcional) Para proteger o novo banco de dados com uma chave de criptografia gerenciada pelo cliente, clique em Mostrar opções de criptografia e selecione Usar uma chave de criptografia gerenciada pelo cliente (CMEK). Em seguida, selecione uma chave na lista suspensa.

11. Selecione uma região no menu suspenso Escolha uma região para o job de importação.

12. Opcional: para criptografar o estado do pipeline do Dataflow com uma chave de criptografia gerenciada pelo cliente, clique em Mostrar opções de criptografia e selecione Usar. uma chave de criptografia gerenciada pelo cliente (CMEK). Em seguida, selecione uma chave na lista suspensa.

13. Marque a caixa de seleção em Confirmar cobranças para confirmar que há cobranças além das referentes à sua instância atual do Spanner.

14. Clique em Importar.

    O console do Google Cloud mostra a página Detalhes do banco de dados, que agora exibe uma caixa descrevendo o job de importação, incluindo o tempo decorrido para sua realização:

    

Quando o job é finalizado ou encerrado, o console do Google Cloud exibe uma mensagem na página Detalhes do banco de dados. Se o job for bem-sucedido, será exibida uma mensagem de sucesso:

Se o job não for bem-sucedido, será exibida uma mensagem de falha:

Se o job falhar, verifique os registros do Dataflow do job para ver os detalhes do erro e consulte Resolver problemas de jobs de importação com falha.

Observação sobre a importação de colunas geradas e fluxo de alterações

O Spanner usa a definição de cada coluna gerada no esquema Avro para recriar essa coluna. O Spanner calcula os valores de coluna gerados automaticamente durante a importação.

Da mesma forma, o Spanner usa a definição de cada fluxo de mudanças no esquema Avro para recriá-lo durante a importação. Os dados do fluxo de alterações não são exportados nem importados pelo Avro. Portanto, todos os fluxo de alterações associados a um banco de dados recém-importado não terão registros de dados de alteração.

Observação sobre a importação de sequências

Cada sequência (GoogleSQL, PostgreSQL) que o Spanner exporta usa a função GET_INTERNAL_SEQUENCE_STATE()(GoogleSQL, PostgreSQL) para capturar o estado atual. O Spanner adiciona um buffer de 1.000 ao contador e grava o novo valor nas propriedades do campo de registro. Essa é apenas uma abordagem de melhor esforço para evitar erros de valores duplicados que podem ocorrer após a importação. Ajuste o contador de sequência real se houver mais gravações no banco de dados de origem durante a exportação de dados.

Na importação, a sequência começa com esse novo contador em vez do contador encontrado no esquema. Se necessário, use a instrução ALTER SEQUENCE (GoogleSQL, PostgreSQL) para atualizar para um novo contador.

Observação sobre a importação de tabelas intercaladas e chaves externas

O job do Dataflow pode importar tabelas intercaladas, permitindo que você mantenha as relações mãe-filha do arquivo de origem. No entanto, as restrições de chave externa não são aplicadas durante o carregamento de dados. O job do Dataflow cria todas as chaves estrangeiras necessárias depois que o carregamento de dados é concluído.

Se você tiver restrições chave externa no banco de dados do Spanner antes do início da importação, poderá encontrar erros de gravação devido a violações de integridade referencial. Para evitar erros de gravação, remova as chaves estrangeiras antes de iniciar o processo de importação.

Escolher uma região para o job de importação

Convém escolher uma região diferente com base na localização do bucket do Cloud Storage. Para evitar cobranças de transferência de dados de saída, escolha uma região que corresponda ao local do seu bucket do Cloud Storage.

• Se o local do bucket do Cloud Storage for uma região, você poderá aproveitar o uso gratuito da rede escolhendo a mesma região para o job de importação, desde que ela esteja disponível.

• Se o local do bucket do Cloud Storage for uma birregião, aproveite o uso gratuito da rede escolhendo uma das duas regiões que compõem a birregião para o job de importação, supondo que uma das regiões esteja disponível.

• Se uma região de colocalização não estiver disponível para seu job de importação ou se o local do bucket do Cloud Storage for multirregional, serão aplicadas cobranças de transferência de dados de saída. Consulte os preços de transferência de dados do Cloud Storage para escolher uma região que incorra nas menores tarifas de transferência de dados.

Visualizar ou resolver problemas de jobs na interface do Dataflow

Depois de iniciar um job de importação, é possível ver os detalhes dele, incluindo registros, na seção do Dataflow do Google Cloud console.

Ver detalhes do job do Dataflow

Para ver os detalhes de qualquer job de importação ou exportação executado na última semana, incluindo os jobs em execução no momento:

1. Navegue até a página Detalhes do banco de dados.
2. Clique no item de menu do painel esquerdo Importar/Exportar. A página Importar/Exportar do banco de dados exibe uma lista de jobs recentes.

3. Na página Importar/Exportar do banco de dados, clique no nome do job na coluna Nome do job do Dataflow:

   

   O console Google Cloud mostra detalhes do job do Dataflow.

Para visualizar um job executado há mais de uma semana, siga estas etapas:

1. Acesse a página de jobs do Dataflow no console Google Cloud .

   Acessar "Jobs"

2. Encontre seu job na lista e clique no nome dele.

   O console Google Cloud mostra detalhes do job do Dataflow.

Ver registros do Dataflow para seu job

Para visualizar os registros de um job do Dataflow, navegue até a página de detalhes do job e clique em Registros à direita do nome do job.

Se um job falhar, procure erros nos registros. Se houver erros, a contagem de erros será exibida ao lado de Registros:

Para ver os erros do job, siga estas etapas:

1. Clique na contagem de erros ao lado de Registros.

   O console Google Cloud mostra os registros do job. Pode ser necessário rolar para visualizar os erros.

2. Localize entradas com o ícone de erro .

3. Clique em uma entrada de registro individual para expandir o conteúdo dela.

Para mais informações sobre como solucionar problemas de jobs do Dataflow, consulte Solução de problemas do pipeline.

Resolver problemas de jobs de importação com falha

Se você vir os seguintes erros nos registros do job:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Verifique a latência de gravação de 99% na guia Monitoramento do banco de dados do Spanner no console doGoogle Cloud . Se estiver exibindo valores altos (vários segundos), isso indicará que a instância está sobrecarregada, fazendo com que as gravações expirem e falhem.

Uma causa da alta latência é que o job do Dataflow está sendo executado usando muitos workers, colocando muita carga na instância do Spanner.

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Resolver erros de rede

O seguinte erro pode ocorrer ao exportar seus bancos de dados do Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Esse erro ocorre porque o Spanner presume que você quer usar uma rede VPC de modo automático chamada default no mesmo projeto do job do Dataflow. Se você não tiver uma rede VPC padrão no projeto ou se ela estiver no modo personalizado, será necessário criar um job do Dataflow e especificar uma rede ou sub-rede alternativa.

Otimizar jobs de importação de execução lenta

Se as sugestões das configurações iniciais forem seguidas, geralmente não será necessário fazer nenhum outro ajuste. Se o job estiver sendo executado lentamente, é possível tentar outras otimizações:

• Otimize o local do job e dos dados: execute o job do Dataflow na mesma região em que estão localizados o bucket do Cloud Storage e a instância do Spanner.

• Garanta recursos suficientes do Dataflow: se as cotas relevantes do Compute Engine limitarem os recursos do job do Dataflow, a página do Dataflow no console do Google Cloud vai mostrar um ícone de aviso e mensagens de registro:

  

  Nessa situação, é possível reduzir o ambiente de execução do job aumentando as cotas (em inglês) para CPUs, endereços IP em uso e disco permanente padrão. Porém, isso pode resultar em mais cobranças do Compute Engine.

• Verifique a utilização da CPU do Spanner: se você perceber que a utilização da CPU para a instância é superior a 65%, é possível aumentar a capacidade de computação nessa instância. A capacidade adiciona mais recursos do Spanner e o job precisa acelerar, mas você gera mais cobranças do Spanner.

Fatores que afetam o desempenho do job de importação

Vários fatores influenciam o tempo necessário para concluir um job de importação.

• Tamanho do banco de dados do Spanner: o processamento de mais dados leva mais tempo e exige mais recursos.

• Esquema do banco de dados do Spanner, incluindo:

  • O número de tabelas
  • O tamanho das linhas
  • O número de índices secundários
  • O número de chaves externas
  • O número de fluxo de alterações

A criação do índice e da chave externa continua após a conclusão do job de importação do Dataflow. Os fluxos de mudanças são criados antes da conclusão do job de importação, mas depois que todos os dados são importados.

• Localização dos dados: os dados são transferidos entre o Spanner e o Cloud Storage usando o Dataflow. O ideal é que os três componentes estejam localizados na mesma região. Se não estiverem, a movimentação dos dados pelas regiões prejudica a velocidade de execução do job.

• Número de workers do Dataflow: o número ideal de workers do Dataflow é necessário para um bom desempenho. Ao usar o escalonamento automático, o Dataflow escolhe o número de workers para o job, dependendo da quantidade de trabalho que precisa ser feita. O número de workers, no entanto, será limitado pelas cotas para CPUs, endereços IP em uso e disco permanente padrão. A IU do Dataflow exibirá um ícone de aviso caso encontre limites de cotas. Nessa situação, o progresso será mais lento, mas ainda assim o job será concluído. O escalonamento automático pode sobrecarregar o Spanner, levando a erros quando há uma grande quantidade de dados para importar.

• Carga atual no Spanner: um job de importação adiciona carga significativa da CPU em uma instância do Spanner. Se a instância já tiver uma carga atual substancial, a execução do job será mais lenta.

• Quantidade de capacidade de computação do Spanner: se a utilização da CPU para a instância for superior a 65%, o job será executado mais lentamente.

Ajustar os workers para um bom desempenho de importação

Ao iniciar um job de importação do Spanner, os workers do Dataflow precisam ser definidos como um valor ideal para um bom desempenho. Muitos workers sobrecarregam o Spanner e poucos workers resultam em um desempenho de importação incrível.

O número máximo de workers depende muito do tamanho dos dados, mas o ideal é que a utilização total da CPU do Spanner esteja entre 70% e 90%. Isso fornece um bom equilíbrio entre a eficiência do Spanner e a conclusão de jobs sem erros.

Para atingir essa meta de utilização na maioria dos esquemas e cenários, recomendamos um número máximo de vCPUs de trabalho entre 4 e 6 vezes o número de nós do Spanner.

Por exemplo, para uma instância do Spanner de 10 nós, usando workers n1-standard-2, defina o máximo de workers como 25, fornecendo 50 vCPUs.