MCP Tools Reference: cloud-sql

Outil : execute_sql

Exécutez n'importe quelle instruction SQL valide, y compris les instructions de langage de définition de données (LDD), de langage de contrôle de données (LCD), de langage de requête de données (LRD) ou de langage de manipulation de données (LMD), sur une instance Cloud SQL.

Pour que l'outil execute_sql soit compatible, une instance Cloud SQL doit répondre aux exigences suivantes :

  • La valeur de data_api_access doit être définie sur ALLOW_DATA_API.
  • Pour une instance MySQL, l'option de base de données cloudsql_iam_authentication doit être définie sur on. Pour une instance PostgreSQL, l'option de base de données cloudsql.iam_authentication doit être définie sur on.
  • Un compte utilisateur IAM ou un compte de service IAM (CLOUD_IAM_USER ou CLOUD_IAM_SERVICE_ACCOUNT) est requis pour appeler l'outil execute_sql. L'outil exécute les instructions SQL à l'aide des droits d'accès de l'utilisateur de base de données connecté avec l'authentification IAM pour les bases de données.

Après avoir utilisé l'outil create_instance pour créer une instance, vous pouvez utiliser l'outil create_user pour créer un compte utilisateur IAM pour l'utilisateur actuellement connecté au projet.

L'outil execute_sql présente les limites suivantes :

  • Si une instruction SQL renvoie une réponse de plus de 10 Mo, elle sera tronquée.
  • L'outil execute_sql a un délai avant expiration par défaut de 30 secondes. Si une requête s'exécute pendant plus de 30 secondes, l'outil renvoie une erreur DEADLINE_EXCEEDED.
  • L'outil execute_sql n'est pas compatible avec SQL Server.

Si vous recevez des erreurs semblables à "L'authentification IAM n'est pas activée pour l'instance", vous pouvez utiliser l'outil get_instance pour vérifier la valeur du flag d'authentification IAM pour les bases de données de l'instance.

Si vous recevez des erreurs telles que "L'instance n'autorise pas l'utilisation d'executeSql pour accéder à cette instance", vous pouvez utiliser l'outil get_instance pour vérifier le paramètre data_api_access.

Lorsque vous recevez des erreurs d'authentification :

  1. Vérifiez si le compte utilisateur actuellement connecté existe en tant qu'utilisateur IAM sur l'instance à l'aide de l'outil list_users.
  2. Si le compte utilisateur IAM n'existe pas, utilisez l'outil create_user pour créer le compte utilisateur IAM pour l'utilisateur connecté.
  3. Si l'utilisateur actuellement connecté ne dispose pas des rôles d'utilisateur de base de données appropriés, vous pouvez utiliser l'outil update_user pour lui accorder ces rôles. Par exemple, le rôle cloudsqlsuperuser peut fournir à un utilisateur IAM de nombreuses autorisations requises.

  4. Vérifiez si l'utilisateur actuellement connecté dispose des autorisations IAM appropriées pour le projet. Vous pouvez utiliser la commande gcloud projects get-iam-policy [PROJECT_ID] pour vérifier si les rôles ou autorisations IAM appropriés sont attribués à l'utilisateur pour le projet.

    • L'utilisateur doit disposer de l'autorisation cloudsql.instance.login pour effectuer l'authentification IAM automatique pour les bases de données.
    • L'utilisateur doit disposer de l'autorisation cloudsql.instances.executeSql pour exécuter des instructions SQL à l'aide de l'outil execute_sql ou de l'API executeSql.
    • Rôles IAM courants contenant les autorisations requises : utilisateur d'instance Cloud SQL (roles/cloudsql.instanceUser) ou administrateur Cloud SQL (roles/cloudsql.admin)

Lorsque vous recevez un ExecuteSqlResponse, vérifiez toujours les champs message et status dans le corps de la réponse. Un code d'état HTTP réussi ne garantit pas le succès complet de toutes les instructions SQL. Les champs message et status indiquent si des erreurs ou des avertissements partiels se sont produits lors de l'exécution de l'instruction SQL.

L'exemple suivant montre comment utiliser curl pour appeler l'outil MCP execute_sql.

Requête curl 
                  
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
}'

Schéma d'entrée

Requête SQL d'exécution d'instance pour MCP.

SqlInstancesExecuteSqlMcpRequest

Représentation JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
Champs
instance

string

Obligatoire. ID de l'instance de base de données. Ce paramètre n'inclut pas l'ID du projet.
project

string

Obligatoire. ID du projet contenant l'instance.
sqlStatement

string

Obligatoire. Instructions SQL à exécuter sur la base de données. Il peut s'agir d'une seule instruction ou d'une séquence d'instructions séparées par des points-virgules.
database

string

Facultatif. Nom de la base de données sur laquelle l'instruction sera exécutée. Elle est obligatoire pour Postgres et facultative pour MySQL. Pour Postgres, si votre requête n'est pas limitée à une base de données existante (par exemple, lister les bases de données, créer une base de données ou accorder des rôles), vous pouvez transmettre la valeur par défaut "postgres".

Schéma de sortie

Réponse à l'exécution d'instructions SQL.

SqlInstancesExecuteSqlResponse

Représentation JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Champs
messages[]

object (Message)

Liste des notifications et des avertissements générés lors de l'exécution de la requête. Pour PostgreSQL, cela inclut tous les avis et avertissements. Pour MySQL, cela inclut les avertissements générés par la dernière instruction exécutée. Pour récupérer tous les avertissements d'une requête à plusieurs instructions, SHOW WARNINGS doit être exécuté après chaque instruction.
metadata

object (Metadata)

Informations de métadonnées supplémentaires concernant l'exécution des instructions SQL.
results[]

object (QueryResult)

Liste des résultats après l'exécution de toutes les instructions SQL.
status

object (Status)

Contient l'erreur de la base de données si l'exécution SQL a échoué.

Message

Représentation JSON 
{

  // 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.
}
Champs

Champ d'union _message.

_message ne peut être qu'un des éléments suivants :
message

string

Chaîne de message complète. Pour PostgreSQL, il s'agit d'une chaîne mise en forme qui peut inclure la gravité, le code et le message d'avertissement ou d'information. Pour MySQL, ce champ contient le message d'avertissement.

Champ d'union _severity.

_severity ne peut être qu'un des éléments suivants :
severity

string

Gravité du message (par exemple, "NOTICE" pour PostgreSQL, "WARNING" pour MySQL).

Métadonnées

Représentation JSON 
{
  "sqlStatementExecutionTime": string
}
Champs
sqlStatementExecutionTime

string (Duration format)

Temps nécessaire à l'exécution des instructions SQL.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

Durée

Représentation JSON 
{
  "seconds": string,
  "nanos": integer
}
Champs
seconds

string (int64 format)

Secondes signées de la durée. La valeur doit être comprise entre -315 576 000 000 et +315 576 000 000 (inclus). Remarque : Ces limites sont calculées à partir de : 60 s/min * 60 min/h * 24 h/jour * 365,25 jours/an * 10 000 ans
nanos

integer

Fractions de secondes signées avec une précision de l'ordre de la nanoseconde pour la durée. Les durées inférieures à une seconde sont représentées par un champ seconds égal à 0 et un champ nanos positif ou négatif. Pour les durées d'une seconde ou plus, une valeur non nulle pour le champ nanos doit avoir le même signe que le champ seconds. La valeur doit être comprise entre -999 999 999 et +999 999 999 inclus.

QueryResult

Représentation JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Champs
columns[]

object (Column)

Liste des colonnes incluses dans le résultat. Cela inclut également le type de données de la colonne.
rows[]

object (Row)

Lignes renvoyées par l'instruction SQL.
message

string

Message lié au résultat de l'exécution SQL.
partialResult

boolean

Définissez sur "true" si le résultat de l'exécution SQL est tronqué en raison de limites de taille ou d'une erreur lors de la récupération des résultats.
status

object (Status)

Détails de l'erreur si les résultats ont été tronqués en raison d'une erreur.

Colonne

Représentation JSON 
{
  "name": string,
  "type": string
}
Champs
name

string

Nom de la colonne.
type

string

Type de données de la colonne.

Ligne

Représentation JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Champs
values[]

object (Value)

Valeurs de la ligne.

Valeur

Représentation JSON 
{
  "value": string,
  "nullValue": boolean
}
Champs
value

string

Valeur de la cellule au format chaîne.
nullValue

boolean

Si la valeur de la cellule est nulle, cet indicateur est défini sur "true".

État

Représentation JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Champs
code

integer

Code d'état, qui doit être une valeur d'énumération de google.rpc.Code.
message

string

Message d'erreur destiné au développeur, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs doit être localisé et envoyé dans le champ google.rpc.Status.details, ou localisé par le client.
details[]

object

Liste de messages comportant les détails de l'erreur. Il existe un ensemble commun de types de message utilisable par les API.

Objet contenant des champs d'un type arbitraire. Un champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

Tous

Représentation JSON 
{
  "typeUrl": string,
  "value": string
}
Champs
typeUrl

string

URL/nom de ressource qui identifie de manière unique le type du message de tampon de protocole sérialisé. Cette chaîne doit contenir au moins un caractère "/". Le dernier segment du chemin d'URL doit représenter le nom complet du type (comme dans path/google.protobuf.Duration). Le nom doit être au format canonique (par exemple, un "." en début de nom n'est pas accepté).

En pratique, les équipes précompilent généralement dans le binaire tous les types qu'elles prévoient d'utiliser dans le contexte de "Any". Toutefois, pour les URL qui utilisent le schéma http, https ou aucun schéma, il est possible de configurer un serveur de type qui mappe les URL de type aux définitions de message comme suit :

  • Si aucun schéma n'est fourni, https est utilisé.
  • Une requête HTTP GET sur l'URL doit générer une valeur google.protobuf.Type au format binaire ou produire une erreur.
  • Les applications sont autorisées à mettre en cache les résultats de recherche en fonction de l'URL ou à les précompiler dans un fichier binaire pour éviter toute recherche. Par conséquent, la compatibilité binaire doit être préservée lors des modifications apportées aux types. (Utilisez des noms de types versionnés pour gérer les modifications destructives.)

Remarque : Cette fonctionnalité n'est actuellement pas disponible dans la version officielle de Protobuf et n'est pas utilisée pour les URL de type commençant par type.googleapis.com. En mai 2023, il n'existe aucune implémentation de serveur de type largement utilisée et aucune n'est prévue.

Des schémas autres que http, https (ou le schéma vide) peuvent être utilisés avec des sémantiques spécifiques à l'implémentation.
value

string (bytes format)

Doit être un tampon de protocole sérialisé valide du type spécifié ci-dessus.

Chaîne encodée en base64.

Annotations d'outils

Indication de destruction : ✅ | Indication d'idempotence : ❌ | Indication de lecture seule : ❌ | Indication de monde ouvert : ❌