Kit de ferramentas de migração do BigQuery para o Datastream

Nesta página, descrevemos as práticas recomendadas ao usar o Datastream para migrar do modelo do Dataflow Datastream para o BigQuery para a solução integrada de replicação do BigQuery.

Antes de começar

As instruções nesta página pressupõem o seguinte:

Ter familiaridade com o Docker e instalado.
Saber clonar repositórios de serviços como o GitHub.
Saber executar streams no Datastream.
Ter instalado a Google Cloud CLI.

Visão geral do kit de ferramentas de migração

O Datastream BigQuery Migration Toolkit é um software de código aberto oferecido pelo Google Cloud. O kit de ferramentas permite migrar do modelo do Datastream para BigQuery do Dataflow, mas também pode ser usado ao migrar de outros pipelines, conforme explicado na seção Migrar de outros pipelines a seguir.

Para migrar as tabelas do BigQuery usando o kit de ferramentas, você precisa executar as seguintes etapas:

Crie, inicie e pause um stream do Datastream com um destino do BigQuery.
Faça a migração em cada tabela do BigQuery que precisa ser migrada.
Retome a transmissão.

O kit de ferramentas faz o seguinte:

Recupera o esquema da tabela de origem usando a API de descoberta do Datastream.
Cria uma tabela do BigQuery compatível com o Datastream com base no esquema recuperado.
Busca o esquema da tabela do BigQuery da qual você está migrando para determinar as conversões necessárias do tipo de dados.
Copia todas as linhas existentes da tabela original para a nova, incluindo o tipo de coluna casts apropriado.

Para mais informações sobre a forma como o kit de ferramentas é estruturado e os argumentos usados, consulte o arquivo README.md do kit de ferramentas.

Configurar o kit de ferramentas de migração

Para executar o kit de ferramentas de migração usando o Docker, siga estas etapas:

Clone o repositório e altere o diretório para ele:

git clone https://github.com/GoogleCloudPlatform/datastream-bigquery-migration-toolkit &&
cd datastream-bigquery-migration-toolkit

Crie a imagem:
```
docker build -t migration-service .
```

Faça a autenticação com suas credenciais do Google Cloud CLI:

docker run -ti \
--name gcloud-config migration-service gcloud auth application-default login

Defina a propriedade do projeto do Google Cloud:
```
docker run -ti --volumes-from gcloud-config migration-service \
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo identificador do seu projeto do Google Cloud.

Migrar do Dataflow para a solução integrada do Datastream

Crie um stream do Datastream com um destino do BigQuery.

Observação :ao configurar a origem, escolha preenchimento manual em Escolher modo de preenchimento para dados históricos.
Inicie o stream e pause imediatamente. Isso permite que o Datastream capture a posição de onde captura as alterações antes do início da migração.

Observação: entre o início e a pausa, o Datastream pode processar alguns eventos e criar uma ou mais tabelas no BigQuery. Nesse caso, você precisa excluir manualmente as tabelas no BigQuery antes de continuar a migração. Caso contrário, ela vai falhar.
Drene o pipeline do Datastream e do Dataflow:
1. Pause o stream de destino do Cloud Storage.
2. Verifique a métrica de latência total do stream e aguarde pelo menos o tempo da latência atual para garantir que todos os eventos em andamento sejam gravados no destino.
3. Drene o job do Dataflow.

Execute a migração:

Faça a migração no modo dry_run. O modo dry_run permite gerar a instrução DDL CREATE TABLE e a instrução SQL para copiar dados, sem executá-las:
```
docker run -v output:/output -ti --volumes-from gcloud-config \
migration-service python3 ./migration/migrate_table.py dry_run \
--project-id PROJECT_ID \
--stream-id STREAM_ID \
--datastream-region STREAM_REGION \
--source-schema-name SOURCE_SCHEMA_NAME \
--source-table-name SOURCE_TABLE_NAME \
--bigquery-source-dataset-name BIGQUERY_SOURCE_DATASET_NAME \
--bigquery-source-table-name BIGQUERY_SOURCE_TABLE_NAME
```
Substitua:
- PROJECT_ID: o identificador exclusivo do seu projeto do Google Cloud.
- STREAM_ID: o identificador exclusivo do fluxo de destino do BigQuery.
- STREAM_REGION: o local da transmissão, por exemplo, us-central1.
- SOURCE_SCHEMA_NAME: o nome do esquema de origem.
- SOURCE_TABLE_NAME: o nome da tabela de origem.
- BIGQUERY_SOURCE_DATASET_NAME: o nome do conjunto de dados atual do BigQuery.
- BIGQUERY_SOURCE_TABLE_NAME: o nome da tabela atual do BigQuery.

Inspecione os arquivos .sql em output/create_target_table e output/copy_rows. Estes são os comandos SQL que serão executados no seu projeto do Google Cloud:

docker run -v output:/output -ti migration-service find output/create_target_table \
-type f -print -exec cat {} \;

docker run -v output:/output -ti migration-service find output/copy_rows \
-type f -print -exec cat {} \;

Para executar os comandos SQL, faça a migração no modo full. O modo full permite criar uma tabela no BigQuery e copiar todas as linhas da tabela do BigQuery atual:

docker run -v output:/output -ti --volumes-from gcloud-config \
migration-service python3 ./migration/migrate_table.py full \
--project-id PROJECT_ID \
--stream-id STREAM_ID \
--datastream-region STREAM_REGION \
--source-schema-name SOURCE_SCHEMA_NAME \
--source-table-name SOURCE_TABLE_NAME \
--bigquery-source-dataset-name BIGQUERY_SOURCE_DATASET_NAME \
--bigquery-source-table-name BIGQUERY_SOURCE_TABLE_NAME

Retomar o stream pausado.
Abra o Explorador de registros do Google Cloud e procure registros do Datastream com a seguinte consulta:
```
resource.type="datastream.googleapis.com/Stream"
resource.labels.stream_id=STREAM_ID
```
Procure o registro a seguir, em que %d é um número:
```
Completed writing %d records into..
```
Esse registro indica que o novo stream carregou dados no BigQuery. Ela só aparece se houver dados do CDC para carregar.

Migrar de outros pipelines

O kit de ferramentas também permite migrar de outros pipelines para a solução integrada do BigQuery no Datastream. O kit de ferramentas pode gerar DDLs CREATE TABLE para tabelas do BigQuery compatíveis com o Datastream, com base no esquema do banco de dados de origem usando o modo dry_run:

  docker run -v output:/output -ti --volumes-from gcloud-config \
  migration-service python3 ./migration/migrate_table.py dry_run \
  --project-id PROJECT_ID \
  --stream-id STREAM_ID \
  --datastream-region STREAM_REGION \
  --source-schema-name SOURCE_SCHEMA_NAME \
  --source-table-name SOURCE_TABLE_NAME \
  --bigquery-source-dataset-name BIGQUERY_SOURCE_DATASET_NAME \
  --bigquery-source-table-name BIGQUERY_SOURCE_TABLE_NAME

Como os esquemas da tabela do BigQuery podem variar, é difícil fornecer uma instrução SQL universal para copiar linhas. É possível usar os esquemas nos diretórios DDL da tabela de origem (output/source_table_ddl) e do diretório DDL da tabela de destino (output/create_target_table) para criar uma instrução SQL com casts apropriados nas colunas de origem.

Veja a seguir um exemplo de formato de instrução SQL que pode ser usado:

  INSERT INTO DESTINATION_TABLE (DESTINATION_COLUMN1, DESTINATION_COLUMN2...)
  SELECT SOURCE_COLUMN1, SOURCE_COLUMN2
  FROM SOURCE_TABLE;

Substitua:

DESTINATION_TABLE: o nome da tabela de destino no BigQuery.
DESTINATION_COLUMN: o nome da coluna na tabela de destino.
SOURCE_COLUMN: o nome da coluna na tabela de origem.
SOURCE_TABLE: o nome da tabela de origem.

Limitações

O kit de ferramentas tem as seguintes limitações:

Os nomes das colunas nas tabelas atuais e novas do BigQuery precisam ser correspondentes (ignorando as colunas de metadados). A migração falhará se você aplicar funções definidas pelo usuário do Dataflow (UDFs) que alteram os nomes das colunas nas tabelas existentes, por exemplo, adicionando um prefixo ou alterando maiúsculas e minúsculas.
Não há suporte para migrações entre regiões e projetos.
A migração funciona por tabela.
Somente origens Oracle e MySQL são compatíveis.