MCP Tools Reference: cloud-sql

Tool: execute_sql

Führen Sie beliebige gültige SQL-Anweisung für eine Cloud SQL-Instanz aus, einschließlich Anweisungen der Datendefinitionssprache (DDL), der Datenkontrollsprache (DCL), der Datenabfragesprache (DQL) oder der Datenbearbeitungssprache (DML).

Damit das execute_sql-Tool unterstützt wird, muss eine Cloud SQL-Instanz die folgenden Anforderungen erfüllen:

  • Der Wert von data_api_access muss auf ALLOW_DATA_API festgelegt werden.
  • Bei einer MySQL-Instanz muss das Datenbank-Flag cloudsql_iam_authentication auf on gesetzt sein. Für eine PostgreSQL-Instanz muss das Datenbank-Flag cloudsql.iam_authentication auf on gesetzt sein.
  • Für den Aufruf des execute_sql-Tools ist ein IAM-Nutzerkonto oder ein IAM-Dienstkonto (CLOUD_IAM_USER oder CLOUD_IAM_SERVICE_ACCOUNT) erforderlich. Das Tool führt die SQL-Anweisungen mit den Berechtigungen des Datenbanknutzers aus, der mit der IAM-Datenbankauthentifizierung angemeldet ist.

Nachdem Sie mit dem Tool create_instance eine Instanz erstellt haben, können Sie mit dem Tool create_user ein IAM-Nutzerkonto für den Nutzer erstellen, der derzeit im Projekt angemeldet ist.

Für das execute_sql-Tool gelten die folgenden Einschränkungen:

  • Wenn eine SQL-Anweisung eine Antwort zurückgibt, die größer als 10 MB ist, wird die Antwort abgeschnitten.
  • Das Tool execute_sql hat ein Standardzeitlimit von 30 Sekunden. Wenn eine Abfrage länger als 30 Sekunden dauert, gibt das Tool einen DEADLINE_EXCEEDED-Fehler zurück.
  • Das Tool execute_sql wird für SQL Server nicht unterstützt.

Wenn Sie Fehler wie „IAM-Authentifizierung ist für die Instanz nicht aktiviert“ erhalten, können Sie mit dem Tool get_instance den Wert des Flags für die IAM-Datenbankauthentifizierung für die Instanz prüfen.

Wenn Sie Fehler wie „Die Instanz erlaubt keinen Zugriff auf diese Instanz über executeSql“ erhalten, können Sie mit dem Tool get_instance die Einstellung data_api_access prüfen.

Wenn Sie Authentifizierungsfehler erhalten:

  1. Prüfen Sie mit dem Tool list_users, ob das aktuell angemeldete Nutzerkonto als IAM-Nutzer in der Instanz vorhanden ist.
  2. Wenn das IAM-Nutzerkonto nicht vorhanden ist, erstellen Sie es mit dem create_user-Tool für den angemeldeten Nutzer.
  3. Wenn der aktuell angemeldete Nutzer nicht die richtigen Datenbanknutzerrollen hat, können Sie ihm mit dem Tool update_user Datenbankrollen zuweisen. Mit der Rolle cloudsqlsuperuser kann einem IAM-Nutzer beispielsweise eine Vielzahl der erforderlichen Berechtigungen gewährt werden.

  4. Prüfen Sie, ob dem aktuell angemeldeten Nutzer die richtigen IAM-Berechtigungen für das Projekt zugewiesen sind. Mit dem Befehl gcloud projects get-iam-policy [PROJECT_ID] können Sie prüfen, ob dem Nutzer die richtigen IAM-Rollen oder -Berechtigungen für das Projekt zugewiesen sind.

    • Der Nutzer muss die Berechtigung cloudsql.instance.login haben, um die automatische IAM-Datenbankauthentifizierung durchzuführen.
    • Der Nutzer muss die Berechtigung cloudsql.instances.executeSql haben, um SQL-Anweisungen mit dem Tool execute_sql oder der API executeSql auszuführen.
    • Häufig verwendete IAM-Rollen, die die erforderlichen Berechtigungen enthalten: Cloud SQL-Instanznutzer (roles/cloudsql.instanceUser) oder Cloud SQL-Administrator (roles/cloudsql.admin)

Wenn Sie eine ExecuteSqlResponse erhalten, prüfen Sie immer die Felder message und status im Antworttext. Ein erfolgreicher HTTP-Statuscode bedeutet nicht, dass alle SQL-Anweisungen vollständig ausgeführt wurden. Die Felder message und status geben an, ob während der Ausführung der SQL-Anweisung teilweise Fehler oder Warnungen aufgetreten sind.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool execute_sql aufrufen.

Curl-Anfrage 
                  
curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

Instanz führt SQL-Anfrage für MCP aus.

SqlInstancesExecuteSqlMcpRequest

JSON-Darstellung 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
Felder
instance

string

Erforderlich. ID der Datenbankinstanz. Die Projekt-ID ist darin nicht enthalten.
project

string

Erforderlich. Projekt-ID des Projekts mit der Instanz.
sqlStatement

string

Erforderlich. SQL-Anweisungen, die für die Datenbank ausgeführt werden sollen. Es kann sich um eine einzelne Anweisung oder eine durch Semikolons getrennte Folge von Anweisungen handeln.
database

string

Optional. Name der Datenbank, für die die Anweisung ausgeführt wird. Für Postgres ist es erforderlich, für MySQL optional. Wenn Ihre Anfrage für Postgres nicht auf eine vorhandene Datenbank beschränkt ist, z. B. zum Auflisten von Datenbanken, Erstellen einer neuen Datenbank oder Zuweisen von Rollen, können Sie den Standardwert „postgres“ übergeben.

Ausgabeschema

Antwort auf die Ausführung von SQL-Anweisungen.

SqlInstancesExecuteSqlResponse

JSON-Darstellung 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Felder
messages[]

object (Message)

Eine Liste der Hinweise und Warnungen, die während der Ausführung der Abfrage generiert wurden. Für PostgreSQL umfasst dies alle Hinweise und Warnungen. Für MySQL umfasst dies Warnungen, die von der zuletzt ausgeführten Anweisung generiert wurden. Wenn Sie alle Warnungen für eine Abfrage mit mehreren Anweisungen abrufen möchten, muss SHOW WARNINGS nach jeder Anweisung ausgeführt werden.
metadata

object (Metadata)

Die zusätzlichen Metadaten zur Ausführung der SQL-Anweisungen.
results[]

object (QueryResult)

Die Liste der Ergebnisse nach Ausführung aller SQL-Anweisungen.
status

object (Status)

Enthält den Fehler aus der Datenbank, wenn die SQL-Ausführung fehlgeschlagen ist.

Nachricht

JSON-Darstellung 
{

  // Union field _message can be only one of the following:
  "message": string
  // End of list of possible types for union field _message.

  // Union field _severity can be only one of the following:
  "severity": string
  // End of list of possible types for union field _severity.
}
Felder

Union-Feld _message.

Für _message ist nur einer der folgenden Werte zulässig:
message

string

Der vollständige Nachrichtenstring. Für PostgreSQL ist dies ein formatierter String, der Schweregrad, Code und die Hinweis-/Warnmeldung enthalten kann. Für MySQL enthält dies die Warnmeldung.

Union-Feld _severity.

Für _severity ist nur einer der folgenden Werte zulässig:
severity

string

Der Schweregrad der Nachricht (z.B. „NOTICE“ für PostgreSQL, „WARNING“ für MySQL).

Metadaten

JSON-Darstellung 
{
  "sqlStatementExecutionTime": string
}
Felder
sqlStatementExecutionTime

string (Duration format)

Die Zeit, die für die Ausführung der SQL-Anweisungen benötigt wurde.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit „s“. Beispiel: "3.5s".

Dauer

JSON-Darstellung 
{
  "seconds": string,
  "nanos": integer
}
Felder
seconds

string (int64 format)

Signierte Sekunden des Zeitraums. Muss zwischen -315.576.000.000 und +315.576.000.000 (einschließlich) liegen. Hinweis: Diese Grenzen werden so berechnet: 60 Sek./Min. × 60 Min./Std. × 24 Std./Tag × 365,25 Tage/Jahr × 10.000 Jahre
nanos

integer

Signierte Sekundenbruchteile mit Nanosekunden-Auflösung für den Zeitraum. Dauern von weniger als einer Sekunde werden mit dem Feld „0“ seconds und einem positiven oder negativen Feld nanos dargestellt. Bei Zeiträumen von einer Sekunde oder mehr muss ein Wert ungleich null für das Feld nanos dasselbe Vorzeichen wie das Feld seconds haben. Muss zwischen -999.999.999 und +999.999.999 liegen (einschließlich).

QueryResult

JSON-Darstellung 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Felder
columns[]

object (Column)

Liste der Spalten, die im Ergebnis enthalten sind. Dazu gehört auch der Datentyp der Spalte.
rows[]

object (Row)

Von der SQL-Anweisung zurückgegebene Zeilen.
message

string

Meldung zum SQL-Ausführungsergebnis.
partialResult

boolean

Wird auf „true“ gesetzt, wenn das Ergebnis der SQL-Ausführung aufgrund von Größenbeschränkungen oder eines Fehlers beim Abrufen von Ergebnissen gekürzt wird.
status

object (Status)

Wenn die Ergebnisse aufgrund eines Fehlers gekürzt wurden, werden Details zu diesem Fehler angezeigt.

Spalte

JSON-Darstellung 
{
  "name": string,
  "type": string
}
Felder
name

string

Name der Spalte.
type

string

Datentyp der Spalte.

Zeile

JSON-Darstellung 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Felder
values[]

object (Value)

Die Werte für die Zeile.

Wert

JSON-Darstellung 
{
  "value": string,
  "nullValue": boolean
}
Felder
value

string

Der Zellenwert im Stringformat.
nullValue

boolean

Wenn der Zellwert null ist, wird dieses Flag auf „true“ gesetzt.

Status

JSON-Darstellung 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Felder
code

integer

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede für Nutzer sichtbare Fehlermeldung sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.
details[]

object

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die APIs verwenden können.

Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.

Beliebig

JSON-Darstellung 
{
  "typeUrl": string,
  "value": string
}
Felder
typeUrl

string

Eine URL/ein Ressourcenname, die den Typ der serialisierten Protokollzwischenspeicher-Nachricht eindeutig identifiziert. Dieser String muss mindestens ein „/“-Zeichen enthalten. Das letzte Segment des URL-Pfads muss den voll qualifizierten Namen des Typs enthalten (wie in path/google.protobuf.Duration). Der Name sollte in kanonischer Form vorliegen (z.B. ist ein führender „.“ nicht zulässig).

In der Praxis kompilieren Teams in der Regel alle Typen, die sie im Kontext von „Any“ verwenden möchten, vorab in das Binärprogramm. Für URLs, die das Schema http, https oder kein Schema verwenden, kann optional ein Typserver eingerichtet werden, der Typ-URLs wie folgt Nachrichtendefinitionen zuordnet:

  • Wenn kein Schema angegeben ist, wird https angenommen.
  • Ein HTTP GET für die URL muss einen google.protobuf.Type-Wert im Binärformat zurückgeben oder einen Fehler erzeugen.
  • Anwendungen dürfen Suchergebnisse basierend auf der URL im Cache speichern oder in ein Binärprogramm vorkompilieren, um Suchvorgänge zu vermeiden. Daher muss die binäre Kompatibilität bei Änderungen an Typen beibehalten werden. (Verwenden Sie versionierte Typnamen, um funktionsgefährdende Änderungen zu verwalten.)

Hinweis: Diese Funktion ist derzeit nicht in der offiziellen Protobuf-Version verfügbar und wird nicht für Typ-URLs verwendet, die mit „type.googleapis.com“ beginnen. Seit Mai 2023 gibt es keine weit verbreiteten Typ-Server-Implementierungen und es ist auch nicht geplant, eine zu implementieren.

Andere Schemas als http, https oder das leere Schema können mit implementierungsspezifischer Semantik verwendet werden.
value

string (bytes format)

Muss ein gültiger serialisierter Protokollpuffer des oben angegebenen Typs sein.

Ein base64-codierter String.

Tool-Annotationen

Destruktiver Hinweis: ✅ | Idempotenter Hinweis: ❌ | Nur-Lese-Hinweis: ❌ | Open-World-Hinweis: ❌