Vorlage „Sourcedb zu Spanner“

Die Vorlage "SourceDB zu Spanner" ist eine Batchpipeline, die Daten aus einer relationalen Datenbank in eine vorhandene Spanner-Datenbank kopiert. Diese Pipeline verwendet JDBC, um eine Verbindung zur relationalen Datenbank herzustellen. Sie können mit dieser Vorlage Daten aus einer beliebigen relationalen Datenbank mit den verfügbaren JDBC-Treibern nach Spanner kopieren. Dies wird nur für eine begrenzte Anzahl von MySQL-Typen unterstützt.

Als zusätzliche Schutzmaßnahme können Sie einen Cloud KMS-Schlüssel zusammen mit einem Base64-codierten Nutzernamen, Passwort und Verbindungsstring-Parametern übergeben, die mit dem Cloud KMS-Schlüssel verschlüsselt sind. Weitere Informationen zum Verschlüsseln von Nutzernamen, Passwörtern und Verbindungsstring-Parametern finden Sie unter Cloud KMS API-Verschlüsselungsendpunkt.

Pipelineanforderungen

  • Die JDBC-Treiber für die relationale Datenbank müssen verfügbar sein.
  • Die Spanner-Tabellen müssen vor der Pipelineausführung vorhanden sein.
  • Die Spanner-Tabellen müssen ein kompatibles Schema haben.
  • Die relationale Datenbank muss über das Subnetz zugänglich sein, in dem Dataflow ausgeführt wird.

Vorlagenparameter

Erforderliche Parameter

  • sourceConfigURL: Die URL der Konfigurationsdatei für die Quellverbindung. Das Dateiformat hängt vom Quelltyp ab. Für Astra verweist sie auf eine Astra-Verbindungskonfigurationsdatei (Beispiel). Bei JDBC verweist sie auf eine JDBC-Sharding-Konfigurationsdatei (sample). Für Cassandra verweist sie auf eine Cassandra-Treiberkonfigurationsdatei (sample). Das ist ein erforderlicher Parameter. Zum Beispiel: gs://your-bucket/source-config.json. Die Standardeinstellung ist leer.
  • instanceId: Die Cloud Spanner-Zielinstanz.
  • databaseId: Die Ziel-Cloud Spanner-Datenbank.
  • projectId: Der Name des Cloud Spanner-Projekts.
  • outputDirectory: Dieses Verzeichnis wird verwendet, um die fehlgeschlagenen/übersprungenen/gefilterten Datensätze bei einer Migration zu verschieben.

Optionale Parameter

  • sourceDbDialect: Mögliche Werte sind CASSANDRA, MYSQL, POSTGRESQL, ORACLE und SQLSERVER. Die Standardeinstellung ist MYSQL.
  • jdbcDriverJars: Die durch Kommas getrennte Liste der JAR-Dateien des Treibers. Beispiel: gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar. Die Standardeinstellung ist leer.
  • jdbcDriverClassName: Der Name der JDBC-Treiberklasse. Beispiel: com.mysql.jdbc.Driver. Die Standardeinstellung ist: com.mysql.jdbc.Driver.
  • tables: Tabellen, die von der Quelle migriert werden sollen. Die Standardeinstellung ist leer.
  • numPartitions: Die Anzahl der Partitionen. Damit bilden zusammen mit der Unter- und Obergrenze die Partitionsschritte für generierte WHERE-Klauselausdrücke, die zum gleichmäßigen Aufteilen der Partitionsspalte verwendet werden. Wenn die Eingabe kleiner als 1 ist, wird die Zahl auf 1 gesetzt. Die Standardeinstellung ist 0.
  • fetchSize: Die Anzahl der Zeilen, die pro gelesener Seite für die JDBC-Quelle abgerufen werden sollen. Wenn nicht festgelegt, wird sie automatisch aus dem Worker-Maschinentyp und der geschätzten Zeilengröße abgeleitet. Wenn sie nicht abgeleitet werden kann (z. B. wenn der Worker-Maschinentyp nicht angegeben ist), wird auf 50.000 Zeilen zurückgegriffen. Wenn der Quelldialekt MySQL ist, lesen Sie bitte den Hinweis unten. Dies führte letztendlich zu einem Statement.setFetchSize-Aufruf auf der JDBC-Ebene. Er sollte NUR verwendet werden, wenn der Standardwert Speicherfehler verursacht.Hinweis für MySQL-Quelle: FetchSize wird vom MySQL-Connector ignoriert, sofern useCursorFetch=true nicht auch Teil der Verbindungseigenschaften ist. Beim MySQL-Dialekt wird der Pipeline standardmäßig useCursorFetch=true zu den Verbindungseigenschaften hinzugefügt, sofern der Parameter „fetchSize“ nicht explizit auf 0 gesetzt ist.
  • spannerHost: Der Cloud Spanner-Endpunkt, der in der Vorlage aufgerufen werden soll. Beispiel: https://batch-spanner.googleapis.com. Die Standardeinstellung ist https://batch-spanner.googleapis.com.
  • maxConnections: Konfiguriert den JDBC-Verbindungspool auf jedem Worker mit der maximalen Anzahl von Verbindungen. Verwenden Sie eine negative Zahl, wenn es kein Limit geben soll. Beispiel: -1. Die Standardeinstellung ist 0.
  • sessionFilePath: Pfad der Sitzungsdatei in Cloud Storage, die Zuordnungsinformationen aus dem Spanner Migration Tool enthält. Die Standardeinstellung ist leer.
  • transformationJarPath: Speicherort der benutzerdefinierten JAR-Datei in Cloud Storage, die die benutzerdefinierte Transformationslogik für die Verarbeitung von Datensätzen enthält. Die Standardeinstellung ist leer.
  • transformationClassName: Voll qualifizierter Klassenname mit der benutzerdefinierten Transformationslogik. Es ist ein Pflichtfeld, wenn „transformationJarPath“ angegeben ist. Die Standardeinstellung ist leer.
  • transformationCustomParameters: String mit allen benutzerdefinierten Parametern, die an die benutzerdefinierte Transformationsklasse übergeben werden sollen. Die Standardeinstellung ist leer.
  • insertOnlyModeForSpannerMutations: Standardmäßig werden in der Pipeline Upserts verwendet, um Zeilen in Spanner zu schreiben. Das bedeutet, dass vorhandene Zeilen überschrieben werden. Wenn der InsertOnly-Modus aktiviert ist, werden Einfügungen anstelle von Upserts verwendet und vorhandene Zeilen werden nicht überschrieben.
  • batchSizeForSpannerMutations: BatchSize in Bytes für Spanner-Mutationen. Wenn der Wert kleiner als 0 ist, wird der Standardwert von Apache Beam's SpannerIO verwendet, der 1 MB beträgt. Legen Sie diesen Wert auf 0 oder 10 fest, um das Zusammenfassen von Mutationen zu deaktivieren.
  • spannerPriority: Die Anfragepriorität für Cloud Spanner-Aufrufe. Der Wert muss einer der folgenden sein: [HIGH,MEDIUM,LOW]. Der Standardwert ist HIGH.
  • tableOverrides: Dies sind die Überschreibungen des Tabellennamens von der Quelle zu Spanner. Sie werden im folgenden Format geschrieben: [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. In diesem Beispiel wird die Tabelle „Singers“ der Tabelle „Vocalists“ und die Tabelle „Albums“ der Tabelle „Records“ zugeordnet. Beispiel: [{Singers, Vocalists}, {Albums, Records}]. Die Standardeinstellung ist leer.
  • columnOverrides: Dies sind die Überschreibungen für Spaltennamen von der Quelle zu Spanner. Sie werden im folgenden Format geschrieben: [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. Der SourceTableName sollte sowohl im Quell- als auch im Spanner-Paar gleich bleiben. Wenn Sie Tabellennamen überschreiben möchten, verwenden Sie „tableOverrides“. Im Beispiel wird „SingerName“ in der Tabelle „Singers“ (Sänger) „TalentName“ und „AlbumName“ in der Tabelle „Albums“ (Alben) „RecordName“ zugeordnet. Beispiel: [{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}]. Die Standardeinstellung ist leer.
  • schemaOverridesFilePath: Eine Datei, in der die Überschreibungen für Tabellen- und Spaltennamen von der Quelle zu Spanner angegeben werden. Die Standardeinstellung ist leer.
  • uniformizationStageCountHint: Hinweis zur Anzahl der Uniformierungsphasen. Derzeit nur für JDBC-basierte Quellen wie MySQL oder PostgreSQL anwendbar. Lassen Sie das Feld leer oder verwenden Sie den Standardwert, um die Vereinheitlichung zu deaktivieren. Auf -1 setzen, um log(numPartition) Phasen zu verwenden. Wenn der primäre Quellschlüsselbereich gleichmäßig verteilt ist (z. B. ein automatisch inkrementierender Schlüssel mit wenigen Lücken), sollte die Funktion deaktiviert bleiben. Wenn Ihr Schlüsselbereich nicht einheitlich ist, kann es in Ihrem Dataflow-Lauf zu einer langsamen VM kommen. In diesem Fall können Sie den Wert auf -1 setzen, um die Uniformisierung zu aktivieren. Wenn Sie den Wert manuell auf einen anderen Wert als 0 oder -1 setzen, können Sie den Kompromiss zwischen dem durch die Vereinheitlichungsphasen verursachten Mehraufwand und der Leistungssteigerung aufgrund einer besseren Verteilung der Arbeit optimieren.
  • failureInjectionParameter: Parameter für die Fehlereinschleusung. Wird nur zum Testen verwendet. Die Standardeinstellung ist leer.
  • maxCommitDelay: Die maximale Commit-Verzögerungszeit, um den Schreibdurchsatz in Spanner zu optimieren. Weitere Informationen finden Sie unter https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set. Setzen Sie den Wert auf -1, damit Spanner den Standardwert auswählt. Wenn Sie einen positiven Wert festlegen, wird der optimale Kompromiss zwischen Durchsatz und Latenz überschrieben.Der Standardwert ist -1.
  • gcsOutputDirectory: In dieses Verzeichnis werden die AVRO-Dateien der aus der Quelle gelesenen Datensätze geschrieben. Beispiel: gs://your-bucket/your-path. Die Standardeinstellung ist leer.
  • disabledAlgorithms: Durch Kommas getrennte Algorithmen zum Deaktivieren. Wenn dieser Wert auf none gesetzt ist, wird kein Algorithmus deaktiviert. Verwenden Sie diesen Parameter mit Vorsicht, da die standardmäßig deaktivierten Algorithmen Sicherheitslücken oder Leistungsprobleme haben können. Beispiel: SSLv3, RC4
  • extraFilesToStage: Durch Kommas getrennte Cloud Storage-Pfade oder Secret Manager-Secrets für Dateien, die im Worker bereitgestellt werden sollen. Diese Dateien werden im Verzeichnis /extra_files in jedem Worker gespeichert. Beispiel: gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>.

Führen Sie die Vorlage aus.

Console

  1. Rufen Sie die Dataflow-Seite Job aus Vorlage erstellen auf.
    2. Zur Seite "Job aus Vorlage erstellen“
  2. Geben Sie im Feld Jobname einen eindeutigen Jobnamen ein.
  3. Optional: Wählen Sie für Regionaler Endpunkt einen Wert aus dem Drop-down-Menü aus. Die Standardregion ist us-central1.

    Eine Liste der Regionen, in denen Sie einen Dataflow-Job ausführen können, finden Sie unter Dataflow-Standorte.

  4. Wählen Sie im Drop-down-Menü Dataflow-Vorlage die Vorlage Sourcedb to Spanner aus.
  5. Geben Sie Ihre Parameterwerte in die Parameterfelder ein.
  6. Klicken Sie auf Job ausführen.

gcloud-CLI

Führen Sie die Vorlage in der Shell oder im Terminal aus:

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

Ersetzen Sie Folgendes:

  • JOB_NAME: Ein eindeutiger Jobname Ihrer Wahl
  • VERSION: Die Version der Vorlage, die Sie verwenden möchten

    Sie können die folgenden Werte verwenden:

    • latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates/latest/.
    • Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates/.
  • REGION_NAME: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • SOURCE_CONFIG_URL: URL zum Herstellen einer Verbindung zum Quelldatenbankhost. Es kann Folgendes sein: 1. Die JDBC-Verbindungs-URL, die den Host, den Port und den Namen der Quelldatenbank enthalten muss und optional Attribute wie „autoReconnect“ und „maxReconnects“ enthalten kann. Format: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Der Pfad zur Shard-Konfiguration
  • INSTANCE_ID: Die Cloud Spanner-Instanz-ID.
  • DATABASE_ID: die Cloud Spanner-Datenbank-ID
  • PROJECT_ID: die Cloud Spanner-Projekt-ID.
  • OUTPUT_DIRECTORY: das Ausgabeverzeichnis für fehlgeschlagene/übersprungene/gefilterte Ereignisse

API

Senden Sie eine HTTP-POST-Anfrage, um die Vorlage mithilfe der REST API auszuführen. Weitere Informationen zur API und ihren Autorisierungsbereichen finden Sie unter 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" }
  }
}

Ersetzen Sie Folgendes:

  • PROJECT_ID: Die Google Cloud Projekt-ID, in der Sie den Dataflow-Job ausführen möchten
  • JOB_NAME: Ein eindeutiger Jobname Ihrer Wahl
  • VERSION: Die Version der Vorlage, die Sie verwenden möchten

    Sie können die folgenden Werte verwenden:

    • latest zur Verwendung der neuesten Version der Vorlage, die im nicht datierten übergeordneten Ordner im Bucket verfügbar ist: gs://dataflow-templates/latest/.
    • Den Versionsnamen wie 2023-09-12-00_RC00, um eine bestimmte Version der Vorlage zu verwenden. Diese ist verschachtelt im jeweiligen datierten übergeordneten Ordner im Bucket enthalten: gs://dataflow-templates/.
  • LOCATION: die Region, in der Sie Ihren Dataflow-Job bereitstellen möchten, z. B. us-central1
  • SOURCE_CONFIG_URL: URL zum Herstellen einer Verbindung zum Quelldatenbankhost. Es kann Folgendes sein: 1. Die JDBC-Verbindungs-URL, die den Host, den Port und den Namen der Quelldatenbank enthalten muss und optional Attribute wie „autoReconnect“ und „maxReconnects“ enthalten kann. Format: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Der Pfad zur Shard-Konfiguration
  • INSTANCE_ID: Die Cloud Spanner-Instanz-ID.
  • DATABASE_ID: die Cloud Spanner-Datenbank-ID
  • PROJECT_ID: die Cloud Spanner-Projekt-ID.
  • OUTPUT_DIRECTORY: das Ausgabeverzeichnis für fehlgeschlagene/übersprungene/gefilterte Ereignisse