Modello SourceDB to Spanner

Il modello SourceDB to Spanner è una pipeline batch che copia i dati da un database relazionale in un database Spanner esistente. Questa pipeline utilizza JDBC per connettersi al database relazionale. Puoi utilizzare questo modello per copiare i dati da qualsiasi database relazionale con driver JDBC disponibili in Spanner. Supporta solo un insieme limitato di tipi di MySQL

Per un ulteriore livello di protezione, puoi anche passare una chiave Cloud KMS insieme a parametri di nome utente, password e stringa di connessione codificati in Base64 criptati con la chiave Cloud KMS. Consulta l'endpoint Crittografia API Cloud KMS per ulteriori dettagli sulla crittografia dei parametri della stringa di connessione, del nome utente e della password.

Requisiti della pipeline

  • I driver JDBC per il database relazionale devono essere disponibili.
  • Le tabelle Spanner devono esistere prima dell'esecuzione della pipeline.
  • Le tabelle Spanner devono avere uno schema compatibile.
  • Il database relazionale deve essere accessibile dalla subnet in cui viene eseguito Dataflow.

Parametri del modello

Parametri obbligatori

  • sourceConfigURL: l'URL del file di configurazione della connessione di origine. Il formato del file dipende dal tipo di origine. Per Astra, punterà a un file di configurazione della connessione Astra (esempio). Per JDBC, punterà a un file di configurazione dello sharding JDBC (sample). Per Cassandra, punterà a un file di configurazione del driver Cassandra (sample). Questo parametro è obbligatorio. Ad esempio, gs://your-bucket/source-config.json. Il valore predefinito è vuoto.
  • instanceId: l'istanza Cloud Spanner di destinazione.
  • databaseId: il database Cloud Spanner di destinazione.
  • projectId: il nome del progetto Cloud Spanner.
  • outputDirectory: questa directory viene utilizzata per scaricare i record non riusciti/ignorati/filtrati in una migrazione.

Parametri facoltativi

  • sourceDbDialect: i valori possibili sono CASSANDRA, MYSQL, POSTGRESQL, ORACLE e SQLSERVER. Il valore predefinito è MYSQL.
  • jdbcDriverJars: l'elenco separato da virgole dei file JAR del driver. Ad esempio, gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar. Il valore predefinito è vuoto.
  • jdbcDriverClassName: il nome della classe del driver JDBC. Ad esempio, com.mysql.jdbc.Driver. Il valore predefinito è: com.mysql.jdbc.Driver.
  • tables: tabelle da migrare dall'origine. Il valore predefinito è vuoto.
  • numPartitions: il numero di partizioni. Questo valore, insieme al limite inferiore e superiore, forma gli intervalli di partizione per le espressioni della clausola WHERE generate utilizzate per dividere in modo uniforme la colonna di partizione. Quando l'input è inferiore a 1, il numero viene impostato su 1. Il valore predefinito è 0.
  • fetchSize: il numero di righe da recuperare per pagina letta per l'origine JDBC. Se non impostato, viene dedotto automaticamente dal tipo di macchina worker e dalla dimensione stimata della riga, tornando a 50.000 righe se non può essere dedotto (ad esempio, quando il tipo di macchina worker non è specificato). Se il dialetto di origine è MySQL, consulta la nota riportata di seguito. che alla fine si traduce nella chiamata Statement.setFetchSize a livello JDBC. Deve essere utilizzato SOLO se il valore predefinito genera errori di memoria.Nota per l'origine MySQL: FetchSize viene ignorato dal connettore MySQL a meno che useCursorFetch=true non faccia parte anche delle proprietà di connessione. Per il dialetto MySQL, la pipeline aggiungerà useCursorFetch=true alle proprietà di connessione per impostazione predefinita, a meno che il parametro fetchSize non sia impostato esplicitamente su 0.
  • spannerHost: l'endpoint Cloud Spanner da chiamare nel modello. Ad esempio, https://batch-spanner.googleapis.com. Il valore predefinito è https://batch-spanner.googleapis.com.
  • maxConnections: configura il pool di connessioni JDBC su ogni worker con il numero massimo di connessioni. Utilizza un numero negativo per nessun limite. Ad esempio, -1. Il valore predefinito è 0.
  • sessionFilePath: percorso del file di sessione in Cloud Storage che contiene le informazioni di mappatura di Spanner Migration Tool. Il valore predefinito è vuoto.
  • transformationJarPath: percorso jar personalizzato in Cloud Storage che contiene la logica di trasformazione personalizzata per l'elaborazione dei record. Il valore predefinito è vuoto.
  • transformationClassName: nome completo della classe con la logica di trasformazione personalizzata. È un campo obbligatorio se viene specificato transformationJarPath. Il valore predefinito è vuoto.
  • transformationCustomParameters: stringa contenente eventuali parametri personalizzati da passare alla classe di trasformazione personalizzata. Il valore predefinito è vuoto.
  • insertOnlyModeForSpannerMutations: per impostazione predefinita, la pipeline utilizza Upsert per scrivere righe in Spanner. Ciò significa che le righe esistenti verranno sovrascritte. Se la modalità InsertOnly è attivata, vengono utilizzati gli inserimenti anziché gli upsert e le righe esistenti non vengono sovrascritte.
  • batchSizeForSpannerMutations: BatchSize in byte per le mutazioni di Spanner. Se impostato su un valore inferiore a 0, viene utilizzato il valore predefinito di SpannerIO di Apache Beam, ovvero 1 MB. Imposta questo valore su 0 o 10 per disattivare il raggruppamento delle mutazioni.
  • spannerPriority: la priorità della richiesta per le chiamate Cloud Spanner. Il valore deve essere uno dei seguenti: [HIGH,MEDIUM,LOW]. Il valore predefinito è HIGH.
  • tableOverrides: questi sono gli override del nome della tabella dall'origine a Spanner. Sono scritte nel seguente formato: [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. Questo esempio mostra la mappatura della tabella Singers a Vocalists e della tabella Albums a Records. Ad esempio, [{Singers, Vocalists}, {Albums, Records}]. Il valore predefinito è vuoto.
  • columnOverrides: questi sono gli override dei nomi delle colonne dall'origine a Spanner. Sono scritte nel seguente formato: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. Tieni presente che SourceTableName deve rimanere invariato sia nella coppia di origine sia in Spanner. Per ignorare i nomi delle tabelle, utilizza tableOverrides.L'esempio mostra la mappatura di SingerName a TalentName e di AlbumName a RecordName rispettivamente nelle tabelle Singers e Albums. Ad esempio, [{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}]. Il valore predefinito è vuoto.
  • schemaOverridesFilePath: un file che specifica le sostituzioni del nome della tabella e della colonna dall'origine a Spanner. Il valore predefinito è vuoto.
  • uniformizationStageCountHint: suggerimento per il numero di fasi di uniformazione. Attualmente applicabile solo alle origini basate su JDBC come MySQL o PostgreSQL. Lascia 0 o il valore predefinito per disattivare l'uniformazione. Imposta il valore -1 per un numero di fasi pari a log(numPartition). Se lo spazio della chiave primaria di origine è distribuito in modo uniforme (ad esempio una chiave a incremento automatico con buchi sparsi), è consigliabile lasciarlo disattivato. Se lo spazio delle chiavi non è uniforme, potresti riscontrare una VM in ritardo nell'esecuzione del dataflow. In questo caso, puoi impostarlo su -1 per attivare l'uniformazione. Se lo imposti manualmente su valori diversi da 0 o -1, puoi perfezionare il compromesso tra l'overhead aggiunto dalle fasi di uniformazione e il miglioramento del rendimento dovuto a una migliore distribuzione del lavoro.
  • failureInjectionParameter: parametro di inserimento dell'errore. Utilizzato solo per i test. Il valore predefinito è vuoto.
  • maxCommitDelay: tempo massimo di ritardo del commit per ottimizzare il throughput di scrittura in Spanner. Fai riferimento a https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set -1 per consentire a Spanner di scegliere il valore predefinito. Imposta un valore positivo per eseguire l'override per il compromesso più adatto tra velocità effettiva e latenza.Il valore predefinito è -1.
  • gcsOutputDirectory: questa directory viene utilizzata per scrivere i file AVRO dei record letti dall'origine. Ad esempio, gs://your-bucket/your-path. Il valore predefinito è vuoto.
  • disabledAlgorithms: algoritmi separati da virgole da disattivare. Se questo valore è impostato su none, nessun algoritmo viene disattivato. Utilizza questo parametro con cautela, perché gli algoritmi disabilitati per impostazione predefinita potrebbero presentare vulnerabilità o problemi di prestazioni. Ad esempio: SSLv3, RC4.
  • extraFilesToStage: percorsi Cloud Storage o secret Secret Manager separati da virgole per i file da preparare nel worker. Questi file vengono salvati nella directory /extra_files di ogni worker. Ad esempio, gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>.

Esegui il modello

Console

  1. Vai alla pagina Crea job da modello di Dataflow.
    2. Vai a Crea job da modello
  2. Nel campo Nome job, inserisci un nome univoco per il job.
  3. (Facoltativo) Per Endpoint a livello di regione, seleziona un valore dal menu a discesa. La regione predefinita è us-central1.

    Per un elenco delle regioni in cui puoi eseguire un job Dataflow, vedi Località Dataflow.

  4. Dal menu a discesa Modello Dataflow, seleziona il modello Sourcedb to Spanner.
  5. Nei campi dei parametri forniti, inserisci i valori dei parametri.
  6. Fai clic su Esegui job.

gcloud CLI

Nella shell o nel terminale, esegui il modello:

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,\

Sostituisci quanto segue:

  • JOB_NAME: un nome univoco del job a tua scelta
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

    • latest per utilizzare l'ultima versione del modello, disponibile nella cartella principale senza data nel bucket: gs://dataflow-templates/latest/
    • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che si trova nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates/
  • REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • SOURCE_CONFIG_URL: l'URL per connettersi all'host del database di origine. Può essere 1. L'URL di connessione JDBC, che deve contenere l'host, la porta e il nome del database di origine e può contenere facoltativamente proprietà come autoReconnect, maxReconnects e così via. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Il percorso di configurazione dello shard
  • INSTANCE_ID: l'ID istanza Cloud Spanner.
  • DATABASE_ID: l'ID del database Cloud Spanner.
  • PROJECT_ID: l'ID progetto Cloud Spanner.
  • OUTPUT_DIRECTORY: la directory di output per gli eventi non riusciti/ignorati/filtrati

API

Per eseguire il modello utilizzando l'API REST, invia una richiesta POST HTTP. Per saperne di più sull'API e sui relativi ambiti di autorizzazione, consulta 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" }
  }
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud in cui vuoi eseguire il job Dataflow
  • JOB_NAME: un nome univoco del job a tua scelta
  • VERSION: la versione del modello che vuoi utilizzare

    Puoi utilizzare i seguenti valori:

    • latest per utilizzare l'ultima versione del modello, disponibile nella cartella principale senza data nel bucket: gs://dataflow-templates/latest/
    • il nome della versione, ad esempio 2023-09-12-00_RC00, per utilizzare una versione specifica del modello, che si trova nidificata nella rispettiva cartella principale con data nel bucket: gs://dataflow-templates/
  • LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempio us-central1
  • SOURCE_CONFIG_URL: l'URL per connettersi all'host del database di origine. Può essere 1. L'URL di connessione JDBC, che deve contenere l'host, la porta e il nome del database di origine e può contenere facoltativamente proprietà come autoReconnect, maxReconnects e così via. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Il percorso di configurazione dello shard
  • INSTANCE_ID: l'ID istanza Cloud Spanner.
  • DATABASE_ID: l'ID del database Cloud Spanner.
  • PROJECT_ID: l'ID progetto Cloud Spanner.
  • OUTPUT_DIRECTORY: la directory di output per gli eventi non riusciti/ignorati/filtrati