MCP Tools Reference: cloud-sql

Outil : execute_sql_readonly

Exécutez n'importe quelle instruction SQL en lecture seule valide sur une instance Cloud SQL.

Pour que l'outil execute_sql_readonly 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_readonly. 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_readonly présente les limites suivantes :

  • Si une instruction SQL renvoie une réponse de plus de 10 Mo, elle sera tronquée.
  • L'outil a un délai avant expiration de 30 secondes par défaut. Si une requête s'exécute pendant plus de 30 secondes, l'outil renvoie une erreur DEADLINE_EXCEEDED.
  • L'outil 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_readonly 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_readonly.

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_readonly",
    "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,
  "user": string,
  "passwordSecretVersion": 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".
user

string

Facultatif. Nom d'un utilisateur de base de données existant pour se connecter à la base de données. Lorsque auto_iam_authn est défini sur "true", ce champ est ignoré et l'utilisateur IAM de l'appelant de l'API est utilisé.
passwordSecretVersion

string

Facultatif. Nom de ressource du secret Secret Manager contenant le mot de passe permettant à l'utilisateur de se connecter à la base de données. Le format attendu est projects/{project}/secrets/{secret}/versions/{secret_version}. Le nom de la ressource de secret ne sera pas stocké.

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 ou "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

Identifie le type du message Protobuf sérialisé avec une référence URI composée d'un préfixe se terminant par une barre oblique et du nom de type complet.

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

Cette chaîne doit contenir au moins un caractère /. Le contenu après le dernier / doit être le nom complet du type sous forme canonique, sans point au début. N'écrivez pas de schéma sur ces références URI afin que les clients ne tentent pas de les contacter.

Le préfixe est arbitraire et les implémentations Protobuf sont censées supprimer tout ce qui précède le dernier / (inclus) pour identifier le type. type.googleapis.com/ est un préfixe par défaut courant que certaines anciennes implémentations requièrent. Ce préfixe n'indique pas l'origine du type, et les URI qui le contiennent ne sont pas censés répondre aux requêtes.

Toutes les chaînes d'URL de type doivent être des références URI légales avec la restriction supplémentaire (pour le format texte) que le contenu de la référence ne doit être composé que de caractères alphanumériques, d'échappements encodés en pourcentage et de caractères de l'ensemble suivant (sans les accents graves extérieurs) : /-.~_!$&()*+,;=. Bien que nous autorisions les encodages en pourcentage, les implémentations ne doivent pas les décoder pour éviter toute confusion avec les analyseurs existants. Par exemple, type.googleapis.com%2FFoo doit être rejeté.

Dans la conception d'origine de Any, la possibilité de lancer un service de résolution de type à ces URL de type a été envisagée, mais Protobuf n'en a jamais implémenté et considère que contacter ces URL est problématique et constitue un risque potentiel pour la sécurité. N'essayez pas de contacter les URL de type.
value

string (bytes format)

Contient une sérialisation Protobuf du type décrit par type_url.

Chaîne encodée en base64.

Annotations d'outils

Indication destructive : ❌ | Indication idempotente : ✅ | Indication en lecture seule : ✅ | Indication Open World : ❌