SQL-Anweisungen mit der Cloud SQL Data API ausführen

Auf dieser Seite wird beschrieben, wie Sie SQL-Anweisungen für Datenbanken in Cloud SQL-Instanzen mit der Data API ausführen. Mit der Data API verwenden Sie die Cloud SQL Admin API und die gcloud CLI, um SQL-Anweisungen für jede Instanz auszuführen, für die Sie den Data API-Zugriff aktiviert haben.

Sie können die Data API mit Instanzen verwenden, die öffentliche IP-Adressen, den Zugriff auf private Dienste oder Private Service Connect verwenden. Die Data API unterstützt alle Arten von SQL-Anweisungen, einschließlich DML (Datenbearbeitungssprache), DDL (Datendefinitionssprache) und DQL (Data Query Language). Die Data API eignet sich gut für kleine und schnelle administrative Anweisungen, z. B. zum Erstellen von Datenbankrollen oder ‑nutzern und für kleine Schemaaktualisierungen. Sie können die Data API auch verwenden, um PostgreSQL-Erweiterungen zu aktivieren.

Hinweis

Bevor Sie SQL-Anweisungen für eine Instanz ausführen können, müssen Sie Folgendes tun:

Erforderliche Rollen oder Berechtigungen

Standardmäßig haben Nutzer oder Dienstkonten mit einer der folgenden Rollen die Berechtigung zum Ausführen von SQL-Anweisungen für eine Cloud SQL-Instanz (cloudsql.instances.executesql):

  • Cloud SQL Admin (roles/cloudsql.admin)
  • Cloud SQL Instance User (roles/cloudsql.instanceUser)
  • Cloud SQL Studio User (roles/cloudsql.studioUser)

Sie können auch eine benutzerdefinierte IAM-Rolle für das Nutzer- oder Dienstkonto definieren, die die Berechtigung cloudsql.instances.executesql enthält. Diese Berechtigung wird in benutzerdefinierten IAM-Rollen unterstützt.

Data API aktivieren oder deaktivieren

Wenn Sie die Data API verwenden möchten, müssen Sie sie für jede Instanz aktivieren. Sie können die Data API jederzeit deaktivieren.

gcloud

Verwenden Sie den Befehl gcloud sql instances patch mit dem Flag --data-api-access=ALLOW_DATA_API, um den Data API-Zugriff für eine Instanz zu aktivieren:

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

Verwenden Sie das Flag --data-api-access=DENY_DATA_API, um den Data API-Zugriff zu deaktivieren:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DENY_DATA_API

Ersetzen Sie INSTANCE_NAME durch den Namen der Instanz, für die Sie die Data API aktivieren oder deaktivieren möchten.

SQL-Anweisung ausführen

Sie können SQL-Anweisungen für Datenbanken in Ihrer Cloud SQL-Instanz entweder mit der gcloud CLI oder der REST API ausführen.

gcloud

Verwenden Sie den Befehl gcloud beta sql instances execute-sql, um eine SQL-Anweisung für eine Datenbank in einer Instanz mit der gcloud CLI auszuführen:

gcloud beta sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial_result_mode=PARTIAL_RESULT_MODE

Ersetzen Sie die folgenden Werte:

  • INSTANCE_NAME: der Name der Instanz.
  • DATABASE_NAME: Der Name der Datenbank in der Instanz.
  • SQL_STATEMENT: Die auszuführende SQL-Anweisung. Wenn die Anweisung Leerzeichen oder Shell-Sonderzeichen enthält, muss sie in Anführungszeichen gesetzt werden.
  • PARTIAL_RESULT_MODE: optional. Steuert, wie reagiert werden soll, wenn das Ergebnis unvollständig ist. Kann ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT oder PARTIAL_RESULT_MODE_UNSPECIFIED sein. Weitere Informationen finden Sie unter Kürzung anpassen.

Bei Bedarf können Sie auch das Flag --project=PROJECT_ID einfügen.

REST

Wenn Sie eine SQL-Anweisung für eine Datenbank in einer Instanz mithilfe der REST API ausführen möchten, senden Sie eine POST-Anfrage an den executeSql-Endpunkt:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

Der Anfragetext sollte den Datenbanknamen und die SQL-Anweisung enthalten:

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
}

Ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Ihre Projekt-ID.
  • INSTANCE_NAME: der Name der Instanz.
  • DATABASE_NAME: Der Name der Datenbank in der Instanz.
  • SQL_STATEMENT: Die auszuführende SQL-Anweisung.
  • PARTIAL_RESULT_MODE: optional. Steuert, wie die API reagiert, wenn das Ergebnis 10 MB überschreitet. Kann FAIL_PARTIAL_RESULT oder ALLOW_PARTIAL_RESULT sein. Weitere Informationen finden Sie unter Kürzung anpassen.

Abschneideverhalten ändern

Sie können festlegen, wie große Ergebnisse bei der Ausführung von SQL behandelt werden.

  • Fügen Sie das Feld "partialResultMode" in die Anfrage ein. Dieses Feld akzeptiert die folgenden Werte:
    • FAIL_PARTIAL_RESULT: Es wird ein Fehler ausgegeben, wenn das Ergebnis 10 MB überschreitet oder nur ein Teilergebnis abgerufen werden kann. Das Ergebnis nicht zurückgeben.
    • ALLOW_PARTIAL_RESULT: Gibt ein gekürztes Ergebnis zurück und setzt partial_result auf „true“, wenn das Ergebnis 10 MB überschreitet oder wenn aufgrund eines Fehlers nur ein Teilergebnis abgerufen werden kann. Keinen Fehler ausgeben.

Beschränkungen

  • Die Größenbeschränkung für eine Antwort beträgt 10 MB. Ergebnisse, die diese Größe überschreiten, werden gekürzt, wenn partialResultMode auf ALLOW_PARTIAL_RESULT gesetzt ist. Andernfalls wird ein Fehler ausgegeben.
  • Anfragen sind auf 0,5 MB beschränkt.
  • Sie können SQL-Anweisungen nur für Cloud SQL for PostgreSQL-Instanzen ausführen, die ausgeführt werden.
  • Cloud SQL unterstützt die Verwendung der Data API nicht für Instanzen, die für die Replikation auf externen Servern eingerichtet sind.
  • Anfragen, die länger als 30 Sekunden dauern, werden abgebrochen. Das Festlegen eines höheren Anweisungstimeouts mit SET STATEMENT_TIMEOUT wird nicht unterstützt.
  • In Cloud SQL ist die Anzahl der gleichzeitigen executeSql-Anfragen auf 10 pro Instanz und Nutzer begrenzt. Wenn dieses Limit erreicht wird, schlagen nachfolgende Anfragen mit der Meldung „Maximum concurrent reads 10 reached.“ fehl.
  • Jede Antwort kann maximal 10 Datenbankmeldungen oder ‑warnungen enthalten.
  • Bei einem Syntax- oder Ausführungsfehler wird kein Ergebnis zurückgegeben.
  • Anweisungen, die viel Arbeitsspeicher belegen, können zu Fehlern aufgrund von unzureichendem Arbeitsspeicher führen. Weitere Informationen zum Vermeiden dieser Fehler finden Sie unter Best Practices für die Verwaltung der Arbeitsspeichernutzung. Eine Datenbankinstanz, die mit hoher Arbeitsspeichernutzung ausgeführt wird, führt häufig zu Leistungsproblemen, Ausführungsunterbrechungen oder sogar Datenbankausfällen.