PostgreSQL-Daten in BigQuery laden

Wenn Sie wiederkehrende Datenübertragungen von PostgreSQL nach BigQuery planen möchten, können Sie eine Übertragungskonfiguration erstellen, um anzugeben, welche Datenobjekte übertragen werden sollen und wie oft die Datenübertragung geplant werden soll. Nachdem Sie die Übertragungskonfiguration eingerichtet haben, überträgt der BigQuery Data Transfer Service die neuesten Daten nach dem angegebenen Zeitplan in eine BigQuery-Tabelle.

Allgemeine Informationen zu PostgreSQL-Übertragungen, einschließlich Konfigurationsoptionen, finden Sie unter Einführung in PostgreSQL-Datenübertragungen.

Beschränkungen

Für PostgreSQL-Datenübertragungen gelten die folgenden Einschränkungen:

  • Die maximale Anzahl gleichzeitiger Übertragungsvorgänge zu einer einzelnen PostgreSQL Datenbank wird durch die maximale Anzahl gleichzeitiger Verbindungen bestimmt, die von der PostgreSQL-Datenbank unterstützt werden. Die Anzahl gleichzeitiger Übertragungsjobs sollte auf einen Wert begrenzt sein, der kleiner als die maximale Anzahl gleichzeitiger Verbindungen ist, die von der PostgreSQL-Datenbank unterstützt werden.

  • Eine einzelne Übertragungskonfiguration kann jeweils nur einen Datenübertragungsvorgang unterstützen. Wenn eine zweite Datenübertragung geplant ist, bevor die erste abgeschlossen ist, wird nur die erste Datenübertragung abgeschlossen. Alle anderen Datenübertragungen, die sich mit der ersten Übertragung überschneiden, werden übersprungen.

    Um zu vermeiden, dass Übertragungen innerhalb einer einzelnen Übertragungskonfiguration übersprungen werden, empfehlen wir, die Zeit zwischen großen Datenübertragungen zu verlängern, indem Sie die Wiederholungshäufigkeit konfigurieren.

  • Während einer Datenübertragung identifiziert der PostgreSQL-Connector indexierte und partitionierte Schlüsselspalten, um Ihre Daten in parallelen Batches zu übertragen. Aus diesem Grund empfehlen wir, Primärschlüsselspalten anzugeben oder indexierte Spalten in Ihrer Tabelle zu verwenden, um die Leistung zu verbessern und die Fehlerrate bei Ihren Datenübertragungen zu reduzieren. Berücksichtige Folgendes:

    • Wenn Sie indexierte oder Primärschlüsseleinschränkungen haben, werden nur die folgenden Spaltentypen für die Erstellung paralleler Batches unterstützt:
      • INTEGER
      • TINYINT
      • SMALLINT
      • FLOAT
      • REAL
      • DOUBLE
      • NUMERIC
      • BIGINT
      • DECIMAL
      • DATE
    • PostgreSQL-Datenübertragungen,bei denen keine Primärschlüssel- oder indexierten Spalten verwendet werden,können nicht mehr als 2.000.000 Datensätze pro Tabelle unterstützen.

Einschränkungen für inkrementelle Übertragungen

Für inkrementelle PostgreSQL-Übertragungen gelten die folgenden Einschränkungen:

  • Sie können nur TIMESTAMP-Spalten als Watermark-Spalten auswählen.
  • Die inkrementelle Aufnahme wird nur für Assets mit gültigen Watermark-Spalten unterstützt.
  • Die Werte in einer Watermark-Spalte müssen monoton ansteigen.
  • Bei inkrementellen Übertragungen können Löschvorgänge in der Quelltabelle nicht synchronisiert werden.
  • Eine einzelne Übertragungskonfiguration kann nur entweder die inkrementelle oder die vollständige Aufnahme unterstützen.
  • Sie können Objekte in der Liste asset nach der ersten inkrementellen Aufnahme nicht mehr aktualisieren.
  • Sie können den Schreibmodus in einer Übertragungskonfiguration nach der ersten inkrementellen Aufnahme nicht mehr ändern.
  • Sie können die Watermark-Spalte oder den Primärschlüssel nach der ersten inkrementellen Aufnahme nicht mehr ändern.
  • Die BigQuery-Zieltabelle wird mit dem angegebenen Primärschlüssel geclustert und unterliegt den Einschränkungen für geclusterte Tabellen.

  • Wenn Sie eine vorhandene Übertragungskonfiguration zum ersten Mal in den inkrementellen Aufnahmemodus aktualisieren, werden bei der ersten Datenübertragung nach dieser Aktualisierung alle verfügbaren Daten aus Ihrer Datenquelle übertragen. Bei allen nachfolgenden inkrementellen Datenübertragungen werden nur die neuen und aktualisierten Zeilen aus Ihrer Datenquelle übertragen.

  • Wir empfehlen, Indexe für die Watermark-Spalte zu erstellen. Dieser Connector verwendet Watermark-Spalten für Filter bei inkrementellen Übertragungen. Das Indexieren dieser Spalten kann die Leistung verbessern.

  • Bei einer inkrementellen Übertragung müssen Sie die aktualisierte Datentypzuordnung verwenden.

Hinweis

Erforderliche Rollen

Wenn Sie Benachrichtigungen zur Übertragungsausführung für Pub/Sub einrichten möchten, benötigen Sie die IAM-Berechtigung (Identity and Access Management) pubsub.topics.setIamPolicy. Pub/Sub-Berechtigungen sind nicht erforderlich, wenn Sie nur E‑Mail-Benachrichtigungen einrichten. Weitere Informationen finden Sie unter Ausführungsbenachrichtigungen im BigQuery Data Transfer Service.

Bitten Sie Ihren Administrator, Ihnen die BigQuery-Administrator (roles/bigquery.admin) IAM-Rolle für Ihr Projekt zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Erstellen einer BigQuery Data Transfer Service-Datenübertragung benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen einer BigQuery Data Transfer Service-Datenübertragung erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um eine BigQuery Data Transfer Service-Datenübertragung zu erstellen:

  • Berechtigungen für BigQuery Data Transfer Service:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • BigQuery-Berechtigungen:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen finden Sie unter Zugriff auf bigquery.admin gewähren.

Netzwerkverbindungen

Wenn für die PostgreSQL Datenbankverbindung keine öffentliche IP-Adresse verfügbar ist, müssen Sie einen Netzwerkanhang einrichten.

Eine detaillierte Anleitung zur erforderlichen Netzwerkeinrichtung finden Sie in den folgenden Dokumenten:

PostgreSQL-Datenübertragung einrichten

Fügen Sie PostgreSQL-Daten in BigQuery hinzu, indem Sie eine Übertragungskonfiguration mit einer der folgenden Optionen einrichten:

Console

  1. Rufen Sie die Seite Datenübertragungen auf.

    Zu „Datenübertragungen“

  2. Klicken Sie auf Übertragung erstellen.

  3. Wählen Sie im Abschnitt Quelltyp für Quelle die Option PostgreSQL aus.

  4. Führen Sie im Abschnitt Details zur Datenquelle folgende Schritte aus:

    • Wählen Sie unter Netzwerkanhang einen vorhandenen Netzwerkanhang aus oder klicken Sie auf Netzwerkanhang erstellen. Weitere Informationen finden Sie im Abschnitt Netzwerkverbindungen in diesem Dokument.
    • Geben Sie unter Host den Hostnamen oder die IP-Adresse des PostgreSQL-Datenbankservers ein.
    • Geben Sie unter Portnummer die Portnummer für den PostgreSQL Datenbankserver ein.
    • Geben Sie unter Datenbankname den Namen der PostgreSQL Datenbank ein.
    • Geben Sie unter Nutzername den Nutzernamen des PostgreSQL Nutzers ein, der die PostgreSQL-Datenbankverbindung initiiert.
    • Geben Sie unter Passwort das Passwort des PostgreSQL -Nutzers ein, der die PostgreSQL-Datenbankverbindung initiiert.
    • Wählen Sie für TLS-Modus eine Option aus dem Menü aus. Weitere Informationen zu TLS-Modi finden Sie unter TLS-Konfiguration.
    • Geben Sie für Trusted PEM Certificate (Zertifikat für vertrauenswürdigen PEM) das öffentliche Zertifikat der Zertifizierungsstelle ein, die das TLS-Zertifikat des Datenbankservers ausgestellt hat. Weitere Informationen finden Sie unter Zertifikat für vertrauenswürdigen Serverzertifikat (PEM).
    • Wählen Sie für Legacy-Zuordnung aktivieren true (Standard) aus, um die Legacy Datentypzuordnung zu verwenden. Wählen Sie false aus, um die aktualisierte Datentypzuordnung zu verwenden. Wenn Sie eine inkrementelle Übertragung vornehmen, muss dieser Wert false sein. Weitere Informationen zu den Datentyp zuordnungsaktualisierungen finden Sie unter 16. März 2027. Datenbankserver.
    • Wählen Sie für Aufnahmetyp die Option Vollständig oder Inkrementell aus.

    • Klicken Sie unter Zu übertragende PostgreSQL-Objekte auf Durchsuchen.

      Wählen Sie alle Objekte aus, die an das BigQuery-Ziel-Dataset übertragen werden sollen. Sie können in dieses Feld auch manuell alle Objekte eingeben, die in die Datenübertragung einbezogen werden sollen.

      • Wenn Sie Append als inkrementellen Schreibmodus ausgewählt haben, müssen Sie eine Spalte als Watermark-Spalte auswählen.
      • Wenn Sie Upsert als inkrementellen Schreibmodus gewählt haben, müssen Sie eine Spalte als Watermark-Spalte und darauf eine oder mehrere Spalten als Primärschlüssel auswählen.

  5. Geben Sie im Abschnitt Konfigurationsname für Übertragung für Anzeigename einen Namen für die Übertragung ein. Der Name kann ein beliebiger Wert sein, anhand dessen Sie die Übertragung identifizieren können, falls Sie sie später ändern müssen.

  6. Führen Sie im Abschnitt Zeitplanoptionen folgende Schritte aus:

    • Wählen Sie eine Wiederholungshäufigkeit aus. Wenn Sie die Option Stunden, Tage (Standard), Wochen oder Monate auswählen, müssen Sie auch eine Häufigkeit angeben. Sie können auch die Option Benutzerdefiniert auswählen, um eine genauere Wiederholungshäufigkeit festzulegen. Wenn Sie die Option On-demand auswählen, wird diese Datenübertragung nur ausgeführt, wenn Sie die Übertragung manuell auslösen.
    • Wählen Sie gegebenenfalls die Option Jetzt starten oder Zu festgelegter Zeit starten aus und geben Sie ein Startdatum und eine Laufzeit an.

  7. Wählen Sie im Abschnitt Zieleinstellungen für Dataset das Dataset aus, das Sie zum Speichern Ihrer Daten erstellt haben, oder klicken Sie auf Neues Dataset erstellen und erstellen Sie ein Dataset, das als Ziel-Dataset verwendet werden soll.

  8. Optional: Gehen Sie im Abschnitt Benachrichtigungsoptionen so vor:

  9. Klicken Sie auf Speichern.

bq

Geben Sie den bq mk Befehl ein und geben Sie das Flag für die Übertragungserstellung --transfer_config an:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Ersetzen Sie Folgendes:

  • PROJECT_ID (optional): Ihre Google Cloud Projekt-ID. Wenn das Flag --project_id nicht angegeben wird, um ein bestimmtes Projekt anzugeben, wird das Standardprojekt verwendet.
  • DATA_SOURCE: die Datenquelle, die postgresql ist.
  • DISPLAY_NAME: der Anzeigename für die Datenübertragungs konfiguration. Der Name kann ein beliebiger Wert sein, anhand dessen Sie die Übertragung identifizieren können, falls Sie sie später ändern müssen.
  • DATASET: das Ziel-Dataset für die Datenübertragungs konfiguration.

  • PARAMETERS: die Parameter für die erstellte Übertragungs konfiguration im JSON-Format. Beispiel: --params='{"param":"param_value"}'. Im Folgenden finden Sie die Parameter für eine PostgreSQL-Übertragung:

    • connector.networkAttachment (optional): der Name des Netzwerkanhangs, der eine Verbindung zur PostgreSQL-Datenbank herstellen soll.
    • connector.database: der Name der PostgreSQL-Datenbank.
    • connector.endpoint.host: der Hostname oder die IP-Adresse der Datenbank.
    • connector.endpoint.port: die Portnummer der Datenbank.
    • connector.authentication.username: der Nutzername des Datenbanknutzers.
    • connector.authentication.password: das Passwort des Datenbanknutzers.
    • connector.tls.mode: Geben Sie eine TLS-Konfiguration an, die für diese Übertragung verwendet werden soll:
      • ENCRYPT_VERIFY_CA_AND_HOST zum Verschlüsseln von Daten und Überprüfen der Zertifizierungsstelle und des Hostnamens
      • ENCRYPT_VERIFY_CA zum Verschlüsseln von Daten und Überprüfen nur der Zertifizierungsstelle
      • ENCRYPT_VERIFY_NONE nur für die Datenverschlüsselung
      • DISABLE für keine Verschlüsselung oder Überprüfung
    • connector.tls.trustedServerCertificate: (optional) Geben Sie ein oder mehrere PEM-codierte Zertifikate an. Nur erforderlich, wenn connector.tls.mode auf ENCRYPT_VERIFY_CA_AND_HOST oder ENCRYPT_VERIFY_CA gesetzt ist.
    • ingestionType: Geben Sie entweder full oder incremental an. Inkrementelle Übertragungen werden in der Vorschauunterstützt. Weitere Informationen finden Sie unter Vollständige oder inkrementelle Übertragungen.
    • writeMode: Geben Sie entweder WRITE_MODE_APPEND oder WRITE_MODE_UPSERT an.
    • watermarkColumns: Geben Sie Spalten in Ihrer Tabelle als Watermark-Spalten an. Dieses Feld ist für inkrementelle Übertragungen erforderlich.
    • primaryKeys: Geben Sie Spalten in Ihrer Tabelle als Primärschlüssel an. Dieses Feld ist für inkrementelle Übertragungen erforderlich.
    • connector.legacyMapping: Setzen Sie den Wert auf true (Standard), um die Legacy Datentypzuordnung zu verwenden. Setzen Sie den Wert auf false, um die aktualisierte Datentypzuordnung zu verwenden. Wenn Sie eine inkrementelle Übertragung vornehmen, muss dieser Wert false sein. Weitere Informationen zu den Aktualisierungen der Datentyp zuordnung finden Sie unter 16. März, 2027.
    • assets: eine Liste der Namen der PostgreSQL-Tabellen, die im Rahmen der Übertragung aus der PostgreSQL-Datenbank übertragen werden sollen.

Mit dem folgenden Befehl wird beispielsweise eine PostgreSQL-Übertragung namens My Transfer erstellt:

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=postgresql
    --display_name='My Transfer'
    --params='{"assets":["DB1/PUBLIC/DEPARTMENT","DB1/PUBLIC/EMPLOYEES"],
        "connector.authentication.username": "User1",
        "connector.authentication.password":"ABC12345",
        "connector.database":"DB1",
        "connector.endpoint.host":"192.168.0.1",
        "connector.endpoint.port":5432,
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_APPEND",
        "watermarkColumns":["createdAt","createdAt"],
        "primaryKeys":[['dep_id'], ['report_by','report_title']],
        "connector.tls.mode": "ENCRYPT_VERIFY_CA_AND_HOST",
        "connector.tls.trustedServerCertificate": "PEM-encoded certificate"}'

Wenn Sie bei einer inkrementellen Übertragung mehrere Assets angeben, entsprechen die Werte der Felder watermarkColumns und primaryKeys der Position der Werte im Feld assets. Im folgenden Beispiel entspricht dep_id der Tabelle DB1/USER1/DEPARTMENT, während report_by und report_title der Tabelle DB1/USER1/EMPLOYEES entsprechen.

      "primaryKeys":[['dep_id'], ['report_by','report_title']],
      "assets":["DB1/USER1/DEPARTMENT","DB1/USER1/EMPLOYEES"],

API

Verwenden Sie die projects.locations.transferConfigs.create Methode und geben Sie eine Instanz der TransferConfig Ressource an.

Wenn Sie die Übertragungskonfiguration speichern, löst der PostgreSQL-Connector automatisch eine Übertragungsausführung gemäß Ihrer Zeitplanoption aus. Bei jeder Übertragungsausführung überträgt der PostgreSQL-Connector alle verfügbaren Daten aus PostgreSQL nach BigQuery.

Wenn Sie eine Datenübertragung außerhalb des regulären Zeitplans manuell ausführen möchten, können Sie einen Backfill-Vorgang starten.

Fehlerbehebung

Unterstützung bei Problemen mit der Einrichtung von Datenübertragungen finden Sie unter PostgreSQL-Übertragungsprobleme.

Metadaten übertragen

Sie können mit dem PostgreSQL-Connector auch Metadaten in Knowledge Catalog übertragen. Weitere Informationen finden Sie unter PostgreSQL-Metadaten in Knowledge Catalog laden.

Nächste Schritte