CSV-Datei exportieren

Wenn Sie Tabellen- oder Abfragedaten für die Verwendung in externen Tools und Umgebungen extrahieren möchten, können Sie Daten aus AlloyDB for PostgreSQL-Clustern im CSV-Format in einen Cloud Storage-Bucket exportieren.

Informationen zum Migrieren einer gesamten Datenbank von einem unterstützten Datenbankserver zu einer neuen AlloyDB-Instanz finden Sie unter Datenbank mit dem Database Migration Service zu AlloyDB migrieren. Wenn Sie aus der exportierten Datei eine neue Instanz erstellen möchten, können Sie stattdessen auch einen Cluster aus einer gespeicherten Sicherung wiederherstellen.

Sie können den Export von Daten aus AlloyDB for PostgreSQL-Clustern abbrechen. Weitere Informationen finden Sie unter Exportvorgang abbrechen.

Hinweis

  • Beachten Sie vor dem Starten eines Exportvorgangs, dass Exportvorgänge Datenbankressourcen verwenden, aber den normalen Datenbankbetrieb nicht beeinträchtigen, es sei denn, die Instanz ist unterdimensioniert.
  • SELECT_QUERY kann Kommentare oder voran- und nachgestellte Leerzeichen enthalten. Kommentare werden ignoriert und Leerzeichen werden vor dem Ausführen der Exportabfrage entfernt.
  • Gebühren für die interregionale Datenübertragung fallen an, wenn sich der Ziel-Bucket in einer anderen Region als der Quellcluster befindet. Weitere Informationen finden Sie unter AlloyDB for PostgreSQL – Preise.
  • Es können mehrere Exportvorgänge parallel ausgeführt werden.
  • Die Komprimierung ist aktiviert, wenn der Objektname auf die Erweiterung .gz endet. Das Objekt wird dann im .gz-Format nach Cloud Storage exportiert.
  • Für Zeichenwerte in CSV-Optionen wie field_delimiter, quote_character und escape_character sind nur ASCII-Zeichen im Hexadezimalcode (mit oder ohne Präfix 0x) zulässig.

Erforderliche Rollen und Berechtigungen für den Export aus AlloyDB

Damit Daten aus AlloyDB in Cloud Storage exportiert werden können, muss der Nutzer, der den Export initiiert, eine der folgenden IAM-Rollen (Identity and Access Management) haben:

Darüber hinaus muss das Dienstkonto für den AlloyDB-Cluster eine der folgenden Rollen haben:

  • storage.objectAdmin IAM-Rolle.
  • Eine benutzerdefinierte Rolle mit folgenden Berechtigungen:
    • storage.objects.create

Informationen zu IAM-Rollen finden Sie unter Identity and Access Management.

Daten in eine CSV-Datei exportieren

Während eines CSV-Exports können Sie die zu exportierenden Schemas angeben. Alle Schemas auf Datenbankebene können exportiert werden.

Zum Anpassen des CSV-Dateiformats können Sie die gcloud CLI oder die REST API verwenden.

gcloud

  1. Cloud Storage-Bucket erstellen

  2. Weisen Sie mit gcloud storage buckets add-iam-policy-binding dem AlloyDB-Dienstkonto für den Bucket die IAM-Rolle storage.objectAdmin zu. Das Format für das Dienstkonto sieht so aus:

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    Weitere Informationen zum Festlegen von IAM-Berechtigungen finden Sie unter IAM-Berechtigungen verwenden.

  3. Exportieren Sie die Datenbank in Ihren Cloud Storage-Bucket.

    Führen Sie den Befehl zum Exportieren der CSV-Datei aus: gcloud alloydb clusters export.

    In der folgenden Liste werden die Optionen für den Export von Daten im CSV-Format beschrieben:

    • --select-query (erforderlich): Die SELECT-Abfrage, die zum Extrahieren der Daten verwendet wird.
    • --async (optional): Sofort zurückkehren, ohne auf den Abschluss des laufenden Vorgangs zu warten.
    • --field-delimiter (optional): Gibt das Zeichen an, das die Spalten in jeder Zeile der Datei trennt. Der Standardwert ist ein Komma. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden.
    • --quote-character (optional): Gibt das Anführungszeichen an, das verwendet werden soll, wenn ein Datenwert in Anführungszeichen gesetzt wird. Der Standardwert ist ein doppeltes Anführungszeichen. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden.
    • --escape-character (optional): Gibt das Zeichen an, das vor einem Datenzeichen stehen muss, das maskiert werden soll. Der Standardwert ist mit --quote-character identisch. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden.

    Wenn Sie diese Funktionen verwenden möchten, fügen Sie diese Optionen in den gcloud CLI-Befehl ein.

    Andernfalls entfernen Sie diese Parameter aus dem folgenden Befehl:

    gcloud alloydb clusters export CLUSTER_NAME \
  --region=REGION \
  --database=DATABASE_NAME \
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME" \
  --select-query=SELECT_QUERY \
  --field-delimiter=FIELD_DELIMITER \
  --quote-character=QUOTE_CHARACTER \
  --escape-character=ESCAPE_CHARACTER \
  --csv

  4. Wenn Sie die zuvor festgelegte IAM-Rolle nicht beibehalten möchten, entfernen Sie sie jetzt.

REST Version 1

  1. Erstellen Sie einen Bucket für den Export:

    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME

  2. Weisen Sie mit gcloud storage buckets add-iam-policy-binding dem AlloyDB-Dienstkonto für den Bucket die IAM-Rolle storage.objectAdmin zu. Das Format für das Dienstkonto sieht so aus:

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    Weitere Informationen zum Festlegen von IAM-Berechtigungen finden Sie unter IAM-Berechtigungen verwenden.

  3. Exportieren Sie Ihre Datenbank.

    Verwenden Sie die folgende HTTP-Methode und URL:

    POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export

    Ersetzen Sie folgende Werte in den Anfragedaten:

    • PROJECT_ID: Projekt-ID.
    • REGION: die Region, in der der AlloyDB-Cluster bereitgestellt wird.
    • CLUSTER_ID: die Cluster-ID.
    • BUCKET_NAME: der Name des Cloud Storage-Buckets.
    • PATH_TO_CSV_FILE: der Pfad zur CSV-Datei.
    • DATABASE_NAME: Der Name einer Datenbank im AlloyDB-Cluster.

    • SELECT_QUERY: die SQL-Abfrage für den Export.

    • ESCAPE_CHARACTER (optional): das Zeichen, das vor einem Datenzeichen stehen muss, das maskiert werden soll. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. Beispiel: 22 steht für ein doppeltes Anführungszeichen.

    • QUOTE_CHARACTER (optional): das Zeichen, das Werte aus Spalten mit dem Datentyp „String“ umschließt. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. 22 steht beispielsweise für ein doppeltes Anführungszeichen.

    • FIELD_DELIMITER (optional): das Zeichen, das die Spaltenwerte aufteilt. Der Wert dieses Arguments muss als ein Zeichen im Hex-ASCII-Code angegeben werden. 2C steht beispielsweise für ein Komma.

    JSON-Text der Anfrage:

    {
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "ESCAPE_CHARACTER",
    "quote_character": "QUOTE_CHARACTER",
    "field_delimiter": "FIELD_DELIMITER"
  }
}

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl (Linux, macOS oder Cloud Shell)

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

       curl -X POST \
             -H "Authorization: Bearer $(gcloud auth print-access-token)" \
             -H "Content-Type: application/json; charset=utf-8" \
             -d @request.json \
             "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"

PowerShell (Windows)

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

Sie erhalten eine JSON-Antwort ähnlich wie diese:

Antwort

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }

Wenn Sie die zuvor festgelegten IAM-Berechtigungen nicht beibehalten möchten, entfernen Sie diese.

Die vollständige Liste der Parameter für die Anfrage finden Sie unter clusters.export.

Format einer CSV-Exportdatei anpassen

Zum Anpassen des CSV-Dateiformats können Sie die gcloud CLI oder die REST API verwenden. Wenn Sie einen Export ausführen, können Sie die folgenden Formatierungsoptionen festlegen:

CSV-Option Standardwert gcloud-Flag REST API-Attribut Beschreibung
Escape-Taste Der Standardwert entspricht dem Wert QUOTE. --escape-character escape_character Zeichen, das vor einem Datenzeichen stehen muss, das maskiert werden soll.
Angebot "22"
ASCII-Hexadezimalcode für doppelte Anführungszeichen.		 --quote-character quote_character Gibt das Anführungszeichen an, das verwendet werden soll, wenn ein Datenwert in Anführungszeichen gesetzt wird.
Feldtrennzeichen "2C"
ASCII-Hexadezimalcode für Komma.		 --field-delimiter field_delimiter Zeichen, das die Spaltenwerte aufteilt.

Verwenden Sie die folgenden gcloud CLI- und REST API-Beispiele, um das Dateiformat Ihrer CSV-Exportdatei anzupassen:

gcloud 

gcloud alloydb clusters export CLUSTER_NAME \
  --region=REGION \
  --database=DATABASE_NAME \
  --gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
  --select-query=SELECT_QUERY \
  --field-delimiter='2C' \
  --quote-character='22' \
  --escape-character='5C' \
  --csv

REST Version 1

Der entsprechende REST API-Anfragetext sieht in etwa so aus:

{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "5C",
    "quote_character": "22",
    "field_delimiter": "2C"
  }
}

Beim CSV-Export wird standardmäßig eine Standard-CSV-Ausgabe erstellt. Wenn Sie mehr Optionen benötigen, als AlloyDB bietet, können Sie die folgende Anweisung in einem psql-Client verwenden:

\copy TABLE_NAME TO 'CSV_FILE_NAME.csv' WITH
  (FORMAT csv, ESCAPE 'ESCAPE_CHARACTER', QUOTE 'QUOTE_CHARACTER',
  DELIMITER 'DELIMITER_CHARACTER', ENCODING 'UTF8', NULL 'NULL_MARKER_STRING');

Nächste Schritte