Fallback auf MySQL konfigurieren

In diesem Dokument wird beschrieben, wie Sie mit der Rückwärtsreplikation den Fallback für MySQL konfigurieren. Fallback bezieht sich auf einen Notfallplan, mit dem Sie zu Ihrer MySQL-Quelldatenbank zurückkehren können, wenn Probleme mit Spanner auftreten.

Die Rückwärtsreplikation ist nützlich, wenn unerwartete Probleme auftreten und Sie mit minimalen Unterbrechungen des Dienstes zur ursprünglichen MySQL-Datenbank zurückkehren müssen. Mit der Rückwärtsreplikation können Sie ein Fallback durchführen, indem Sie Daten, die in Spanner geschrieben wurden, in Ihre MySQL-Quelldatenbank replizieren.

Der Ablauf der Rückwärtsreplikation umfasst die folgenden Schritte, die von der Spanner_to_SourceDb Dataflow-Vorlage ausgeführt werden:

  1. Änderungen aus Spanner mit Spanner-Änderungsstreams lesen.

  2. Datensätze mit dem Filtermodus forward_migration filtern.

  3. Spanner-Daten mit dem Spanner-Migrationstool so transformieren, dass sie mit dem Schema Ihrer Quelldatenbank kompatibel sind. Weitere Informationen finden Sie unter Benutzerdefinierte Transformation.

  4. Prüfen, ob die MySQL-Quelldatenbank bereits neuere Daten für den angegebenen Primärschlüssel enthält. Wenn bereits neuere Daten vorhanden sind, überspringt die Pipeline das Änderungsereignis, um neuere Daten nicht zu überschreiben.

  5. Daten in Ihre Quelldatenbank schreiben.

Dataflow-Vorlage Spanner_to_SourceDb verwenden

Die Dataflow-Vorlage trägt dazu bei, die Konsistenz auf Primärschlüsselebene sicherzustellen. Die Vorlage erstellt in Spanner Metadatentabellen, sogenannte Schattentabellen, die den Commit-Zeitstempel der letzten Schreib transaktion für den Shard für diese bestimmte Tabelle enthalten.

Die Schreibvorgänge sind bis zum Commit-Zeitstempel des Primärschlüssels konsistent.

Die Rückwärtsreplikation wird als kontinuierlicher Streaming-Dataflow-Job ausgeführt. Der Job liest Änderungsereignisse aus Spanner-Änderungsstreams, konvertiert sie in Datentypen, die mit dem Schema der Quelldatenbank kompatibel sind, und schreibt sie in Ihre MySQL-Datenbank. Wenn bei einem Ereignis ein vorübergehender Fehler auftritt, wird es vom Job automatisch über ein retry/-Verzeichnis für die Warteschlange für unzustellbare Nachrichten (Dead-Letter Queue, DLQ) in Cloud Storage wiederholt. Wenn bei einem Ereignis ein permanenter Fehler auftritt oder die Anzahl der Wiederholungsversuche überschritten wird, leitet der Job es zur manuellen Behebung an ein severe/-DLQ-Verzeichnis weiter. Weitere Informationen zum Beheben und Wiedergeben fehlgeschlagener Datensätze, siehe Fehler bei der Rückwärtsreplikation im Blick behalten und beheben.

Hinweis

  • Prüfen Sie die Netzwerkverbindung zwischen Ihrer MySQL-Quelldatenbank und Ihrem Google Cloud Projekt, in dem Ihre Dataflow-Jobs ausgeführt werden.

  • Fügen Sie die IP-Adressen der Dataflow-Worker in der Zulassungsliste Ihrer MySQL-Quellinstanz hinzu.

  • Prüfen Sie, ob die MySQL-Anmeldedaten in der source shards file korrekt angegeben sind.

  • Prüfen Sie, ob Ihre MySQL-Instanz online ist und ausgeführt wird.

  • Prüfen Sie, ob der MySQL-Nutzer die Berechtigungen INSERT, UPDATE und DELETE für die MySQL-Datenbank hat.

  • Prüfen Sie, ob Sie die erforderlichen IAM-Berechtigungen zum Ausführen einer flexiblen Dataflow-Vorlage haben. Weitere Informationen finden Sie unter Flexible Vorlage erstellen und ausführen.

  • Prüfen Sie, ob der Port 12345 für die Kommunikation zwischen den Dataflow-Worker-VMs geöffnet ist.

Erforderliche Rollen

  • Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Instanz zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Starten der Rückwärtsreplikation benötigen:

  • Damit das Compute Engine-Dienstkonto die erforderlichen Berechtigungen zum Starten der Rückwärtsreplikation hat, bitten Sie Ihren Administrator, dem Compute Engine-Dienstkonto die folgenden IAM-Rollen für die Instanz zu gewähren:

Rückwärtsreplikation ausführen

So führen Sie die Rückwärtsreplikation aus:

  1. Laden Sie die Sitzungsdatei in den Cloud Storage-Bucket hoch.

  2. Erstellen Sie eine Pub/Sub-Benachrichtigung für den Ordner retry des DLQ-Verzeichnisses. Dazu können Sie ein Pub/Sub Thema und ein Pub/Sub Abo für dieses Thema erstellen.

  3. Erstellen Sie die Dataflow-Vorlage und führen Sie das Staging durch. Weitere Informationen finden Sie unter Vorlage erstellen.

  4. Führen Sie den folgenden gcloud dataflow flex-template run-Befehl aus, um die Streaming-Pipeline für die Rückwärtsreplikation zu starten:

      gcloud dataflow flex-template run "spanner-to-sourcedb-job" \
  --project "PROJECT" \
  --region "REGION" \
  --template-file-gcs-location "TEMPLATE_SPEC_GCSPATH" \
  --parameters "changeStreamName=CHANGE_STREAM_NAME" \
  --parameters "instanceId=INSTANCE_ID" \
  --parameters "databaseId=DATABASE_ID" \
  --parameters "spannerProjectId=SPANNER_PROJECT_ID" \
  --parameters "metadataInstance=METADATA_INSTANCE" \
  --parameters "metadataDatabase=METADATA_DATABASE" \
  --parameters "sourceShardsFilePath=SOURCE_SHARDS_FILE_PATH" \
  # All flags after this point are optional
  [--parameters "startTimestamp=START_TIMESTAMP"] \
  [--parameters "endTimestamp=END_TIMESTAMP"] \
  [--parameters "shadowTablePrefix=SHADOW_TABLE_PREFIX"] \
  [--parameters "sessionFilePath=SESSION_FILE_PATH"] \
  [--parameters "filtrationMode=FILTRATION_MODE"] \
  [--parameters "shardingCustomJarPath=SHARDING_CUSTOM_JAR_PATH"] \
  [--parameters "shardingCustomClassName=SHARDING_CUSTOM_CLASS_NAME"] \
  [--parameters "shardingCustomParameters=SHARDING_CUSTOM_PARAMETERS"] \
  [--parameters "sourceDbTimezoneOffset=SOURCE_DB_TIMEZONE_OFFSET"] \
  [--parameters "dlqGcsPubSubSubscription=DLQ_GCS_PUB_SUB_SUBSCRIPTION"] \
  [--parameters "skipDirectoryName=SKIP_DIRECTORY_NAME"] \
  [--parameters "maxShardConnections=MAX_SHARD_CONNECTIONS"] \
  [--parameters "deadLetterQueueDirectory=DEAD_LETTER_QUEUE_DIRECTORY"] \
  [--parameters "dlqMaxRetryCount=DLQ_MAX_RETRY_COUNT"] \
  [--parameters "runMode=RUN_MODE"] \
  [--parameters "dlqRetryMinutes=DLQ_RETRY_MINUTES"] \
  [--parameters "sourceType=SOURCE_TYPE"] \
  [--parameters "transformationJarPath=TRANSFORMATION_JAR_PATH"] \
  [--parameters "transformationClassName=TRANSFORMATION_CLASS_NAME"] \
  [--parameters "transformationCustomParameters=TRANSFORMATION_CUSTOM_PARAMETERS"] \
  [--parameters "filterEventsDirectoryName=FILTER_EVENTS_DIRECTORY_NAME"]

    Die obligatorischen Variablen sind in der folgenden Liste beschrieben:

    • PROJECT: die Google Cloud Projekt-ID.
    • REGION: die Google Cloud region, in der Sie den Dataflow-Job ausführen möchten.
    • TEMPLATE_SPEC_GCSPATH: der Cloud Storage-Pfad zur bereitgestellten Dataflow-Vorlagendatei.
    • CHANGE_STREAM_NAME: der Name des Spanner-Änderungsstreams, aus dem der Job liest.
    • INSTANCE_ID: die Spanner-Instanz-ID.
    • DATABASE_ID: die Spanner-Datenbank-ID.
    • SPANNER_PROJECT_ID: die Projekt-ID, in der sich Ihre Spanner-Instanzen befinden.
    • METADATA_INSTANCE: die Spanner-Instanz, in der die Metadaten gespeichert sind, mit denen der Connector die Nutzung von API-Daten für Änderungsstreams steuert.
    • METADATA_DATABASE: die Spanner-Datenbank, in der die Metadaten gespeichert sind, mit denen der Connector die Nutzung von API-Daten für Änderungsstreams steuert.
    • SOURCE_SHARDS_FILE_PATH: der Cloud Storage-Pfad, der die Informationen zum Verbindungsprofil für die Quell-Shards enthält.

    Die optionalen Variablen sind in der folgenden Liste beschrieben:

    • START_TIMESTAMP: der Zeitstempel, ab dem Änderungen gelesen werden sollen. Die Standardeinstellung ist leer.
    • END_TIMESTAMP: der Zeitstempel, bis zu dem Änderungen gelesen werden sollen. Wenn nicht angegeben, werden Änderungen unbegrenzt gelesen. Die Standardeinstellung ist leer.
    • SHADOW_TABLE_PREFIX: das Präfix für die Benennung von Schattentabellen. Standardeinstellung: shadow_.
    • SESSION_FILE_PATH: der Pfad zur Sitzungsdatei in Cloud Storage, die Zuordnungsinformationen aus dem Spanner-Migrationstool enthält.
    • FILTRATION_MODE: der Modus, der bestimmt, wie Datensätze anhand von Kriterien gefiltert werden. Unterstützte Modi sind none und forward_migration.
    • SHARDING_CUSTOM_JAR_PATH: der Speicherort (Pfad) in Cloud Storage der benutzerdefinierten JAR-Datei, die die Logik zum Abrufen der Shard-ID enthält. Die Standardeinstellung ist leer.
    • SHARDING_CUSTOM_CLASS_NAME: der vollständig qualifizierte Klassenname mit der benutzerdefinierten Shard-ID-Implementierung. Dieser Parameter ist erforderlich, wenn SHARDING_CUSTOM_JAR_PATH angegeben ist. Die Standardeinstellung ist leer.
    • SHARDING_CUSTOM_PARAMETERS: ein String mit allen benutzerdefinierten Parametern, die an die benutzerdefinierte Sharding-Klasse übergeben werden sollen. Die Standardeinstellung ist leer.
    • SOURCE_DB_TIMEZONE_OFFSET: der Zeitzonenversatz von UTC für die Quelldatenbank. Beispiel: +10:00. Standardeinstellung: +00:00.
    • DLQ_GCS_PUB_SUB_SUBSCRIPTION: das Pub/Sub-Abo, das in einer Cloud Storage-Benachrichtigungsrichtlinie für das DLQ-Wiederholverzeichnis verwendet wird, wenn der Modus regular genutzt wird. Geben Sie den Namen im Format projects/<PROJECT_ID>/subscriptions/<SUBSCRIPTION_ID> an. Wenn Sie diesen Parameter festlegen, werden deadLetterQueueDirectory und dlqRetryMinutes vom System ignoriert.
    • SKIP_DIRECTORY_NAME: das Verzeichnis, in das das System Datensätze schreibt, die bei der Rückwärtsreplikation übersprungen werden. Standardeinstellung: skip.
    • MAX_SHARD_CONNECTIONS: die maximale Anzahl der Verbindungen, die pro Shard zulässig sind. Standardeinstellung: 10000.
    • DEAD_LETTER_QUEUE_DIRECTORY: der Pfad zum Speichern der DLQ-Ausgabe. Der Standardwert ist ein Verzeichnis unter dem temporären Speicherort des Dataflow-Jobs.
    • DLQ_MAX_RETRY_COUNT: die maximale Anzahl der Wiederholungsversuche des Systems bei vorübergehenden Fehlern über die DLQ. Standardeinstellung: 500.
    • RUN_MODE: der Typ des Ausführungsmodus. Unterstützte Optionen sind regular, retryDLQ und retryAllDLQ. Verwenden Sie retryDLQ, um Fehlerdatensätze aus dem Verzeichnis severe/ zusammen mit einer aktiven Pipeline noch einmal zu versuchen, oder retryAllDLQ, um sowohl die Verzeichnisse retry/ als auch severe/ zu verarbeiten, wenn die reguläre Pipeline beendet ist. Standardeinstellung: regular.
    • DLQ_RETRY_MINUTES: die Anzahl der Minuten zwischen DLQ-Wiederholungsversuchen. Standardeinstellung: 10.
    • SOURCE_TYPE: der Typ der Quelldatenbank, in die die Rückwärtsreplikation erfolgen soll. Standardeinstellung: mysql.
    • TRANSFORMATION_JAR_PATH: der Speicherort (Pfad) in Cloud Storage der benutzerdefinierten JAR-Datei, die die benutzerdefinierte Transformationslogik für die Verarbeitung von Datensätzen bei der Rückwärtsreplikation enthält. Die Standardeinstellung ist leer.
    • TRANSFORMATION_CLASS_NAME: der vollständig qualifizierte Klassenname mit der benutzerdefinierten Transformationslogik. Dieser Parameter ist erforderlich, wenn TRANSFORMATION_JAR_PATH angegeben ist. Die Standardeinstellung ist leer.
    • TRANSFORMATION_CUSTOM_PARAMETERS: ein String mit allen benutzerdefinierten Parametern, die an die benutzerdefinierte Transformationsklasse übergeben werden sollen. Die Standardeinstellung ist leer.
    • FILTER_EVENTS_DIRECTORY_NAME: das Verzeichnis in Cloud Storage, in das das System Datensätze schreibt, die durch die benutzerdefinierte Rückwärtstransformationslogik herausgefiltert werden. Standardeinstellung: filteredEvents.

Fehler bei der Rückwärtsreplikation im Blick behalten und beheben

Wenn Sie die Rückwärtsreplikation von Spanner zurück zu MySQL ausführen und Ihr Streaming-Dataflow-Job ein Änderungsereignis nicht in Ihre primäre MySQL-Datenbank schreiben kann, klassifiziert er den Fehler in eine von zwei Kategorien und schreibt den Datensatz in ein DLQ-Verzeichnis in Ihrem Cloud Storage-Bucket:

  • Wiederholbare Fehler: Vorübergehende Fehler wie MySQL-Datenbank-Lock s oder Zeitüberschreitungen bei der Netzwerkverbindung. Dataflow schreibt diese Ereignisse in ein retry/-DLQ-Verzeichnis und wiederholt sie automatisch in derselben Pipeline, bis sie erfolgreich sind oder dlqMaxRetryCount überschritten wird.
  • Schwerwiegende Fehler: Permanente Fehler, die nicht durch automatische Wiederholungsversuche behoben werden können, z. B. Fehler bei der Datentypkonvertierung, Syntaxfehler oder Ausnahmen in benutzerdefinierten Transformations-JAR-Dateien. Dataflow schreibt diese Ereignisse in ein severe/-DLQ-Verzeichnis (z. B. gs://MIGRATION_BUCKET/ENV/SERVICE/reverse/DB_SCHEMA/severe/) und erhöht den benutzerdefinierten Zähler severe_error_count.

Da schwerwiegende Fehler nicht durch automatische Wiederholungsversuche behoben werden können, entfernt Dataflow diese fehlgeschlagenen Ereignisse aus dem aktiven Replikationsstream und speichert sie im Verzeichnis severe/. Wenn sie nicht behoben werden, fehlen diese Datensätze in Ihrer MySQL-Datenbank für das Rollback. Behalten Sie den Zähler severe_error_count und das Verzeichnis severe/ während der Rückwärtsreplikation regelmäßig im Blick, damit Sie fehlgeschlagene Änderungsereignisse beheben und wiedergeben können, bevor Sie ein Rollback initiieren.

Der benutzerdefinierte Dataflow-Zähler severe_error_count ist eine kumulative Messung, die die Gesamtzahl der schwerwiegenden Fehler erfasst, die seit dem Start des Streaming-Jobs aufgetreten sind. Wenn Sie fehlgeschlagene Datensätze mit einem DLQ-Wiederholungsjob wiedergeben und beheben, wird dieser Zähler in Ihrer ursprünglichen Streaming-Pipeline nicht verringert. Daher ist Ihr schwerwiegendes DLQ-Verzeichnis in Cloud Storage (gs://MIGRATION_BUCKET/ENV/SERVICE/reverse/DB_SCHEMA/severe/) die maßgebliche Quelle für die Wahrheit, ob unbehandelte Fehler vorhanden sind.

Fehlgeschlagene Datensätze wiedergeben

Wenn fehlgeschlagene Datensätze in Ihrem schwerwiegenden DLQ-Verzeichnis angezeigt werden, prüfen Sie die JSON-Fehlerdateien in Cloud Storage, ermitteln Sie die Ursache und beheben Sie das zugrunde liegende Problem.

Wenn Sie korrigierte DLQ-Datensätze in MySQL wiedergeben möchten, starten Sie einen neuen Dataflow-Job mit einem der folgenden Ausführungsmodi:

  • Modus retryDLQ: Führen Sie diesen Modus als Batchjob zusammen mit Ihrer aktiven Streaming-Pipeline aus, um Fehlerdateien im Verzeichnis severe/ zu verarbeiten, ohne die Live-Rückwärtsreplikation zu unterbrechen. Führen Sie diesen Modus aus, nachdem Sie die Ursachen der schwerwiegenden Fehler behoben haben.
  • Modus retryAllDLQ: Wenn Ihre reguläre Streaming-Pipeline beendet ist, verwenden Sie diesen Modus, um sowohl die Verzeichnisse retry/ als auch severe/ zu verarbeiten. Führen Sie retryAllDLQ nicht gleichzeitig mit einer aktiven Pipeline aus, da dies zu Dateikonflikten und Verarbeitungskonflikten führt.

Führen Sie den folgenden Befehl aus, um einen DLQ-Wiederholungsjob für die Rückwärtsreplikation mit der gcloud CLI zu starten:

gcloud dataflow flex-template run "spanner-to-sourcedb-retry-job" \
    --project "PROJECT" \
    --region "REGION" \
    --template-file-gcs-location "TEMPLATE_SPEC_GCSPATH" \
    --parameters "changeStreamName=CHANGE_STREAM_NAME" \
    --parameters "instanceId=INSTANCE_ID" \
    --parameters "databaseId=DATABASE_ID" \
    --parameters "spannerProjectId=SPANNER_PROJECT_ID" \
    --parameters "metadataInstance=METADATA_INSTANCE" \
    --parameters "metadataDatabase=METADATA_DATABASE" \
    --parameters "sourceShardsFilePath=SOURCE_SHARDS_FILE_PATH" \
    --parameters "deadLetterQueueDirectory=DLQ_DIRECTORY" \
    --parameters "runMode=retryDLQ"

Ersetzen Sie Folgendes:

  • PROJECT: die Google Cloud Projekt-ID.
  • REGION: die Google Cloud region, in der Sie den Dataflow-Job ausführen möchten.
  • TEMPLATE_SPEC_GCSPATH: der Cloud Storage-Pfad zur bereitgestellten Dataflow-Vorlagendatei.
  • CHANGE_STREAM_NAME: der Name des Spanner-Änderungsstreams, aus dem der Job liest.
  • INSTANCE_ID: die Spanner-Instanz-ID.
  • DATABASE_ID: die Spanner-Datenbank-ID.
  • SPANNER_PROJECT_ID: die Projekt-ID, in der sich Ihre Spanner-Instanzen befinden.
  • METADATA_INSTANCE: die Spanner-Instanz, in der die Metadaten gespeichert sind, mit denen der Connector die Nutzung von API-Daten für Änderungsstreams steuert.
  • METADATA_DATABASE: die Spanner-Datenbank, in der die Metadaten gespeichert sind, mit denen der Connector die Nutzung von API-Daten für Änderungsstreams steuert.
  • SOURCE_SHARDS_FILE_PATH: der Cloud Storage-Pfad, der die Informationen zum Verbindungsprofil für die Quell-Shards enthält.
  • DLQ_DIRECTORY: der Cloud Storage-Pfad zum DLQ-Verzeichnis, das die schwerwiegenden Fehlerdateien enthält, die noch einmal versucht werden sollen.

Nächste Schritte