Nesta página, descrevemos 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 ferramenta de linha de comando gcloud spanner
, conclua as etapas na seção Antes de começar nesta página e consulte as instruções detalhadas em Spanner para o Avro do Cloud Storage 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 APIs Spanner, Cloud Storage, Compute Engine e Dataflow:
É 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 de computação extra é necessária para exportar um banco de dados, mas pode ser necessário adicionar mais capacidade de computação para que o job seja concluído em um prazo razoável. Veja 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, seja pela página do Cloud Storage ou ao criar sua exportação na página do Spanner. Não é necessário 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
Em geral, 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.
Requisitos do IAM
Para exportar 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 exportação. Para informações sobre como conceder papéis e permissões, consulte Aplicar papéis do IAM.
Para exportar 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
)
- Leitor do Spanner (
- No nível do banco de dados ou da instância do Spanner ou no
nível do projeto do Google Cloud:
- Leitor do banco de dados do Spanner (
roles/spanner.databaseReader
) - Administrador do banco de dados do Spanner (
roles/spanner.databaseAdmin
)
- Leitor do banco de dados do Spanner (
Para usar os recursos de computação independentes do Spanner Data Boost 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 do IAM descritos anteriormente, é possível exportar um banco de dados do Spanner.
Para exportar o banco de dados do Spanner para um bucket do Cloud Storage, siga estas etapas.
Acesse a página Instâncias do Spanner.
Clique no nome da instância que contém o banco de dados.
Clique no item de menu Importar/Exportar no painel esquerdo e depois no botão Exportar.
Em Escolha onde armazenar sua exportação, clique em Procurar.
Caso ainda não tenha um bucket do Cloud Storage para sua exportação, siga estas etapas:
- Clique em Novo bucket .
- Digite um nome para o bucket. Os nomes de intervalos precisam ser exclusivos no Cloud Storage.
- Selecione uma classe e um local de armazenamento padrão e clique em Criar.
- 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.
Clique em Selecionar.
Selecione o banco de dados que você quer exportar no menu suspenso Escolher um banco de dados para exportar.
Opcional: para exportar o banco de dados de um momento anterior, marque a caixa e insira um carimbo de data/hora.
Selecione uma região no menu suspenso Escolha uma região para o job de exportação.
Opcional: para criptografar o estado do pipeline do Dataflow com uma chave de criptografia gerenciada pelo cliente:
- Clique em Mostrar opções de criptografia.
- Selecione Usar uma chave de criptografia gerenciada pelo cliente (CMEK).
- 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 a CMEK no bucket do Cloud Storage, consulte Usar CMEK com o Cloud Storage.
Opcional: para exportar usando o Spanner Data Boost, marque a caixa de seleção Use Spanner Data Boost. Para mais informações, consulte Visão geral do Data Boost.
Marque a caixa de seleção em Confirmar cobranças para confirmar que há cobranças além das referentes à instância atual do Spanner.
Clique em Exportar.
O console do Google Cloud exibe a página Importação/exportação de banco de dados, que agora mostra um item de linha do job de exportação na lista de jobs de importação/exportação, incluindo o tempo decorrido:
Quando o job é concluído ou encerrado, o status é atualizado na lista de importação/exportação. Se o job for bem-sucedido, o status Concluído será exibido:
Se o job falhar, o status Concluído será exibido:
Para ver 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 Visualizar sua exportação para informações sobre como encontrar a pasta.
Observação sobre como exportar as 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 a operação de preenchimento de uma coluna gerada recentemente seja concluída, a coluna gerada será ignorada como se não existisse no esquema.
Os fluxos de alterações exportados como arquivos Avro contêm apenas o esquema dos fluxo de alterações, e não registros 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 um dos objetos de esquema para o esquema do Avro como um campo de registro, com o tipo de sequência, o intervalo ignorado e o contador como propriedades do campo. Para evitar que uma sequência seja redefinida e gera
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 de 1.000 ao 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, ajuste o contador de sequência real usando a instrução ALTER SEQUENCE
(GoogleSQL, PostgreSQL).
Na importação, a sequência começa a partir desse novo contador, em vez do contador encontrado no esquema. Como alternativa, use a instrução ALTER SEQUENCE
(GoogleSQL, PostgreSQL) para atualizar a sequência com um novo contador.
Conferir a exportação no Cloud Storage
Para visualizar a pasta que contém o banco de dados exportado no console do Google Cloud, navegue até o navegador do Cloud Storage e escolha o bucket selecionado anteriormente:
Acessar o navegador do Cloud 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 tabelaSongs
.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 alterações. Esse arquivo contém dados vazios apenas com o esquema Avro do fluxo de alterações.
Escolha uma região para seu job de importação
Convém escolher uma região diferente com base na localização do seu bucket do Cloud Storage. Para evitar cobranças de transferência de dados de saída, escolha uma região que corresponda à localização do seu bucket do Cloud Storage.
Se o local do bucket do Cloud Storage for uma região, aproveite o uso de rede gratuito escolhendo a mesma região para o job de importação, supondo que ela esteja disponível.
Se o local do bucket do Cloud Storage for um local birregional, você poderá aproveitar o uso de rede gratuito escolhendo uma das duas regiões que compõem a região birregional do job de importação, supondo que uma delas 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 multirregional, serão aplicadas as taxas 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 gere as menores cobranças 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 todo o esquema do banco de dados, incluindo os dados das tabelas especificadas, e deixando todas as outras tabelas presentes, mas vazias no arquivo exportado.
É possível especificar um subconjunto de tabelas para exportar usando a página do Dataflow no console do Google Cloud ou a linha de comando. A página do Spanner não fornece essa ação.
Se você exportar os dados de uma tabela que é filha de outra, também precisará exportar os dados da tabela parent. 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 Spanner para o modelo Avro do Cloud Storage e especifique as tabelas usando a página do Dataflow no console do Google Cloud ou a Google Cloud CLI, conforme descrito abaixo:
Console do Google Cloud
Se você estiver usando a página do Dataflow no console do Google Cloud, o parâmetro Nomes da tabela do Cloud Spanner estará localizado na seção Parâmetros opcionais da página Criar job usando um modelo. É possível especificar várias tabelas no formato separado por vírgulas.
CLI da gcloud
Se você estiver usando a Google Cloud CLI, use o argumento tableNames
para especificar a tabela. 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
Especificar várias tabelas em gcloud
requer
o 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
O parâmetro shouldExportRelatedTables
é uma opção conveniente para exportar automaticamente todas as tabelas pai das tabelas desejadas. Por exemplo, nesta hierarquia de esquema
com as tabelas Singers
, Albums
e Songs
, só precisamos especificar Songs
. A
opção shouldExportRelatedTables
também 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
Confira ou resolva problemas de jobs na IU do Dataflow
Depois de iniciar um job de exportação, é possível visualizar detalhes dele, 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:
- Navegue até a página Detalhes do banco de dados.
- 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.
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 do job do Dataflow.
Para visualizar um job executado há mais de uma semana, siga estas etapas:
Acesse a página "Jobs" do Dataflow no console do Google Cloud.
Encontre seu job na lista e clique no nome dele.
O console do Google Cloud exibe detalhes do job do Dataflow.
Conferir os registros do Dataflow para o 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:
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.
Localize entradas com o ícone de erro .
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 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% na guia Monitoramento do banco de dados do Spanner no 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 das causas de alta latência é a execução do job do Dataflow com muitos workers, o que sobrecarrega a instância do Spanner.
Para especificar um limite para o número de workers do Dataflow, em vez de usar a guia "Importar/Exportar" na página de detalhes da instância do banco de dados do Spanner no console do Google Cloud, inicie a exportação usando o modelo Avro do Cloud Spanner para Cloud Storage e especifique 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-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
Otimizar jobs de exportação com 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 a instância do Spanner e o bucket do Cloud Storage.
Garanta recursos suficientes do Dataflow: se as cotas relevantes do Compute Engine limitarem os recursos do job do Dataflow, a página do Dataflow do job no console do Google Cloud exibirá 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%, aumente a capacidade de computação dessa instância. A capacidade adiciona mais recursos do Spanner e o job deve acelerar, mas isso gera mais cobranças.
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 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 estrangeiras
- O número de fluxo de alterações
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.
Carga existente no Spanner: um job de exportação normalmente adiciona uma carga leve a 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.