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.
  • Für integrierte Nutzer muss „password_secret_version“ festgelegt werden.
  • Andernfalls muss für IAM-Nutzer für eine MySQL-Instanz das Datenbank-Flag cloudsql_iam_authentication auf on festgelegt werden. Für eine PostgreSQL-Instanz muss das Datenbank-Flag cloudsql.iam_authentication auf on gesetzt sein.
  • 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 list_users-Tool, 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,
  "user": string,
  "passwordSecretVersion": 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.
user

string

Optional. Der Name eines vorhandenen Datenbanknutzers, mit dem eine Verbindung zur Datenbank hergestellt werden soll. Wenn auto_iam_authn auf „true“ gesetzt ist, wird dieses Feld ignoriert und der IAM-Nutzer des API-Aufrufers wird verwendet.
passwordSecretVersion

string

Optional. Der Ressourcenname des Secret Manager-Secrets, das das Passwort für den Nutzer enthält, mit dem er sich in der Datenbank anmelden kann. Das erwartete Format ist projects/{project}/secrets/{secret}/versions/{secret_version}. Der Secret-Ressourcenname wird nicht gespeichert.

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 Meldung, z.B. „NOTICE“ für PostgreSQL oder „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 aus folgenden Werten 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

Gibt den Typ der serialisierten Protobuf-Nachricht mit einem URI-Verweis an, der aus einem Präfix, das mit einem Schrägstrich endet, und dem vollständig qualifizierten Typnamen besteht.

Beispiel: type.googleapis.com/google.protobuf.StringValue

Dieser String muss mindestens ein /-Zeichen enthalten. Der Inhalt nach dem letzten / muss der vollständig qualifizierte Name des Typs in kanonischer Form ohne führenden Punkt sein. Schreiben Sie kein Schema in diese URI-Referenzen, damit Clients nicht versuchen, sie zu kontaktieren.

Das Präfix ist beliebig. Protobuf-Implementierungen entfernen einfach alles bis zum letzten / (einschließlich) und verwenden den Rest, um den Typ zu identifizieren. type.googleapis.com/ ist ein häufiges Standardpräfix, das für einige ältere Implementierungen erforderlich ist. Dieses Präfix gibt nicht den Ursprung des Typs an und URIs, die es enthalten, werden voraussichtlich nicht auf Anfragen reagieren.

Alle Typ-URL-Strings müssen gültige URI-Referenzen sein. Für das Textformat gilt die zusätzliche Einschränkung, dass der Inhalt der Referenz nur aus alphanumerischen Zeichen, prozentual codierten Escape-Sequenzen und Zeichen aus der folgenden Menge bestehen darf (ohne die äußeren Backticks): /-.~_!$&()*+,;=. Obwohl wir Prozentcodierungen zulassen, sollten Implementierungen sie nicht decodieren, um Verwechslungen mit vorhandenen Parsern zu vermeiden. Beispiel: type.googleapis.com%2FFoo sollte abgelehnt werden.

Im ursprünglichen Design von Any wurde die Möglichkeit in Betracht gezogen, einen Dienst zur Typauflösung unter diesen Typ-URLs zu starten. Protobuf hat jedoch nie einen solchen Dienst implementiert und betrachtet das Kontaktieren dieser URLs als problematisch und als potenzielles Sicherheitsproblem. Versuchen Sie nicht, URLs vom Typ „Kontakt“ aufzurufen.
value

string (bytes format)

Enthält eine Protobuf-Serialisierung des Typs, der durch „type_url“ beschrieben wird.

Ein base64-codierter String.

Tool-Annotationen

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