PostgreSQL-Daten in BigQuery laden

Wenn Sie wiederkehrende Datenübertragungen von PostgreSQL zu BigQuery planen möchten, können Sie eine Übertragungskonfiguration erstellen, um festzulegen, 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 gemäß dem angegebenen Zeitplan in eine BigQuery-Tabelle.

Informationen zur Funktionsweise einer PostgreSQL-Übertragung finden Sie unter Einführung in PostgreSQL-Datenübertragungen.

Beschränkungen

PostgreSQL-Datenübertragungen unterliegen den folgenden Einschränkungen:

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

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

    Damit innerhalb einer einzelnen Übertragungskonfiguration keine Übertragungen übersprungen werden, empfehlen wir, die Zeitspanne 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 der Tabelle zu verwenden, um die Leistung zu verbessern und die Fehlerrate bei Datenübertragungen zu reduzieren. Berücksichtige Folgendes:

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

Einschränkungen bei inkrementellen Übertragungen

Inkrementelle PostgreSQL-Übertragungen unterliegen den folgenden Einschränkungen:

  • Sie können nur TIMESTAMP Spalten als Wasserzeichenspalten auswählen.
  • Die inkrementelle Aufnahme wird nur für Assets mit gültigen Wasserzeichenspalten unterstützt.
  • Die Werte in einer Wasserzeichenspalte müssen monoton steigend sein.
  • 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.
  • Nach dem ersten inkrementellen Aufnahmevorgang können Sie Objekte in der Liste asset nicht mehr aktualisieren.
  • Sie können den Schreibmodus in einer Übertragungskonfiguration nach der ersten inkrementellen Aufnahme nicht mehr ändern.
  • Nach der ersten inkrementellen Aufnahme können Sie die Wasserzeichenspalte oder den Primärschlüssel 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 auf den inkrementellen Aufnahmemodus aktualisieren, werden bei der ersten Datenübertragung nach diesem Update 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 Wasserzeichenspalte zu erstellen. Dieser Connector verwendet Wasserzeichenspalten für Filter in inkrementellen Übertragungen. Das Indexieren dieser Spalten kann daher 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 IAM-Rolle BigQuery-Administrator (roles/bigquery.admin) für Ihr Projekt zuzuweisen, 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:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen einer BigQuery Data Transfer Service-Datenübertragung erforderlich:

  • 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 bigquery.admin-Zugriff gewähren.

Netzwerkverbindungen

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

Eine ausführliche Anleitung zur erforderlichen Netzwerkeinrichtung finden Sie in den folgenden Dokumenten:

PostgreSQL-Datenübertragung einrichten

Fügen Sie PostgreSQL-Daten zu 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 dieses Dokuments.
    • 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 durchführen, muss dieser Wert false sein. Weitere Informationen zu den Aktualisierungen der Datentypzuordnung finden Sie unter 16. März 2027.
    • 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 Übertragungsname kann ein beliebiger Wert sein, mit dem Sie die Übertragung identifizieren können, wenn 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:

    • Klicken Sie zum Aktivieren von E‑Mail-Benachrichtigungen auf den Ein/Aus-Button E‑Mail-Benachrichtigungen. Wenn Sie diese Option aktivieren, erhält der Übertragungsadministrator eine E‑Mail-Benachrichtigung, falls ein Übertragungsvorgang fehlschlägt.
    • Wenn Sie Pub/Sub-Ausführungsbenachrichtigungen für Ihre Übertragung konfigurieren möchten, aktivieren Sie den Ein/Aus-Button Pub/Sub-Benachrichtigungen. Sie können den Namen für das Thema auswählen oder auf Thema erstellen klicken, um eines zu erstellen.

  9. Klicken Sie auf Speichern.

bq

Geben Sie den Befehl bq mk ein und geben Sie das Flag --transfer_config für die Übertragungserstellung 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 ist, um ein bestimmtes Projekt anzugeben, wird das Standardprojekt verwendet.
  • DATA_SOURCE: die Datenquelle, also postgresql.
  • DISPLAY_NAME: Der Anzeigename für die Datenübertragungskonfiguration. Der Übertragungsname kann ein beliebiger Wert sein, mit dem Sie die Übertragung identifizieren können, wenn Sie sie später ändern müssen.
  • DATASET: Das Ziel-Dataset für die Datenübertragungskonfiguration.

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

    • connector.networkAttachment (optional): 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, um Daten zu verschlüsseln und die Zertifizierungsstelle und den Hostnamen zu überprüfen
      • ENCRYPT_VERIFY_CA, um Daten zu verschlüsseln und nur die Zertifizierungsstelle zu überprüfen
      • 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 ENCRYPT_VERIFY_CA_AND_HOST oder ENCRYPT_VERIFY_CA ist.
    • ingestionType: Geben Sie entweder full oder incremental an. Inkrementelle Übertragungen werden in der Vorabversion unterstü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 Wasserzeichenspalten 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: Auf true (Standard) gesetzt, um die Legacy-Datentypzuordnung zu verwenden. Legen Sie false fest, um die aktualisierte Datentypzuordnung zu verwenden. Wenn Sie eine inkrementelle Übertragung durchführen, muss dieser Wert false sein. Weitere Informationen zu den Aktualisierungen der Datentypzuordnung 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 mit dem Namen 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 Methode projects.locations.transferConfigs.create und geben Sie eine Instanz der Ressource TransferConfig an.

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

Wenn Sie eine Datenübertragung außerhalb Ihres 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 den PostgreSQL-Connector auch verwenden, um Metadaten an Knowledge Catalog zu übertragen. Weitere Informationen finden Sie unter PostgreSQL-Metadaten in Knowledge Catalog laden.

Nächste Schritte