Modelo do Sourcedb para o Spanner

O modelo do SourceDB para Spanner é um pipeline em lote que copia dados de um banco de dados relacional para um banco de dados do Spanner. Esse pipeline usa o JDBC para se conectar ao banco de dados relacional. É possível usar esse modelo para copiar dados de qualquer banco de dados relacional com drivers JDBC disponíveis no Spanner. Isso só é compatível com um conjunto limitado de tipos do MySQL

Para ter uma camada extra de proteção, é possível transmitir uma chave do Cloud KMS com um nome de usuário, senha e parâmetros da string de conexão criptografados em Base64 com a chave do Cloud KMS. Consulte o endpoint de criptografia da API Cloud KMS para saber mais detalhes sobre como criptografar o nome de usuário, senha e parâmetros da string de conexão.

Requisitos de pipeline

  • É necessário que os drivers do JDBC para o banco de dados relacional estejam disponíveis.
  • As tabelas do Spanner precisam existir antes da execução do pipeline.
  • As tabelas do Spanner precisam ter um esquema compatível.
  • O banco de dados relacional precisa estar acessível na sub-rede em que o Dataflow é executado.

Parâmetros do modelo

Parâmetros obrigatórios

  • sourceConfigURL: o URL do arquivo de configuração da conexão de origem. O formato do arquivo depende do tipo de origem. Para o Astra, ele vai apontar para um arquivo de configuração de conexão do Astra (exemplo). Para JDBC, ele vai apontar para um arquivo de configuração de fragmentação JDBC (exemplo). Para o Cassandra, ele vai apontar para um arquivo de configuração do driver do Cassandra (sample). Este parâmetro é obrigatório. Por exemplo, gs://your-bucket/source-config.json. O padrão é vazio.
  • instanceId: a instância de destino do Cloud Spanner.
  • databaseId: o banco de dados de destino do Cloud Spanner.
  • projectId: o nome do projeto do Cloud Spanner.
  • outputDirectory: esse diretório é usado para despejar os registros com falha/ignorados/filtrados em uma migração.

Parâmetros opcionais

  • sourceDbDialect: os valores possíveis são CASSANDRA, MYSQL, POSTGRESQL, ORACLE e SQLSERVER. O padrão é: MYSQL.
  • jdbcDriverJars: a lista separada por vírgulas de arquivos JAR do driver. Por exemplo, gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar. O padrão é vazio.
  • jdbcDriverClassName: o nome da classe do driver do JDBC. Por exemplo, com.mysql.jdbc.Driver. O padrão é: com.mysql.jdbc.Driver.
  • tables: tabelas para migrar da origem. O padrão é vazio.
  • numPartitions: o número de partições. Isso, junto com os limites inferior e superior, cria avanços de partições para expressões da cláusula WHERE geradas, usadas para dividir a coluna da partição de maneira uniforme. Quando a entrada for menor que 1, o número será definido como 1. Padrão: 0.
  • fetchSize: o número de linhas a serem buscadas por leitura de página para a origem JDBC. Se não for definido, ele será inferido automaticamente do tipo de máquina do worker e do tamanho estimado da linha, voltando para 50.000 linhas se não for possível inferir (por exemplo, quando o tipo de máquina do worker não é especificado). Se o dialeto de origem for MySQL, consulte a observação abaixo. Isso acabou sendo traduzido para a chamada Statement.setFetchSize na camada Jdbc. Ele SÓ deve ser usado se o valor padrão gerar erros de memória.Observação para a origem do MySQL: FetchSize é ignorado pelo conector do MySQL, a menos que useCursorFetch=true também faça parte das propriedades de conexão. Para o dialeto MySql, o pipeline adiciona useCursorFetch=true às propriedades de conexão por padrão, a menos que o parâmetro fetchSize seja definido explicitamente como 0.
  • spannerHost: o endpoint do Cloud Spanner para chamar no modelo. Por exemplo, https://batch-spanner.googleapis.com. O padrão é: https://batch-spanner.googleapis.com.
  • maxConnections: configura o pool de conexões JDBC em cada worker com o número máximo de conexões. Use um número negativo para não haver limite. Por exemplo, -1. Padrão: 0.
  • sessionFilePath: o caminho do arquivo de sessão no Cloud Storage que contém informações de mapeamento da ferramenta de migração do Spanner. O padrão é vazio.
  • transformationJarPath: local do jar personalizado no Cloud Storage que contém a lógica de transformação personalizada para processar registros. O padrão é vazio.
  • transformationClassName: o nome de classe totalmente qualificado com lógica de transformação personalizada. É um campo obrigatório no caso de transformationJarPath é especificado. O padrão é vazio.
  • transformationCustomParameters: string contendo os parâmetros personalizados que serão passados para a classe de transformação personalizada. O padrão é vazio.
  • insertOnlyModeForSpannerMutations: por padrão, o pipeline usa Upserts para gravar linhas no Spanner. Isso significa que as linhas atuais seriam substituídas. Se o modo "InsertOnly" estiver ativado, as inserções serão usadas em vez de upserts, e as linhas atuais não serão substituídas.
  • batchSizeForSpannerMutations: BatchSize em bytes para mutações do Spanner. Se definido como menor que 0, será usado o padrão do SpannerIO do Apache Beam, que é de 1 MB. Defina como 0 ou 10 para desativar as mutações em lote.
  • spannerPriority: a prioridade da solicitação para chamadas do Cloud Spanner. O valor precisa ser um destes: [HIGH,MEDIUM,LOW]. O padrão é HIGH.
  • tableOverrides: substituições de nome de tabela da origem para o Spanner. Eles são gravados no seguinte formato: [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. Este exemplo mostra o mapeamento da tabela "Singers" para "Vocalists" e da tabela "Albums" para "Records". Por exemplo, [{Singers, Vocalists}, {Albums, Records}]. O padrão é vazio.
  • columnOverrides: substituições de nome de coluna da origem para o Spanner. Eles são gravados no seguinte formato: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. O SourceTableName precisa permanecer o mesmo no par de origem e Spanner. Para substituir nomes de tabelas, use tableOverrides.O exemplo mostra o mapeamento de SingerName para TalentName e AlbumName para RecordName nas tabelas "Singers" e "Albums", respectivamente. Por exemplo, [{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}]. O padrão é vazio.
  • schemaOverridesFilePath: um arquivo que especifica as substituições de nome da tabela e da coluna da origem para o Spanner. O padrão é vazio.
  • uniformizationStageCountHint: dica para o número de etapas de uniformização. No momento, aplicável apenas a fontes baseadas em JDBC, como MySQL ou PostgreSQL. Deixe 0 ou o padrão para desativar a uniformização. Defina como -1 para um número log(numPartition) de estágios. Se o espaço de chave primária de origem for distribuído uniformemente (por exemplo, uma chave de incremento automático com lacunas esparsas), é melhor deixar desativado. Se o keyspace não for uniforme, você poderá encontrar uma VM lenta na execução do Dataflow. Nesse caso, defina como -1 para ativar a uniformização. Definir manualmente valores diferentes de 0 ou -1 ajuda a ajustar a compensação da sobrecarga adicionada pelas etapas de uniformização e a melhoria de performance devido a uma melhor distribuição do trabalho.
  • failureInjectionParameter: parâmetro de injeção de falha. Usado apenas para testes. O padrão é vazio.
  • maxCommitDelay: tempo máximo de atraso do commit para otimizar a capacidade de processamento de gravação no Spanner. Consulte https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set como -1 para permitir que o Spanner escolha o padrão. Defina um valor positivo para substituir a compensação mais adequada de capacidade de processamento x latência.O padrão é -1.
  • gcsOutputDirectory: usado para gravar os arquivos AVRO dos registros lidos da origem. Por exemplo, gs://your-bucket/your-path. O padrão é vazio.
  • disabledAlgorithms: algoritmos separados por vírgula a serem desativados. Se esse valor for definido como none, nenhum algoritmo será desativado. Use esse parâmetro com cuidado, porque os algoritmos desativados por padrão podem ter vulnerabilidades ou problemas de desempenho. Por exemplo, SSLv3, RC4.
  • extraFilesToStage: caminhos do Cloud Storage separados por vírgulas ou secrets do Secret Manager para que os arquivos sejam organizados no worker. Esses arquivos são salvos no diretório /extra_files em cada worker. Por exemplo, gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>.

Executar o modelo

Console

  1. Acesse a página Criar job usando um modelo do Dataflow.
    2. Acesse Criar job usando um modelo
  2. No campo Nome do job, insira um nome exclusivo.
  3. Opcional: em Endpoint regional, selecione um valor no menu suspenso. A região padrão é us-central1.

    Para ver uma lista de regiões em que é possível executar um job do Dataflow, consulte Locais do Dataflow.

  4. No menu suspenso Modelo do Dataflow, selecione o modelo Sourcedb para Spanner.
  5. Nos campos de parâmetro fornecidos, insira os valores de parâmetro.
  6. Cliquem em Executar job.

CLI da gcloud

No shell ou no terminal, execute o modelo:

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --parameters \
       sourceConfigURL=SOURCE_CONFIG_URL,\
       instanceId=INSTANCE_ID,\
       databaseId=DATABASE_ID,\
       projectId=PROJECT_ID,\
       outputDirectory=OUTPUT_DIRECTORY,\

Substitua:

  • JOB_NAME: um nome de job de sua escolha
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

    • latest para usar a versão mais recente do modelo, disponível na pasta mãe não datada no bucket: gs://dataflow-templates/latest/
    • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser aninhada na respectiva pasta mãe datada no bucket: gs://dataflow-templates
  • REGION_NAME: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
  • SOURCE_CONFIG_URL: o URL para se conectar ao host do banco de dados de origem. Pode ser um destes valores: O URL de conexão JDBC, que precisa conter o host, a porta e o nome do banco de dados de origem e pode conter, opcionalmente, propriedades como autoReconnect, maxReconnects etc. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. O caminho da configuração do fragmento
  • INSTANCE_ID: o ID da instância do Cloud Spanner.
  • DATABASE_ID: o ID do banco de dados do Cloud Spanner.
  • PROJECT_ID: o ID do projeto do Cloud Spanner.
  • OUTPUT_DIRECTORY: o diretório de saída para eventos com falha/ignorados/filtrados

API

Para executar o modelo usando a API REST, envie uma solicitação HTTP POST. Para mais informações sobre a API e os respectivos escopos de autorização, consulte projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "sourceConfigURL": "SOURCE_CONFIG_URL",
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "projectId": "PROJECT_ID",
       "outputDirectory": "OUTPUT_DIRECTORY",
     },
     "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex",
     "environment": { "maxWorkers": "10" }
  }
}

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud em que você quer executar o job do Dataflow
  • JOB_NAME: um nome de job de sua escolha
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

    • latest para usar a versão mais recente do modelo, disponível na pasta mãe não datada no bucket: gs://dataflow-templates/latest/
    • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser aninhada na respectiva pasta mãe datada no bucket: gs://dataflow-templates
  • LOCATION: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
  • SOURCE_CONFIG_URL: o URL para se conectar ao host do banco de dados de origem. Pode ser um destes valores: O URL de conexão JDBC, que precisa conter o host, a porta e o nome do banco de dados de origem e pode conter, opcionalmente, propriedades como autoReconnect, maxReconnects etc. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. O caminho da configuração do fragmento
  • INSTANCE_ID: o ID da instância do Cloud Spanner.
  • DATABASE_ID: o ID do banco de dados do Cloud Spanner.
  • PROJECT_ID: o ID do projeto do Cloud Spanner.
  • OUTPUT_DIRECTORY: o diretório de saída para eventos com falha/ignorados/filtrados