BigQuery-Migrations-Toolkit für Datastream

Auf dieser Seite werden Best Practices für die Migration von Datastream zur Vorlage „Dataflow Datastream zu BigQuery“ zur integrierten BigQuery-Replikationslösung für Datastream beschrieben.

Hinweise

Bei den Anweisungen auf dieser Seite wird Folgendes vorausgesetzt:

Sie sind mit Docker vertraut und haben diese App installiert.
Sie wissen, wie Sie Repositories von Diensten wie GitHub klonen.
Sie wissen, wie Sie Streams in Datastream ausführen.
Sie haben die Google Cloud CLI installiert.

Übersicht über das Migrations-Toolkit

Das BigQuery Migration Toolkit von Datastream ist eine Open-Source-Software von Google Cloud. Mit dem Toolkit können Sie aus der Dataflow-Vorlage Datastream zu BigQuery migrieren. Sie können das Tool aber auch für die Migration von anderen Pipelines verwenden. Eine Erläuterung hierzu finden Sie im folgenden Abschnitt Von anderen Pipelines migrieren.

Führen Sie die folgenden Schritte aus, um Ihre BigQuery-Tabellen mit dem Toolkit zu migrieren:

Datastream-Stream mit einem BigQuery-Ziel erstellen, starten und pausieren.
Führen Sie die Migration für jede BigQuery-Tabelle aus, die migriert werden soll.
Setze den Stream fort.

Das Toolkit bietet folgende Aufgaben:

Das Quelltabellenschema wird mit der Datastream Discover API abgerufen.
Erstellt anhand des abgerufenen Schemas eine Datastream-kompatible BigQuery-Tabelle.
Ruft das Schema der BigQuery-Tabelle ab, aus der Sie migrieren, um die erforderlichen Datentypkonvertierungen zu bestimmen.
Kopiert alle vorhandenen Zeilen aus der ursprünglichen Tabelle in die neue Tabelle, einschließlich des entsprechenden Spaltentyps casts.

Weitere Informationen zur Strukturierung des Toolkits und zu den verwendeten Argumenten finden Sie in der README.md-Toolkit-Datei.

Migrations-Toolkit einrichten

Führen Sie die folgenden Schritte aus, um das Migrations-Toolkit mit Docker auszuführen:

Klonen Sie das Repository und wechseln Sie in das Verzeichnis:

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

Erstellen Sie das Image:
```
docker build -t migration-service .
```

Authentifizieren Sie sich mit Ihren Anmeldedaten für die Google Cloud CLI:

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

Legen Sie die Property Ihres Google Cloud-Projekts fest:
```
docker run -ti --volumes-from gcloud-config migration-service \
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch die ID Ihres Google Cloud-Projekts.

Von Dataflow zur integrierten Datastream-Lösung migrieren

Datastream-Stream mit einem BigQuery-Ziel erstellen

Hinweis: Wählen Sie beim Konfigurieren der Quelle unter Backfill-Modus für Verlaufsdaten auswählen die Option Manueller Backfill aus.
Starte den Stream und pausiere ihn sofort. Dadurch kann Datastream die Position erfassen, von der aus Änderungen erfasst werden, bevor die Migration beginnt.

Hinweis: Zwischen dem Starten und dem Pausieren verarbeitet Datastream möglicherweise einige Ereignisse und erstellt eine oder mehrere Tabellen in BigQuery. In einem solchen Fall müssen Sie die Tabellen in BigQuery manuell löschen, bevor Sie mit der Migration fortfahren. Andernfalls schlägt die Migration fehl.
Leeren Sie die Datastream- und Dataflow-Pipeline:
1. Pausieren Sie den vorhandenen Cloud Storage-Zielstream.
2. Prüfen Sie den Messwert für die Gesamtlatenz für den Stream und warten Sie mindestens so lange wie die aktuelle Latenzzeit, damit alle laufenden Ereignisse in das Ziel geschrieben werden.
3. Leeren Sie den Dataflow-Job.

Migration ausführen

Führen Sie die Migration im dry_run-Modus aus. Im Modus dry_run können Sie die DDL-Anweisung CREATE TABLE und die SQL-Anweisung zum Kopieren von Daten generieren, ohne sie auszuführen:
```
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
```
Ersetzen Sie Folgendes:
- PROJECT_ID: Die eindeutige Kennung Ihres Google Cloud-Projekts.
- STREAM_ID: Die eindeutige Kennung Ihres BigQuery-Zielstreams.
- STREAM_REGION: Der Speicherort Ihres Streams, z. B. us-central1.
- SOURCE_SCHEMA_NAME: Der Name des Quellschemas.
- SOURCE_TABLE_NAME ist der Name der Quelltabelle.
- BIGQUERY_SOURCE_DATASET_NAME: Der Name des vorhandenen BigQuery-Datasets.
- BIGQUERY_SOURCE_TABLE_NAME: Der Name der vorhandenen BigQuery-Tabelle.

Prüfen Sie die .sql-Dateien unter output/create_target_table und output/copy_rows. Dies sind die SQL-Befehle, die in Ihrem Google Cloud-Projekt ausgeführt werden:

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 {} \;

Führen Sie die Migration im full-Modus aus, um die SQL-Befehle auszuführen. Mit dem Modus full können Sie eine Tabelle in BigQuery erstellen und alle Zeilen aus der vorhandenen BigQuery-Tabelle kopieren:

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

Setzen Sie den pausierten Stream fort.
Öffnen Sie den Google Cloud-Log-Explorer und suchen Sie mit der folgenden Abfrage nach Datastream-Logs:
```
resource.type="datastream.googleapis.com/Stream"
resource.labels.stream_id=STREAM_ID
```
Suchen Sie nach dem folgenden Log, wobei %d eine Zahl ist:
```
Completed writing %d records into..
```
Dieses Log gibt an, dass der neue Stream Daten erfolgreich in BigQuery geladen hat. Es wird nur angezeigt, wenn CDC-Daten zum Laden vorhanden sind.

Von anderen Pipelines migrieren

Mit dem Toolkit können Sie auch von anderen Pipelines zur integrierten BigQuery-Lösung von Datastream migrieren. Das Toolkit kann auf Basis des Quelldatenbankschemas CREATE TABLE-DDLs für Datastream-kompatible BigQuery-Tabellen generieren. Dazu wird der Modus dry_run verwendet:

  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

Da die BigQuery-Tabellenschemas variieren können, ist es schwierig, eine universelle SQL-Anweisung zum Kopieren von Zeilen bereitzustellen. Sie können die Schemas im DDL-Verzeichnis der Quelltabelle (output/source_table_ddl) und im DDL-Verzeichnis der Zieltabelle (output/create_target_table) verwenden, um eine SQL-Anweisung mit entsprechenden Casts für die Quellspalten zu erstellen.

Hier sehen Sie ein Beispiel für ein SQL-Anweisungsformat:

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

Ersetzen Sie Folgendes:

DESTINATION_TABLE: Der Name Ihrer Zieltabelle in BigQuery.
DESTINATION_COLUMN: Der Name der Spalte in der Zieltabelle.
SOURCE_COLUMN: Der Name der Spalte in der Quelltabelle.
SOURCE_TABLE: Der Name Ihrer Quelltabelle.

Beschränkungen

Das Toolkit hat folgende Einschränkungen:

Die Spaltennamen in den vorhandenen und neuen BigQuery-Tabellen müssen übereinstimmen. Metadatenspalten werden ignoriert. Die Migration schlägt fehl, wenn Sie benutzerdefinierte Dataflow-Funktionen (User-Defined Functions, UDFs) anwenden, die die Namen der Spalten in den vorhandenen Tabellen ändern, z. B. durch Hinzufügen eines Präfixes oder Ändern der Groß- und Kleinschreibung.
Regionen- und projektübergreifende Migrationen werden nicht unterstützt.
Die Migration erfolgt pro Tabelle.
Es werden nur Oracle- und MySQL-Quellen unterstützt.