Daten aus Nicht-Cloud Spanner-Datenbanken importieren

Auf dieser Seite wird beschrieben, wie Sie Avro-Dateien vorbereiten, die Sie aus Nicht-Spanner-Datenbanken exportiert haben, und diese Dateien dann in Spanner importieren. Diese Verfahren enthalten Informationen für Datenbanken im GoogleSQL-Dialekt und Datenbanken im PostgreSQL-Dialekt. Wenn Sie eine zuvor exportierte Spanner-Datenbank importieren möchten, lesen Sie den Abschnitt Spanner-Avro-Dateien importieren.

Der Vorgang verwendet Dataflow; Es importiert Daten aus einem Cloud Storage-Bucket, der eine Reihe von Avro-Dateien und eine JSON-Manifestdatei enthält, die die Zieltabellen und Avro-Dateien angibt, mit denen die einzelnen Tabellen gefüllt werden.

Hinweis

Wenn Sie eine Spanner-Datenbank importieren möchten, müssen Sie zuerst die APIs für Spanner, Cloud Storage, Compute Engine und Dataflow API aktivieren:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

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

Kontingentanforderungen

Für Importjobs gelten die folgenden Kontingentanforderungen:

• Spanner: Sie müssen über genügend Rechenkapazität verfügen, um die zu importierende Datenmenge zu unterstützen. Für den Import 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 Importieren benötigen Sie einen Bucket mit Ihren zuvor exportierten Dateien. Sie müssen keine Größe für Ihren Bucket festlegen.
• Dataflow: Für Importjobs gelten dieselben Compute Engine-Kontingente für CPU, Laufwerksnutzung und IP-Adressen wie für andere Dataflow-Jobs.

• Compute Engine: Bevor Sie den Importjob ausführen, müssen Sie zuerst Kontingente für Compute Engine einrichten, die von Dataflow verwendet werden. Diese Kontingente stellen die maximale Anzahl von Ressourcen dar, die Dataflow für Ihren Job verwenden darf. Empfohlene Anfangswerte sind:

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

  In der Regel müssen Sie keine weiteren Anpassungen vornehmen. Dataflow bietet Autoscaling, sodass Sie nur für die Ressourcen zahlen, die beim Import 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:

• Cloud Spanner-Betrachter (roles/spanner.viewer)
• Dataflow-Worker (roles/dataflow.worker)
• Storage-Administrator (roles/storage.admin)
• Spanner-Datenbankleser (roles/spanner.databaseReader)
• Database Admin (roles/spanner.databaseAdmin)

Hinweis: Die Rolle „Spanner-Datenbankadministrator“ ist nur für Importjobs erforderlich.

Daten aus einer Nicht-Spanner-Datenbank in Avro-Dateien exportieren

Beim Importvorgang werden Daten aus Avro-Dateien in einem Cloud Storage-Bucket übernommen. Sie können Daten im Avro-Format aus jeder Quelle exportieren und dazu jede verfügbare Methode verwenden.

So exportieren Sie Daten aus einer Nicht-Spanner-Datenbank in Avro-Dateien:

Beachten Sie beim Exportieren Ihrer Daten folgende Punkte:

• Der Export lässt sich mit einem der primitiven Avro-Typen sowie mit dem komplexen Array-Typ ausführen.

• Jede Spalte der Avro-Dateien muss einen der folgenden Spaltentypen verwenden:

  • ARRAY
  • BOOL
  • BYTES^*
  • DOUBLE
  • FLOAT
  • INT
  • LONG^†
  • STRING^‡

  ^* Eine Spalte vom Typ BYTES wird verwendet, um einen Spanner-NUMERIC zu importieren. Weitere Informationen finden Sie im folgenden Abschnitt Empfohlene Zuordnungen.

  ^†,‡ Sie können einen LONG, der einen Zeitstempel speichert, oder einen STRING, der einen Zeitstempel speichert, als Spanner-TIMESTAMP importieren. Weitere Informationen finden Sie im folgenden Abschnitt Empfohlene Zuordnungen.

• Sie müssen beim Exportieren der Avro-Dateien keine Metadaten einfügen oder generieren.

• Sie müssen für Ihre Dateien keine bestimmte Namenskonvention einhalten.

Wenn Sie Ihre Dateien nicht direkt nach Cloud Storage exportieren, müssen Sie die Avro-Dateien in einen Cloud Storage-Bucket hochladen. Eine ausführliche Anleitung finden Sie unter Objekte in Cloud Storage hochladen.

Avro-Dateien aus Nicht-Spanner-Datenbanken in Spanner importieren

So importieren Sie Avro-Dateien aus einer Nicht-Spanner-Datenbank in Spanner:

1. Erstellen Sie Zieltabellen und definieren Sie das Schema für Ihre Spanner-Datenbank.
2. Erstellen Sie in Ihrem Cloud Storage-Bucket eine spanner-export.json-Datei.
3. Führen Sie einen Dataflow-Importjob mit der Google Cloud CLI aus.

Schritt 1: Schema für die Spanner-Datenbank erstellen

Bevor Sie den Import ausführen, müssen Sie die Zieltabelle in Spanner erstellen und ihr Schema definieren.

Sie müssen ein Schema erstellen, das den entsprechenden Spaltentyp für jede Spalte in den Avro-Dateien verwendet.

Empfohlene Zuordnungen

GoogleSQL

Avro-Spaltentyp	Spanner-Spaltentyp
ARRAY	ARRAY
BOOL	BOOL
BYTES	BYTES NUMERIC (wenn der Spaltentyp BYTES und logicalType=decimal, precision=38 und scale=9 ist. Wenn diese genauen Spezifikationen weggelassen werden, wird das Feld als Spanner-BYTES-Wert behandelt. Weitere Informationen finden Sie in der Dokumentation zum Logischen Avro-Dezimaltyp.)
DOUBLE	FLOAT64
FLOAT	FLOAT64
INT	INT64
LONG	INT64 TIMESTAMP, wobei LONG einen Zeitstempel der Anzahl der Mikrosekunden seit dem 01.01.1970, 00:00:00 Uhr (UTC) darstellt
STRING	STRING TIMESTAMP, wenn STRING einen Zeitstempel im kanonischen Format für SQL-Abfragen darstellt

PostgreSQL

Avro-Spaltentyp	Spanner-Spaltentyp
ARRAY	ARRAY
BOOL	BOOLEAN
BYTES	BYTEA NUMERIC (wenn der Spaltentyp BYTEA und logicalType=decimal, precision=147455 und scale=16383 ist. Wenn diese genauen Spezifikationen weggelassen werden, wird das Feld als BYTEA-Wert behandelt. Weitere Informationen finden Sie in der Dokumentation zum Logischen Avro-Dezimaltyp.)
DOUBLE	DOUBLE PRECISION
FLOAT	DOUBLE PRECISION
INT	BIGINT
LONG	BIGINT TIMESTAMP, wobei LONG einen Zeitstempel der Anzahl der Mikrosekunden seit dem 01.01.1970, 00:00:00 Uhr (UTC) darstellt
STRING	CHARACTER VARYING TIMESTAMP, wobei STRING einen Zeitstempel im kanonischen Format für SQL-Abfragen darstellt, z. B. „2022-05-28T07:08:21.123456789Z“ oder „2021-12-19T16:39:57-08:00“.

Hinweis: Wenn eine Spalte in Ihren Avro-Daten NULL-Werte enthält, müssen Sie dafür sorgen, dass die entsprechende Spalte in Ihrer Spanner-Tabelle Nullwerte zulässt.

Schritt 2: Datei „spanner-export.json“ erstellen

Außerdem müssen Sie in Ihrem Cloud Storage-Bucket eine Datei mit dem Namen spanner-export.json erstellen. In dieser Datei wird der Datenbankdialekt angegeben. Sie enthält ein tables-Array, in dem der Name und die Speicherorte der Datendateien für jede Tabelle aufgeführt sind.

Der Inhalt der Datei hat folgendes Format:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

Dabei gilt: DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

Wenn das Dialekt-Element weggelassen wird, wird der Dialekt standardmäßig auf GOOGLE_STANDARD_SQL gesetzt.

Hinweis: Platzhalter werden nicht unterstützt. Sie müssen alle Dateinamen vollständig ausschreiben.

Schritt 3: Dataflow-Importjob mit der gcloud CLI ausführen

Wenn Sie den Importjob starten möchten, folgen Sie der Anleitung zur Verwendung der gcloud CLI, um einen Job mit der Avro-zu-Spanner-Vorlage auszuführen.

Nachdem Sie einen Importjob gestartet haben, können Sie in der Google Cloud Console Details zum Job aufrufen.

Fügen Sie nach Abschluss des Importjobs alle erforderlichen sekundären Indexe und Fremdschlüssel hinzu.

Hinweis: Wählen Sie eine Region aus, die mit dem Standort Ihres Cloud Storage-Bucket übereinstimmt, um Gebühren für die ausgehende Datenübertragung zu vermeiden. Weitere Informationen finden Sie unter Region auswählen.

Hinweis: Der Dataflow-Job löst keine verschachtelten Tabellen oder Fremdschlüsseleinschränkungen auf. Daher können Schreibfehler aufgrund von Verletzungen der referenziellen Integrität auftreten. Entfernen Sie alle Interleaving-Beziehungen oder Fremdschlüssel, bevor Sie den Dataflow-Job starten.

Wählen Sie eine Region für den Importjob aus.

Je nach Standort Ihres Cloud Storage-Bucket sollten Sie eventuell eine andere Region auswählen. Wählen Sie eine Region aus, die dem Standort Ihres Cloud Storage-Bucket entspricht, um Gebühren für die ausgehende Datenübertragung zu vermeiden.

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

• Wenn sich Ihr Cloud Storage-Bucket in einer Dual-Region befindet, können Sie die kostenlose Netzwerknutzung in Anspruch nehmen, indem Sie eine der beiden Regionen, aus denen die Dual-Region besteht, für Ihren Importjob auswählen, sofern eine der Regionen verfügbar ist.

• Wenn für Ihren Importjob keine Region am selben Standort verfügbar ist oder wenn sich Ihr Cloud Storage-Bucket an einem multiregionalen Standort befindet, fallen Gebühren für die ausgehende Datenübertragung an. Informationen zu den Preisen für die Datenübertragung in Cloud Storage finden Sie unter „Cloud Storage – Preise“. Wählen Sie eine Region aus, für die die niedrigsten Gebühren für die Datenübertragung anfallen.

Jobs in der Dataflow-UI ansehen oder Fehler beheben

Nachdem Sie einen Importjob gestartet haben, können Sie im Dataflow-Bereich der Google Cloud Console Details zum Job aufrufen, einschließlich Logs.

Details zum Dataflow-Job ansehen

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

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:

   

   In der Google Cloud Console werden Details zum Dataflow-Job angezeigt.

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

1. Rufen Sie in der Google Cloud Console die Seite „Dataflow-Jobs“ auf.

   ZU JOBS

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

   In der Google Cloud Console werden Details zum Dataflow-Job angezeigt.

Hinweis: Jobs desselben Typs für dieselbe Datenbank haben denselben Namen. Sie können sie anhand der Werte in den Spalten Beginn und Ende unterscheiden.

Dataflow-Logs für Ihren Job ansehen

Wenn Sie die Logs eines Dataflow-Jobs aufrufen möchten, rufen Sie die Detailseite des Jobs auf und klicken Sie rechts neben dem Jobnamen auf Logs.

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

So sehen Sie sich Jobfehler genauer an:

1. Klicken Sie neben Logs auf die Anzahl der Fehler.

   In der Google Cloud Console werden die Logs des Jobs angezeigt. Unter Umständen müssen Sie scrollen, um die Fehler einzublenden.

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

3. Klicken Sie auf einen einzelnen Logeintrag, um seinen Inhalt zu maximieren.

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

Fehlerbehebung bei fehlgeschlagenen Importjobs

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 % Schreiblatenz auf dem Tab Monitoring Ihrer Spanner-Datenbank in derGoogle Cloud Console. Wenn hohe Werte angezeigt werden (mehrere Sekunden), bedeutet dies, dass die Instanz überlastet ist, was zu Schreibfehlern führt.

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

Wenn Sie die Anzahl der Dataflow-Worker begrenzen möchten, müssen Sie den Import mit der Dataflow-Vorlage Cloud Storage Avro zu Spanner starten und die maximale Anzahl von Workern wie beschrieben angeben, anstatt den Tab „Importieren/Exportieren“ auf der Detailseite der Instanzdetails Ihrer Spanner-Datenbank in der Google Cloud Console zu verwenden:

Console

Wenn Sie die Dataflow-Konsole verwenden, befindet sich der Parameter Maximale Anzahl von Workern im Abschnitt Optionale Parameter der Seite Job aus Vorlage erstellen.

Zu Dataflow

gcloud

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

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

Netzwerkfehler beheben

Der folgende Fehler kann auftreten, wenn Sie Ihre Spanner-Datenbanken exportieren:

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 Cloud 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 Ihr VPC-Netzwerk ein VPC-Netzwerk im benutzerdefinierten Modus ist, müssen Sie einen Dataflow-Job erstellen und ein alternatives Netzwerk oder Subnetzwerk angeben.

Langsame Importjobs optimieren

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:

• Job- und Datenstandort optimieren: Führen Sie Ihren Dataflow-Job in derselben Region aus, in der sich Ihre Spanner-Instanz und Ihr Cloud Storage-Bucket befinden.

• Ausreichende Dataflow-Ressourcen sicherstellen: Wenn die relevanten Compute Engine-Kontingente die Ressourcen Ihres Dataflow-Jobs einschränken, wird auf der Dataflow-Seite des Jobs in der Google Cloud -Console ein Warnsymbol und Logeinträge angezeigt:

  

  In diesem Fall kann das Erhöhen der Kontingente für CPUs, verwendete IP-Adressen und nichtflüchtigen Standardspeicher die Ausführungszeit des Jobs verkürzen, aber auch höhere Compute Engine-Gebühren zur Folge haben.

• Spanner-CPU-Auslastung prüfen: Wenn die CPU-Auslastung für die Instanz über 65 % liegt, können Sie die Rechenkapazität in dieser Instanz erhöhen. Durch die Kapazität werden mehr Spanner-Ressourcen hinzugefügt und der Job sollte schneller ausgeführt werden. Es fallen jedoch mehr Spanner-Gebühren an.

Faktoren, die sich auf die Leistung von Importjobs auswirken

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

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

• Spanner-Datenbankschema, einschließlich:

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

• Speicherort der Daten: 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. Autoscaling kann Spanner überlasten, was zu Fehlern führt, wenn eine große Datenmenge importiert werden muss.

• Vorhandene Last in Spanner: Ein Importjob verursacht eine erhebliche CPU-Last auf einer Spanner-Instanz. 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.

Worker für eine gute Importleistung optimieren

Beim Starten eines Spanner-Importjobs müssen Dataflow-Worker auf einen optimalen Wert für eine gute Leistung festgelegt werden. Zu viele Worker überlasten Spanner und zu wenige Worker führen zu einer unzureichenden Importleistung.

Die maximale Anzahl von Workern hängt stark von der Datengröße ab. Idealerweise sollte die gesamte Spanner-CPU-Auslastung jedoch zwischen 70 % und 90 % liegen. Dies bietet ein gutes Gleichgewicht zwischen Spanner-Effizienz und fehlerfreiem Jobabschluss.

Um dieses Auslastungsziel in den meisten Schemas und Szenarien zu erreichen, empfehlen wir eine maximale Anzahl von Worker-vCPUs, die dem 4- bis 6-Fachen der Anzahl der Spanner-Knoten entspricht.

Für eine Spanner-Instanz mit 10 Knoten und n1-standard-2-Workern würden Sie beispielsweise die maximale Anzahl von Workern auf 25 festlegen, was 50 vCPUs entspricht.