Exportar bancos de dados do Spanner para o Avro

Esta página descreve como exportar bancos de dados do Spanner com o Console do Google Cloud.

Para exportar um banco de dados do Spanner usando a API REST ou a Google Cloud CLI, conclua as etapas do Antes de começar nesta página e consulte a instruções detalhadas no Spanner para o Cloud Storage Avro no na documentação do Dataflow. O processo de exportação usa o Dataflow e grava dados em uma pasta em um bucket do Cloud Storage. A pasta resultante contém um conjunto de Arquivos Avro e arquivos de manifesto JSON.

Antes de começar

Para exportar um banco de dados do Spanner, primeiro você precisa ativar as instâncias do Spanner, Cloud Storage Compute Engine e APIs 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 exportação são os seguintes:

• Spanner: nenhuma capacidade extra de computação é necessária para exportar um banco de dados, embora 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 exportar, crie um bucket para os arquivos exportados, caso ainda não tenha um. É possível fazer isso no console do Google Cloud, na página do Cloud Storage ou ao criar a exportação na página do Spanner. Não é preciso definir um tamanho para o bucket.
• Cloud Dataflow: os jobs de exportaçã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 exportaçã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 exportaçã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 ter 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 de armazenamento (roles/storage.admin)
• Leitor de banco de dados do Spanner (roles/spanner.databaseReader)
• Administrador de banco de dados (roles/spanner.databaseAdmin)

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

Para usar os recursos de computação independentes do Data Boost do Spanner durante uma exportação, você também precisa da permissão spanner.databases.useDataBoost do IAM. Para mais informações, consulte Visão geral do Data Boost.

Exportar um banco de dados

Depois de atender aos requisitos de cota e IAM descritos antes era possível exportar um banco de dados atual do Spanner.

Observação: é seguro exportar um banco de dados que está em uso. No entanto, as alterações que você fazer depois que o Dataflow criar uma transação do Spanner não são capturados pela exportação, porque todos os dados exportados são do mesmo do banco de dados.

Para exportar seu banco de dados do Spanner para um Cloud Storage do bucket, siga estas etapas:

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

   Acesse "Instâncias"

2. Clique no nome da instância que contém o banco de dados.

3. Clique no item de menu Importar/Exportar no painel esquerdo e clique no Botão Exportar.

4. Em Escolha onde armazenar sua exportação, clique em Procurar.

5. Se você ainda não tiver um bucket do Cloud Storage para sua exportação:

   1. Clique em Novo bucket .
   2. Digite um nome para o bucket. Os nomes de intervalos precisam ser exclusivos no Cloud Storage.
   3. Selecione uma classe e um local de armazenamento padrão e clique em Criar.
   4. Clique no bucket para selecioná-lo.

   Se você já tiver um bucket, selecione-o na lista inicial ou clique em Pesquisar para filtrar a lista. Depois, clique no seu bucket para selecioná-lo.

6. Clique em Selecionar.

7. Selecione o banco de dados que você quer exportar no menu suspenso Escolher um banco de dados para exportar.

8. Opcional: para exportar o banco de dados de um momento anterior, verifique o e digite um carimbo de data/hora.

9. Selecione uma região no menu suspenso Escolha uma região para o job de exportação.

   Observação: para evitar cobranças de transferência de dados, escolha uma região que se sobreponha à configuração da instância. Para mais informações, consulte Escolha uma região.

10. Opcional: para criptografar o estado do pipeline do Dataflow com uma chave de criptografia gerenciada pelo cliente:

    1. Clique em Mostrar opções de criptografia.
    2. Selecione Usar uma chave de criptografia gerenciada pelo cliente (CMEK).
    3. Selecione a chave na lista suspensa.

    Essa opção não afeta a criptografia no nível do bucket do Cloud Storage de destino. Para ativar as CMEKs no bucket do Cloud Storage, consulte Usar CMEK com o Cloud Storage.

11. Opcional: para exportar usando o Data Boost do Spanner, selecione a caixa de seleção Usar o Data Boost do Spanner. Para mais informações, consulte Visão geral do Data Boost.

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

13. Clique em Exportar.

    O console do Google Cloud mostra a página Importação/exportação do banco de dados. que agora mostra um item de linha para seu job de exportação nos jobs de importação/exportação incluindo o tempo decorrido do job:

    

Quando o job termina ou é encerrado, o status é atualizado no lista. Se o job for bem-sucedido, o status Concluído será exibido:

Se o job falhar, o status Concluído será exibido:

Para conferir os detalhes da operação do Dataflow, clique no nome do job na coluna Nome do job do Dataflow.

Se o job falhar, verifique os registros do Dataflow do job para ter acesso aos detalhes do erro.

Para evitar cobranças do Cloud Storage por arquivos criados por um job que falhou, exclua a pasta e seus arquivos. Consulte Como visualizar sua exportação para informações sobre como encontrar a pasta.

Uma observação sobre como exportar colunas geradas e fluxo de alterações

Os valores em uma coluna gerada armazenada não são exportados. A definição da coluna é exportada para o esquema do Avro como um campo de registro do tipo nulo, com a definição da coluna como propriedades personalizadas do campo. Até que o preenchimento de uma coluna recém-adicionada for concluída, a coluna gerada será ignorada como se não existisse no esquema.

Os streams de alterações exportados como arquivos Avro contêm apenas o esquema do fluxo de alterações e nenhum registro de alteração de dados.

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

As sequências (GoogleSQL, PostgreSQL) são objetos de esquema usados para gerar valores inteiros exclusivos. O Spanner exporta cada objeto de esquema para o esquema Avro como um campo record, com seu tipo de sequência, intervalo ignorado e contador como propriedades do campo. Para evitar que uma sequência seja redefinida e gere valores duplicados após a importação, durante a exportação do esquema, a função GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) captura o contador de sequência. O Spanner adiciona um buffer 1.000 no contador e grava o novo valor do contador no campo de registro. Essa abordagem evita erros de valor duplicado que podem ocorrer após a importação. Se houver mais gravações no banco de dados de origem durante a exportação de dados, ajustar o contador de sequência real usando a função ALTER SEQUENCE. (GoogleSQL, PostgreSQL) instrução.

Na importação, a sequência começa a partir desse novo contador, em vez do contador encontrado no esquema. Como alternativa, use ALTER SEQUENCE (GoogleSQL, PostgreSQL) para atualizar a sequência com um novo contador.

Ver sua exportação no Cloud Storage

Para visualizar a pasta que contém o banco de dados exportado no console do Google Cloud, acesse o navegador do Cloud Storage e escolha o bucket selecionado anteriormente:

Acesse Navegador do Storage

O bucket agora contém uma pasta com o banco de dados exportado. O nome da pasta começa com o código da instância, o nome do banco de dados e o carimbo de data e hora do seu 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 arquivo ChangeStreamName.avro-00000-of-00001 para cada fluxo de mudanças. Este arquivo contém dados vazios apenas com o esquema Avro do fluxo de alterações.

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 uma região dupla, aproveite o uso gratuito da rede escolhendo uma das duas regiões que compõem a região dupla para o job de importação, assumindo que uma das regiões esteja disponível.

• Se uma região colocalizada não estiver disponível para o job de importação ou se o local do bucket do Cloud Storage for uma multirregional, serão aplicadas cobranças de transferência de dados de saída. 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.

Exportar um subconjunto de tabelas

Se você quiser exportar apenas os dados de determinadas tabelas, e não o banco de dados inteiro, especifique essas tabelas durante a exportação. Nesse caso, o Spanner exporta o esquema inteiro do banco de dados, incluindo os dados das tabelas especificadas, e deixa todas as outras tabelas presentes, mas vazias no arquivo exportado.

Você pode especificar um subconjunto de tabelas a serem exportadas usando o página do Dataflow no console do Google Cloud ou CLI gcloud. A página do Spanner não oferece essa ação.

Se você exportar os dados de uma tabela filha de outra, também exporte os dados da tabela mãe. Se os pais não forem exportados, o job de exportação falhará.

Para exportar um subconjunto de tabelas, inicie a exportação usando o modelo do Spanner para Avro do Cloud Storage do Dataflow e especifique as tabelas usando a página do Dataflow no console do Google Cloud ou a CLI gcloud, conforme descrito:

Console

Se você estiver usando a página do Dataflow no console do Google Cloud, o parâmetro Nome(s) da tabela do Cloud Spanner estará localizado na seção Parâmetros opcionais da página Criar job a partir de modelo. Várias tabelas podem ser especificadas em um formato separado por vírgulas.

Acessar o Dataflow

gcloud

Execute o gcloud dataflow jobs run. e especifique o argumento tableNames. Exemplo:

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

A especificação de várias tabelas no gcloud requer a escape de argumento do tipo de dicionário. O exemplo a seguir usa "|" como caractere de escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

O parâmetro shouldExportRelatedTables é uma opção conveniente para exportar automaticamente todas as tabelas pai das tabelas escolhidas. Por exemplo, nesta hierarquia de esquema com as tabelas Singers, Albums e Songs, você só precisa especificar Songs. A opção shouldExportRelatedTables também vai exportar Singers e Albums porque Songs é descendente de ambos.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Conferir ou resolver problemas de jobs na interface do Dataflow

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

Conferir os detalhes do job do Dataflow

Para acessar detalhes de qualquer job de importação ou exportação que você executou na última semana, incluindo todos 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 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 do Google Cloud.

   Acessar "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 acessar os registros de um job do Dataflow, acesse os detalhes dele 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 do 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 abrir o conteúdo dela.

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

Resolver problemas de jobs de exportaçã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 leitura de 99% no guia Monitoramento do banco de dados do Spanner, console do Google Cloud. Se ele mostra valores altos (vários segundos), indica que a instância está sobrecarregada, fazendo com que as leituras atinjam o tempo limite 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.

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

Console

No console do Dataflow, o Número máximo de workers está localizado na seção Parâmetros opcionais do Página Criar job usando um modelo.

Acessar o Dataflow

gcloud

Execute o comando gcloud dataflow jobs run e especifique o argumento max-workers. Exemplo:

  gcloud dataflow jobs run my-export-job \
    --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,outputDir=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 supõe que você pretende usar uma rede VPC de modo automático chamada default no mesmo projeto da job do Dataflow. Se você não tiver uma rede VPC padrão na projeto ou, caso sua rede VPC esteja em uma rede VPC de modo personalizado, criar um job do Dataflow e especifique uma rede ou sub-rede alternativa.

Otimizar jobs de exportaçã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 referente a esse job 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 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 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 exportação

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

• Tamanho do banco de dados do Spanner: o processamento de mais dados leva mais tempo e exige mais 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 fluxos de mudança

• Local 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.

• Carga atual no Spanner: Um job de exportação normalmente adiciona uma carga leve ao Spanner. instância. 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.