Il template da SourceDB a Spanner è una pipeline batch che copia i dati da un database relazionale a 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 un nome utente, una password e parametri della stringa di connessione con codifica Base64 criptati con la chiave Cloud KMS. Per ulteriori dettagli sulla crittografia dei parametri di nome utente, password e stringa di connessione, consulta l'endpoint di crittografia dell'API Cloud KMS.
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 file dipende dal tipo di origine. Per Astra, rimanderà a un file di configurazione della connessione Astra (esempio). Per JDBC, rimanderà a un file di configurazione di sharding JDBC (esempio). Per Cassandra, rimanderà a un file di configurazione del driver Cassandra (esempio). 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 eseguire il dump dei record non riusciti/saltati/filtrati in una migrazione.
Parametri facoltativi
- sourceDbDialect: i valori possibili sono
CASSANDRA,MYSQL,POSTGRESQL,ORACLEeSQLSERVER. 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 di cui eseguire la migrazione dall'origine. Il valore predefinito è vuoto.
- numPartitions: il numero di partizioni. Insieme ai limiti inferiore e superiore, formano i passi delle partizioni per le espressioni della clausola WHERE generate utilizzate per suddividere uniformemente la colonna di partizione. Se 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 viene impostato, viene dedotto automaticamente dal tipo di macchina worker e dalla dimensione stimata delle righe, con un valore di riserva di 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 di seguito. Questo si traduce in ultima analisi 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 anche
useCursorFetch=truenon faccia parte delle proprietà di connessione. Per il dialetto MySql, la pipeline aggiungeràuseCursorFetch=truealle 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 template. 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 non impostare limiti. 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 del file 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 è 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 gli upsert per scrivere righe in Spanner. Ciò significa che le righe esistenti verranno sovrascritte. Se la modalità InsertOnly è attiva, verranno utilizzati gli inserimenti anziché gli upsert e le righe esistenti non verranno sovrascritte.
- batchSizeForSpannerMutations: BatchSize in byte per le mutazioni Spanner. Se il 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 in batch 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: si tratta delle sostituzioni dei nomi delle tabelle dall'origine a Spanner. Sono scritti 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: si tratta delle sostituzioni dei nomi delle colonne dall'origine a Spanner. Sono scritti nel seguente formato: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]Tieni presente che SourceTableName deve rimanere invariato sia nella coppia di origine che in quella di Spanner. Per eseguire l'override dei 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 gli override dei nomi delle tabelle e delle colonne dall'origine a Spanner. Il valore predefinito è vuoto.
- uniformizationStageCountHint: suggerimento per il numero di fasi di uniformizzazione. Attualmente applicabile solo per le origini basate su JDBC come MySQL o PostgreSQL. Lascia 0 o il valore predefinito per disattivare l'uniformizzazione. Imposta su -1 per un numero di fasi log(numPartition). Se lo spazio della chiave primaria di origine è distribuito in modo uniforme (ad esempio una chiave con incremento automatico con spazi vuoti sparsi), è consigliabile lasciarlo disattivato. Se lo spazio delle chiavi non è uniforme, potresti riscontrare una VM in ritardo nell'esecuzione di Dataflow. In questo caso, puoi impostarlo su -1 per attivare l'uniformizzazione. L'impostazione manuale di valori diversi da 0 o -1 ti aiuterà a ottimizzare il compromesso tra l'overhead aggiunto dalle fasi di uniformizzazione e il miglioramento delle prestazioni dovuto a una migliore distribuzione del lavoro.
- failureInjectionParameter: parametro di inserimento di errori. Utilizzato solo per i test. Il valore predefinito è vuoto.
- maxCommitDelay: tempo di ritardo massimo del commit per ottimizzare il throughput di scrittura in Spanner. Consulta https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set. Imposta -1 per consentire a Spanner di scegliere il valore predefinito. Imposta un valore positivo per eseguire l'override per il miglior compromesso tra throughput 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 da disattivare separati da virgole. Se questo valore è impostato su
none, non viene disattivato alcun algoritmo. Utilizza questo parametro con cautela, perché gli algoritmi disattivati per impostazione predefinita potrebbero presentare vulnerabilità o problemi di prestazioni. Ad esempio:SSLv3, RC4. - extraFilesToStage: percorsi Cloud Storage o secret di Secret Manager separati da virgole per i file di cui eseguire la gestione temporanea 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
- Vai alla pagina Crea job da modello di Dataflow. Vai a Crea job da modello
- Nel campo Nome job, inserisci un nome job univoco.
- (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, consulta Località di Dataflow.
- Dal menu a discesa Modello Dataflow, seleziona il modello Sourcedb to Spanner.
- Nei campi dei parametri forniti, inserisci i valori dei parametri.
- Fai clic su Esegui job.
gcloud CLI
Nella shell o nel terminale, esegui il template:
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 job univoco di tua sceltaVERSION: la versione del template che vuoi utilizzarePuoi utilizzare i seguenti valori:
latestper utilizzare l'ultima versione del template, disponibile nella cartella padre 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 template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
REGION_NAME: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1SOURCE_CONFIG_URL: l'URL per connettersi all'host del database di origine. Può essere uno dei seguenti: 1. L'URL di connessione JDBC, che deve contenere l'host, la porta e il nome del database di origine e può facoltativamente contenere proprietà come autoReconnect, maxReconnects e così via. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Il percorso di configurazione dello shardINSTANCE_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/saltati/filtrati
API
Per eseguire il template 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 DataflowJOB_NAME: un nome job univoco di tua sceltaVERSION: la versione del template che vuoi utilizzarePuoi utilizzare i seguenti valori:
latestper utilizzare l'ultima versione del template, disponibile nella cartella padre 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 template, che si trova nidificata nella rispettiva cartella padre con data nel bucket: gs://dataflow-templates/
LOCATION: la regione in cui vuoi eseguire il deployment del job Dataflow, ad esempious-central1SOURCE_CONFIG_URL: l'URL per connettersi all'host del database di origine. Può essere uno dei seguenti: 1. L'URL di connessione JDBC, che deve contenere l'host, la porta e il nome del database di origine e può facoltativamente contenere proprietà come autoReconnect, maxReconnects e così via. Formato: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Il percorso di configurazione dello shardINSTANCE_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/saltati/filtrati