Datenbanken von Spanner nach Avro exportieren

Auf dieser Seite wird beschrieben, wie Sie Spanner-Datenbanken mit der Google Cloud Console exportieren.

Führen Sie die Schritte im Abschnitt Vorbereitung auf dieser Seite aus, um eine Spanner-Datenbank mit der REST API oder der Google Cloud CLI zu exportieren. Eine detaillierte Anleitung finden Sie in der Dataflow-Dokumentation unter Spanner für Cloud Storage Avro. Beim Export werden die Daten mit Dataflow in einen Ordner in einem Cloud Storage Bucket geschrieben. Dieser Ordner enthält eine Reihe von Avro-Dateien und JSON-Manifestdateien.

Vorbereitung

Zum Exportieren einer Spanner-Datenbank müssen Sie zuerst die APIs für Spanner, Cloud Storage, Compute Engine und Dataflow aktivieren:

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.

APIs aktivieren

Außerdem brauchen Sie ein ausreichend großes Kontingent und die erforderlichen IAM-Berechtigungen.

Kontingentanforderungen

Die Kontingentanforderungen für Exportjobs sind wie folgt:

  • Spanner: Für den Export einer Datenbank ist keine zusätzliche Rechenkapazität erforderlich. Allerdings benötigen Sie möglicherweise weitere Rechenkapazität, damit der Job in angemessener Zeit abgeschlossen werden kann. Weitere Informationen finden Sie unter Jobs optimieren.
  • Cloud Storage: Zum Exportieren müssen Sie einen Bucket für die exportierten Dateien erstellen, sofern noch keiner vorhanden ist. Das können Sie in der Google Cloud Console erledigen – entweder auf der Cloud Storage-Seite oder beim Erstellen des Exports auf der Spanner-Seite. Für den Bucket muss keine Größe festgelegt werden.
  • Dataflow: Bei Exportjobs gelten die gleichen Compute Engine-Kontingente für CPU, Laufwerksauslastung und IP-Adressen wie bei anderen Dataflow-Jobs.
  • Compute Engine: Bevor Sie den Exportjob ausführen, müssen Sie zuerst Kontingente für Compute Engine einrichten, die von Dataflow verwendet werden. Diese Kontingente stellen die maximale Anzahl an Ressourcen dar, die Dataflow für Ihren Job verwenden darf. Empfohlene Anfangswerte sind:

    • CPUs: 200
    • Verwendete IP-Adressen: 200
    • Nichtflüchtiger Standardspeicher: 50 TB

    Im Allgemeinen sind keine weiteren Anpassungen erforderlich. Dataflow bietet Autoscaling, sodass Sie nur für die Ressourcen zahlen, die beim Export tatsächlich verwendet werden. Wenn Ihr Job mehr Ressourcen verwenden kann, wird in der Dataflow-UI ein Warnsymbol angezeigt. Der Job sollte trotz dieses Warnsymbols beendet werden.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Dataflow-Worker-Dienstkonto zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Exportieren einer Datenbank benötigen:

Wenn Sie die unabhängigen Rechenressourcen von Spanner Data Boost während eines Exports verwenden möchten, benötigen Sie auch die IAM-Berechtigung spanner.databases.useDataBoost. Weitere Informationen finden Sie unter Data Boost-Übersicht.

Datenbank exportieren

Wenn Sie die oben beschriebenen Kontingent- und IAM-Anforderungen erfüllen, können Sie eine vorhandene Spanner-Datenbank exportieren.

Führen Sie die folgenden Schritte aus, um die Spanner-Datenbank in einen Cloud Storage-Bucket zu exportieren:

  1. Rufen Sie die Spanner-Seite Instanzen auf.

    Zur Seite „VM-Instanzen“

  2. Klicken Sie auf den Namen der Instanz, die die Datenbank enthält.

  3. Klicken Sie im linken Bereich auf den Menüpunkt Import/Export und anschließend auf den Button Export.

  4. Klicken Sie unter Speicherort für den Export auswählen auf Durchsuchen.

  5. Wenn Sie noch keinen Cloud Storage-Bucket für den Export haben:

    1. Klicken Sie auf Neuer Bucket Screenshot des UI-Elements für einen neuen Bucket.
    2. Geben Sie einen Namen für den Bucket ein. Bucket-Namen in Cloud Storage dürfen nur einmal vorkommen.
    3. Wählen Sie eine Standardspeicherklasse und einen Speicherort aus und klicken Sie auf Erstellen.
    4. Klicken Sie auf den Bucket, um ihn auszuwählen.

    Wenn bereits ein Bucket vorhanden ist, wählen Sie ihn entweder aus der angezeigten Liste aus oder klicken Sie auf Suchen Screenshot des UI-Elements zum Suchen, damit Sie die Liste filtern können. Klicken Sie dann auf den entsprechenden Bucket, um ihn auszuwählen.

  6. Klicken Sie auf Auswählen.

  7. Wählen Sie im Drop-down-Menü Datenbank für den Export auswählen die zu exportierende Datenbank aus.

  8. Optional: Klicken Sie das Kästchen an, um die Datenbank von einem früheren Zeitpunkt zu exportieren, und geben Sie einen Zeitstempel ein.

  9. Wählen Sie im Drop-down-Menü Region für den Exportjob auswählen eine Region aus.

  10. Optional: So verschlüsseln Sie den Dataflow-Pipelinestatus mit einem kundenverwalteten Verschlüsselungsschlüssel:

    1. Klicken Sie auf Verschlüsselungsoptionen anzeigen.
    2. Wählen Sie Vom Kunden verwalteten Verschlüsselungsschlüssel (CMEK) verwenden aus.
    3. Wählen Sie Ihren Schlüssel aus der Drop-down-Liste aus.

    Diese Option wirkt sich nicht auf die Verschlüsselung auf Cloud Storage-Bucket-Zielebene aus. Informationen zum Aktivieren von CMEK für den Cloud Storage-Bucket finden Sie unter CMEK mit Cloud Storage verwenden.

  11. Optional: Wählen Sie das Kästchen Spanner Data Boost verwenden aus, um den Export mit Spanner Data Boost durchzuführen. Weitere Informationen finden Sie unter Data Boost-Übersicht.

  12. Klicken Sie auf das Kästchen unter Gebühren bestätigen , um zu bestätigen, dass zusätzlich zu den Kosten für die vorhandene Spanner-Instanz weitere Gebühren anfallen.

  13. Klicken Sie auf Exportieren.

    In der Google Cloud Console sehen Sie jetzt die Seite Datenbankimport/-export , in der jetzt eine Position für Ihren Exportjob in der Liste der Import-/Exportjobs angezeigt wird, einschließlich der verstrichenen Zeit:

    Screenshot eines laufenden Jobs

Wenn der Job beendet oder abgebrochen wird, wird der Status in der Import-/Exportliste aktualisiert. Wenn der Job erfolgreich ausgeführt wurde, wird der Status Succeeded (Erfolgreich) angezeigt:

Erfolgsmeldung für Exportjob

Wenn der Job fehlgeschlagen ist, wird der Status Fehlgeschlagen angezeigt:

Fehlermeldung für Exportjob

Klicken Sie auf den Namen des Jobs in der Spalte Dataflow-Jobname, um die Details des Dataflow-Vorgangs für Ihren Job aufzurufen.

Falls der Job fehlschlägt, sehen Sie sich die Fehlerdetails in den Dataflow-Logs des Jobs an.

Löschen Sie den Ordner und die Dateien, die durch den fehlgeschlagenen Exportjob erstellt wurden, um Cloud Storage-Gebühren für diese Dateien zu vermeiden. Informationen zum Suchen des Ordners finden Sie unter View your export.

Hinweis zum Exportieren generierter Spalten und Änderungsstreams

Die Werte in einer gespeicherten generierten Spalte werden nicht exportiert. Die Spaltendefinition wird als Eintragsfeld vom Typ Null als Teil des Avro-Schemas exportiert, wobei die Spaltendefinition als benutzerdefinierte Attribute des Felds angegeben wird. Bis zum Abschluss des Backfill-Vorgangs für eine neu hinzugefügte Spalte wird die generierte Spalte ignoriert, als wäre sie im Schema nicht vorhanden.

Als Avro-Dateien exportierte Änderungsstreams enthalten nur das Schema der Änderungsstreams und keine Datensatzänderungen.

Hinweis zum Exportieren von Sequenzen

Sequenzen (GoogleSQL, PostgreSQL) sind Schemaobjekte, mit denen Sie eindeutige Ganzzahlwerte generieren können. Spanner exportiert jedes Schemaobjekt als Eintragsfeld in das Avro-Schema, wobei die Sequenzart, der übersprungene Bereich und der Zähler als Attribute des Felds angegeben werden. Damit eine Sequenz nach dem Import nicht zurückgesetzt wird und keine doppelten Werte generiert werden, erfasst die GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) Funktion beim Schemaexport den Sequenzzähler. Spanner fügt dem Zähler einen Puffer von 1.000 hinzu und schreibt den neuen Zählerwert in das Eintragsfeld. So werden Fehler durch doppelte Werte vermieden, die nach dem Import auftreten können. Wenn während des Datenexports weitere Schreibvorgänge in der Quelldatenbank ausgeführt werden, sollten Sie den tatsächlichen Sequenzzähler mit der Anweisung ALTER SEQUENCE (GoogleSQL, PostgreSQL) anpassen.

Beim Import beginnt die Sequenz mit diesem neuen Zähler anstelle des im Schema gefundenen Zählers. Alternativ können Sie die ALTER SEQUENCE (GoogleSQL, PostgreSQL) Anweisung verwenden, um die Sequenz mit einem neuen Zähler zu aktualisieren.

Export in Cloud Storage ansehen

Wechseln Sie zum Cloud Storage-Browser und wählen Sie den Bucket aus, den Sie zuvor ausgewählt haben, um in der Google Cloud Console den Ordner anzusehen, der die exportierte Datenbank enthält:

Zum Stroage-Browser

Der Bucket enthält jetzt einen Ordner mit der exportierten Datenbank. Der Ordnername beginnt mit der ID Ihrer Instanz, dem Datenbanknamen und dem Zeitstempel des Exportjobs. Der Ordner enthält:

  • Eine spanner-export.json-Datei
  • Eine TableName-manifest.json-Datei für jede Tabelle in der Datenbank, die Sie exportiert haben.
  • Mindestens eine TableName.avro-#####-of-#####-Datei. Die erste Zahl in der Erweiterung .avro-#####-of-##### steht für den Index der Avro-Datei, beginnend bei null, und die zweite Zahl steht für die Anzahl der Avro-Dateien, die für jede Tabelle generiert werden.

    Songs.avro-00001-of-00002 ist beispielsweise die zweite von zwei Dateien, die die Daten der Tabelle Songs enthalten.

  • Eine ChangeStreamName-manifest.json-Datei für jeden Änderungsstream in der Datenbank, die Sie exportiert haben.

  • Eine ChangeStreamName.avro-00000-of-00001 Datei für jeden Änderungsstream. Diese Datei enthält leere Daten mit nur dem Avro-Schema des Änderungsstreams.

Region für Importjob auswählen

Welche Region Sie auswählen, hängt vom Speicherort Ihres Cloud Storage-Bucket ab. Wählen Sie eine Region aus, die mit dem Speicherort Ihres Cloud Storage-Bucket übereinstimmt, um Gebühren für die ausgehende Datenübertragung zu vermeiden.

  • Wenn der Speicherort Ihres Cloud Storage-Bucket eine Region ist, können Sie die kostenlose Netzwerknutzung nutzen, indem Sie dieselbe Region für den Importjob auswählen, sofern diese Region verfügbar ist.

  • Wenn der Speicherort Ihres Cloud Storage-Bucket eine Dual-Region, ist, können Sie die kostenlose Netzwerknutzung nutzen, indem Sie eine der beiden Regionen auswählen, aus denen die Dual-Region besteht, sofern eine der Regionen für Ihren Importjob verfügbar ist.

  • Wenn für den Importjob keine Region mit gemeinsamem Standort verfügbar ist oder der Speicherort Ihres Cloud Storage-Bucket eine Multi-Region ist, fallen Gebühren für die ausgehende Datenübertragung an. Wählen Sie anhand der Cloud Storage Preisliste für die Datenübertragung eine Region aus, in der die Gebühren für die Datenübertragung möglichst gering sind.

Teilmenge von Tabellen exportieren

Wenn Sie nur die Daten aus bestimmten Tabellen und nicht die gesamte Datenbank exportieren möchten, können Sie diese Tabellen beim Export angeben. In diesem Fall exportiert Spanner das gesamte Schema der Datenbank, einschließlich der Daten der von Ihnen angegebenen Tabellen. Alle anderen Tabellen sind in der exportierten Datei vorhanden, aber leer.

Sie können eine Teilmenge von Tabellen exportieren, indem Sie entweder die Dataflow-Seite in der Google Cloud Console oder die gcloud CLI verwenden. Auf der Spanner-Seite ist diese Aktion nicht verfügbar.

Wenn Sie die Daten einer Tabelle exportieren, die untergeordnet zu einer anderen Tabelle ist, sollten Sie auch die Daten der übergeordneten Tabelle exportieren. Wenn übergeordnete Tabellen nicht exportiert werden, schlägt der Exportjob fehl.

Wenn Sie eine Teilmenge von Tabellen exportieren möchten, starten Sie den Export mit der Dataflow-Vorlage Spanner für Cloud Storage Avro und geben Sie die Tabellen entweder über die Dataflow-Seite in der Google Cloud Console oder mit der gcloud CLI an, wie beschrieben:

Console

Wenn Sie die Dataflow-Seite in Google Cloud der Console verwenden, befindet sich der Cloud Spanner-Tabellennamen Parameter im Abschnitt Optionale Parameter auf der Seite Job aus Vorlage erstellen. Mehrere Tabellen können in einem kommagetrennten Format angegeben werden.

Zu Dataflow

gcloud

Führen Sie den gcloud dataflow jobs run Befehl aus und geben Sie das tableNames Argument an. Beispiel:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Wenn Sie in gcloud mehrere Tabellen angeben, müssen Sie Argumente vom Typ „Dictionary“ maskieren. Im folgenden Beispiel wird „|“ als Maskierungszeichen verwendet:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Der shouldExportRelatedTables Parameter ist eine praktische Option, um automatisch alle übergeordneten Tabellen der ausgewählten Tabellen zu exportieren. In dieser Schemahierarchie mit den Tabellen Singers, Albums und Songs müssen Sie beispielsweise nur Songs angeben. Mit der Option shouldExportRelatedTables werden auch Singers und Albums exportiert, da Songs von beiden abstammt.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Jobs in der Dataflow-UI ansehen und Probleme beheben

Nachdem Sie einen Exportjob gestartet haben, können Sie in der Console im Abschnitt „Dataflow“ Details zum Job einschließlich der Logs ansehen. Google Cloud

Dataflow-Jobdetails ansehen

So rufen Sie Details zu allen Import- oder Exportjobs auf, die Sie in der letzten Woche ausgeführt haben, einschließlich aller derzeit ausgeführten Jobs:

  1. Wechseln Sie zur Seite Datenbanküberblick für die Datenbank.
  2. Klicken Sie im linken Bereich auf den Menüpunkt Import/Export. Auf der Datenbankseite Import/Export wird eine Liste der letzten Jobs angezeigt.
  3. Klicken Sie auf der Seite Import/Export der Datenbank in der Spalte Dataflow-Jobname auf den Jobnamen:

    Statusmeldung für laufende Jobs

    Die Google Cloud Console zeigt Details des Dataflow Jobs an.

So rufen Sie einen Job auf, den Sie vor mehr als einer Woche ausgeführt haben:

  1. Öffnen Sie in der Google Cloud Console die Seite „Dataflow-Jobs“.

    ZU JOBS

  2. Suchen Sie den Job in der Liste und klicken Sie auf seinen Namen.

    Die Google Cloud Console zeigt Details des Dataflow Jobs an.

Dataflow-Logs für einen Job aufrufen

Rufen Sie die Detailseite des Jobs auf und klicken Sie rechts neben dem Jobnamen auf Logs , um die Logs eines Dataflow-Jobs anzusehen.

Wenn ein Job fehlschlägt, suchen Sie in den Logs nach Fehlern. Falls Fehler aufgetreten sind, ist neben Logs die Fehleranzahl zu sehen:

Beispiel für Fehleranzahl neben der Schaltfläche "Logs"

So sehen Sie sich Jobfehler genauer an:

  1. Klicken Sie auf die Fehleranzahl neben Logs.

    In der Google Cloud Console können Sie die Logs des Jobs ansehen. Unter Umständen müssen Sie scrollen, um die Fehler einzublenden.

  2. Suchen Sie nach Einträgen mit dem Fehlersymbol Fehlersymbol.

  3. Klicken Sie auf einen Logeintrag, um ihn zu maximieren.

Weitere Informationen zur Fehlerbehebung bei Dataflow-Jobs finden Sie unter Pipelinefehler beheben.

Fehlerbehebung bei fehlgeschlagenen Exportjobs

Wenn in Ihren Joblogs die folgenden Fehler angezeigt werden:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Prüfen Sie die 99%-Leselatenz in der Google Cloud Console auf dem Tab Monitoring Ihrer Spanner-Datenbank. Wenn hohe Werte angezeigt werden (mehrere Sekunden), dann bedeutet dies, dass die Instanz überlastet ist, was zu Lesefehlern führt.

Eine Ursache für eine hohe Latenz ist, dass der Dataflow-Job mit zu vielen Workern ausgeführt wird und die Spanner-Instanz zu stark belastet wird.

Um eine Beschränkung für die Anzahl der Dataflow-Worker festzulegen, müssen Sie den Export statt auf der Seite mit den Instanzdetails in Ihrer Spanner-Datenbank über den Console-Tab „Importieren/Exportieren“ über die Dataflow-Vorlage Spanner für Cloud Storage Avro starten und dabei die maximale Worker-Anzahl wie beschrieben angeben: Google Cloud

Console

Wenn Sie die Dataflow Console verwenden, befindet sich der Parameter Max. Worker im Abschnitt Optionale Parameter auf der Seite Job aus Vorlage erstellen.

Zu Dataflow

gcloud

Führen Sie den gcloud dataflow jobs run Befehl aus und geben Sie das max-workers Argument an. Beispiel:

  gcloud dataflow jobs run my-export-job \
    --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Fehlerbehebung bei Netzwerkfehlern

Beim Exportieren von Spanner-Datenbanken kann der folgende Fehler auftreten:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Dieser Fehler tritt auf, weil Spanner davon ausgeht, dass Sie im selben Projekt wie der Dataflow-Job ein VPC-Netzwerk im automatischen Modus namens default verwenden möchten. Wenn Sie im Projekt kein Standard-VPC-Netzwerk haben oder für Ihr VPC-Netzwerk der benutzerdefinierte Modus gilt, müssen Sie einen Dataflow-Job erstellen und ein alternatives Netzwerk oder Subnetzwerk angeben.

Ausführung von Exportjobs beschleunigen

Wenn Sie die Vorschläge für die Anfangseinstellungen befolgt haben, sollten in der Regel keine weiteren Anpassungen nötig sein. Falls der Job jedoch langsam ausgeführt wird, können Sie einige andere Optimierungen versuchen:

Faktoren, die sich auf die Leistung von Exportjobs auswirken

Mehrere Faktoren beeinflussen die Zeit, die für einen Exportjob benötigt wird.

  • Größe der Spanner-Datenbank: Die Verarbeitung von mehr Daten erfordert mehr Zeit und Ressourcen.

  • Spanner-Datenbankschema, einschließlich:

    • Anzahl der Tabellen
    • Größe der Zeilen
    • Anzahl der sekundären Indexe
    • Anzahl der Fremdschlüssel
    • Anzahl der Änderungsstreams

  • Datenspeicherort: Daten werden mit Dataflow zwischen Spanner und Cloud Storage übertragen. Idealerweise befinden sich alle drei Komponenten in derselben Region. Wenn das nicht der Fall ist, dauert das regionsübergreifende Verschieben der Daten länger.

  • Anzahl der Dataflow-Worker: Optimale Dataflow-Worker sind für eine gute Leistung erforderlich. Mithilfe von Autoscaling wählt Dataflow die Anzahl der Worker für einen Job abhängig vom Arbeitsumfang aus. Diese Anzahl wird jedoch durch die Kontingente für CPUs, verwendete IP-Adressen und nichtflüchtigen Standardspeicher begrenzt. In der Dataflow-UI ist ein Warnsymbol zu sehen, wenn Kontingentobergrenzen erreicht werden. In diesem Fall dauert die Verarbeitung länger, aber der Job sollte dennoch abgeschlossen werden.

  • Bestehende Auslastung von Spanner: Ein Exportjob stellt normalerweise eine geringe Last für eine Spanner Instanz dar. Wenn die Instanz jedoch bereits eine erhebliche bestehende Auslastung aufweist, wird der Job langsamer ausgeführt.

  • Menge der Spanner-Rechenkapazität: Wenn die CPU-Auslastung für die Instanz über 65 % liegt, wird der Job langsamer ausgeführt.