Importar arquivos Avro do Spanner

Nesta página, descrevemos como importar bancos de dados do Spanner para o Spanner usando no console do 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 oferece suporte apenas a arquivos Avro exportados do Spanner.

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

Antes de começar

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

Ative as 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: você precisa ter capacidade de computação suficiente para dar suporte à 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 tarefas 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.

Requisitos do IAM

Para importar um banco de dados, é preciso também ter papéis do IAM com permissões suficientes para usar todos os serviços envolvidos em um job de importação. Para informações sobre como conceder papéis e permissões, consulte Aplicar papéis do IAM.

Para importar um banco de dados, você precisa dos seguintes papéis:

• No nível do projeto do Google Cloud:
  • Leitor do Spanner (roles/spanner.viewer)
  • Administrador do Dataflow (roles/dataflow.admin)
  • Administrador do Storage (roles/storage.admin)
• No nível do banco de dados ou da instância do Spanner ou Nível do projeto do Google Cloud:
  • Leitor de banco de dados do Spanner (roles/spanner.databaseReader)
  • Administrador do banco de dados do Spanner (roles/spanner.databaseAdmin)

.

Observação: o papel de administrador do banco de dados do Spanner é necessário apenas para jobs de importação.

Opcional: encontre a pasta do banco de dados no Cloud Storage

Para localizar a pasta que contém seu banco de dados exportado na console do Google Cloud, acesse o navegador do Cloud Storage e clique em 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 que você exportados.

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

Importar um banco de dados

Para importar o banco de dados do Spanner do Cloud Storage para o exemplo, 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.

   Observação: certifique-se de selecionar a pasta criada pelo job de exportação, e não uma de nível superior que contenha a pasta exportada.

7. Clique em Selecionar.

8. Insira um nome para o novo banco de dados, que o Spanner cria durante a 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 para o 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.

    Observação: para evitar cobranças de transferência de dados de saída, escolha uma região que se sobrepõe ao local do bucket do Cloud Storage. Consulte Escolha uma região abaixo para mais informações.

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á além das cobranças da sua instância atual do Spanner.

14. Clique em Importar.

    O console do Google Cloud exibe a página Detalhes do banco de dados, que agora mostra uma caixa que descreve seu job de importação, incluindo o tempo decorrido horário:

    

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

Observação: depois que o job de importação do Dataflow for concluído, O Spanner cria índices e chaves externas para seu banco de dados importado. Enquanto o índice está em andamento, o console do Google Cloud mostra ícone de progresso para indicar que uma operação de longa duração está ocorrendo. O ícone fica ao lado do nome do índice, na hierarquia do banco de dados à esquerda da página Detalhes do banco de dados. Quando o ícone indicativo de operação em andamento muda para o ícone de índice , significa que o índice foi criado. Você pode consultar SPANNER_STATE na visualização INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS para ver o progresso da criação de chaves estrangeiras.

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

Se o job falhar, verifique se há erros nos registros do Dataflow do job e consulte Resolver problemas em jobs de importação com falha.

Uma 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. Spanner. calcula automaticamente os valores de coluna gerados durante a importação.

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

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

Cada sequência (GoogleSQL, PostgreSQL) que o Spanner exporta usa o método GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) para capturar o estado atual dela. O Spanner adiciona um buffer de 1.000 ao contador e grava o novo do contador para as propriedades do campo de registro. Observe que esta é apenas uma melhor de esforço para evitar erros de valor duplicado que podem acontecer 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 nesse novo contador em vez de no contador encontrados no esquema. Se necessário, use ALTER SEQUENCE (GoogleSQL, PostgreSQL) para atualizar para um novo contador.

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

Você pode escolher uma região diferente com base na localização do bucket do Cloud Storage. Para evitar taxas de transferência de dados de saída, escolha uma região que corresponde ao local do bucket do Cloud Storage.

• Se o local do bucket do Cloud Storage for uma região, podem aproveitar o uso gratuito da rede escolhendo o mesma região para o job de importação, supondo que essa região esteja disponível.

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

• Se uma região colocalizada não estiver disponível para seu job de importação ou se seu O local do bucket do Cloud Storage é um local multirregional, tarifas de transferência de dados de saída se aplicam. Consulte o Cloud Storage os preços de transferência de dados para escolher uma região que incorre no as tarifas mais baixas de transferência de dados.

Visualizar ou solucionar problemas de jobs na IU do Dataflow

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

Mais detalhes do job do Dataflow

Para ver os detalhes de qualquer job de importação/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 do Google Cloud exibe detalhes da API Dataflow trabalho.

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

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

   Ir para a página de jobs

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

   O console do Google Cloud exibe detalhes da API Dataflow trabalho.

Observação: jobs do mesmo tipo no mesmo banco de dados têm nomes iguais. É possível distinguir os jobs pelos valores nas colunas Horário de início ou Horário de término.

Visualizar os registros do Dataflow do job

Para visualizar os registros de um job do Dataflow, navegue até a página de detalhes do job, conforme descrito acima. Em seguida, 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 do Google Cloud exibe 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 seu conteúdo.

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

Resolver problemas de jobs de importação

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.

Consulte o 99% de latência de gravação no guia Monitoramento do banco de dados do Spanner, console do Google 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 das causas de alta latência é que o job do Dataflow está sendo executado usando muitos os workers, sobrecarregando muito a instância do Spanner.

Para especificar um limite para o número de workers do Dataflow, em vez de usar o método Guia "Importar/Exportar" na página de detalhes da instância do Spanner no console do Google Cloud, inicie o usando o Dataflow Modelo do Cloud Storage Avro para Cloud Spanner e especificar o número máximo de workers, conforme descrito abaixo:

• Se você estiver usando o console do Dataflow, o parâmetro Workers máximos estará localizado na seção Parâmetros opcionais da página Criar job a partir do modelo.

• Se você estiver usando o gcloud, especifique o argumento max-workers. Exemplo:

  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
  

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 a instância do Spanner e do bucket do Cloud Storage estão localizados.

• Garanta recursos suficientes do Dataflow: se o cotas relevantes do Compute Engine limitar os recursos do job do Dataflow, Página do Dataflow no console do Google Cloud exibe um ícone de aviso e registrar mensagens:

  

  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 o uso da CPU do Spanner: caso a CPU uso da instância for superior a 65%, é possível aumentar a capacidade de computação da instância. A capacidade aumenta Os recursos do Spanner e o job devem acelerar, mas você incorre em 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 recursos.

• Esquema de 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 estrangeiras
  • O número de fluxo de alterações

O índice e a chave externa a criação continua depois que o job de importação do Dataflow é concluída. Os fluxos de alterações são criados antes da conclusão do job de importação. mas após a importação de todos os dados.

• Local dos dados: os dados são transferidos entre o Spanner e 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 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 da capacidade de computação do Spanner: se a utilização da CPU para a instância for maior que 65%, o job será executado mais lentamente.

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

Ao iniciar um job de importação do Spanner, o Dataflow os workers precisam ser definidos com um valor ideal para ter um bom desempenho. Muitos workers sobrecarrega o Spanner e o número de workers é insuficiente desempenho de importação.

O número máximo de workers depende muito do tamanho dos dados. mas o ideal é que o uso total da CPU do Spanner fique entre 70% a 90%. Isso oferece um bom equilíbrio entre o Spanner e o eficiência e 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 worker entre 4 e 6 vezes o número de nós do Spanner.

Por exemplo, para uma instância de 10 nós do Spanner, use n1-standard-2. workers, você definiria o máximo de workers como 25, ou seja, 50 vCPUs.