MCP Tools Reference: cloud-sql

Herramienta: execute_sql

Ejecutar cualquier instrucción de SQL válida, incluidas las instrucciones del lenguaje de definición de datos (DDL), el lenguaje de control de datos (DCL), el lenguaje de consulta de datos (DQL) o el lenguaje de manipulación de datos (DML) en una instancia de Cloud SQL

Para admitir la herramienta execute_sql, una instancia de Cloud SQL debe cumplir con los siguientes requisitos:

  • El valor de data_api_access debe establecerse en ALLOW_DATA_API.
  • En el caso de una instancia de MySQL, la marca de base de datos cloudsql_iam_authentication debe establecerse en on. En el caso de una instancia de PostgreSQL, la marca de base de datos cloudsql.iam_authentication debe establecerse en on.
  • Se requiere una cuenta de usuario o una cuenta de servicio de IAM (CLOUD_IAM_USER o CLOUD_IAM_SERVICE_ACCOUNT) para llamar a la herramienta execute_sql. La herramienta ejecuta las sentencias SQL con los privilegios del usuario de la base de datos que accedió con la autenticación de la base de datos de IAM.

Después de usar la herramienta create_instance para crear una instancia, puedes usar la herramienta create_user para crear una cuenta de usuario de IAM para el usuario que actualmente accedió al proyecto.

La herramienta execute_sql tiene las siguientes limitaciones:

  • Si una instrucción de SQL devuelve una respuesta de más de 10 MB, la respuesta se truncará.
  • La herramienta execute_sql tiene un tiempo de espera predeterminado de 30 segundos. Si una consulta se ejecuta durante más de 30 segundos, la herramienta devuelve un error de DEADLINE_EXCEEDED.
  • La herramienta execute_sql no es compatible con SQL Server.

Si recibes errores similares a "La autenticación de IAM no está habilitada para la instancia", puedes usar la herramienta get_instance para verificar el valor de la marca de autenticación de la base de datos de IAM para la instancia.

Si recibes errores como "La instancia no permite usar executeSql para acceder a esta instancia", puedes usar la herramienta get_instance para verificar el parámetro de configuración data_api_access.

Cuando recibas errores de autenticación, haz lo siguiente:

  1. Verifica si la cuenta de usuario con la que se accedió actualmente existe como usuario de IAM en la instancia con la herramienta list_users.
  2. Si la cuenta de usuario de IAM no existe, usa la herramienta create_user para crearla para el usuario que accedió.
  3. Si el usuario que accedió actualmente no tiene los roles de usuario de la base de datos adecuados, puedes usar la herramienta update_user para otorgarle roles de base de datos. Por ejemplo, el rol cloudsqlsuperuser puede proporcionar a un usuario de IAM muchos permisos requeridos.

  4. Verifica si el usuario que accedió actualmente tiene los permisos de IAM correctos asignados para el proyecto. Puedes usar el comando gcloud projects get-iam-policy [PROJECT_ID] para verificar si el usuario tiene los roles o permisos de IAM adecuados asignados para el proyecto.

    • El usuario debe tener permiso cloudsql.instance.login para realizar la autenticación automática de la base de datos de IAM.
    • El usuario debe tener permiso cloudsql.instances.executeSql para ejecutar instrucciones SQL con la herramienta execute_sql o la API de executeSql.
    • Roles de IAM comunes que contienen los permisos requeridos: Usuario de instancia de Cloud SQL (roles/cloudsql.instanceUser) o Administrador de Cloud SQL (roles/cloudsql.admin)

Cuando recibas un ExecuteSqlResponse, siempre verifica los campos message y status dentro del cuerpo de la respuesta. Un código de estado HTTP correcto no garantiza el éxito total de todas las sentencias SQL. Los campos message y status indicarán si hubo errores o advertencias parciales durante la ejecución de la instrucción de SQL.

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta de MCP execute_sql.

Solicitud de 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
}'

Esquema de entrada

Es una solicitud de ejecución de SQL de instancia para MCP.

SqlInstancesExecuteSqlMcpRequest

Representación JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string
}
Campos
instance

string

Obligatorio. El ID de instancia de la base de datos. Esto no incluye el ID del proyecto.
project

string

Obligatorio. El ID del proyecto que contiene la instancia.
sqlStatement

string

Obligatorio. Son las instrucciones de SQL que se ejecutarán en la base de datos. Puede ser una sola instrucción o una secuencia de instrucciones separadas por punto y coma.
database

string

Es opcional. Nombre de la base de datos en la que se ejecutará la instrucción. Es obligatorio para Postgres y opcional para MySQL. En el caso de Postgres, si tu consulta no se limita a una base de datos existente, como enumerar bases de datos, crear una base de datos nueva o otorgar roles, puedes pasar el valor predeterminado como postgres.

Esquema de salida

Es la respuesta de la ejecución de instrucciones de SQL.

SqlInstancesExecuteSqlResponse

Representación JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Campos
messages[]

object (Message)

Es una lista de avisos y advertencias generados durante la ejecución de la consulta. En el caso de PostgreSQL, esto incluye todos los avisos y advertencias. En el caso de MySQL, esto incluye las advertencias generadas por la última instrucción ejecutada. Para recuperar todas las advertencias de una consulta de varias instrucciones, se debe ejecutar SHOW WARNINGS después de cada instrucción.
metadata

object (Metadata)

Es la información de metadatos adicional sobre la ejecución de las sentencias SQL.
results[]

object (QueryResult)

Es la lista de resultados después de ejecutar todas las instrucciones SQL.
status

object (Status)

Contiene el error de la base de datos si falló la ejecución de SQL.

Mensaje

Representación 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.
}
Campos

Campo de unión _message.

_message puede ser una de las siguientes opciones:
message

string

Es la cadena de mensaje completa. En el caso de PostgreSQL, se trata de una cadena con formato que puede incluir la gravedad, el código y el mensaje de aviso o advertencia. En el caso de MySQL, contiene el mensaje de advertencia.

Campo de unión _severity.

_severity puede ser una de las siguientes opciones:
severity

string

Es la gravedad del mensaje (p.ej., "NOTICE" para PostgreSQL y "WARNING" para MySQL

Metadatos

Representación JSON 
{
  "sqlStatementExecutionTime": string
}
Campos
sqlStatementExecutionTime

string (Duration format)

Es el tiempo que se tarda en ejecutar las instrucciones de SQL.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

Duración

Representación JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Son los segundos firmados del período. Debe estar entre -315,576,000,000 y +315,576,000,000, inclusive. Nota: Estos límites se calculan de la siguiente manera: 60 s/min * 60 min/h * 24 h/día * 365.25 días/año * 10,000 años.
nanos

integer

Fracciones firmadas de un segundo con una resolución de nanosegundos del período. Las duraciones inferiores a un segundo se representan con un campo seconds igual a 0 y un campo nanos positivo o negativo. Para duraciones de un segundo o más, un valor distinto de cero para el campo nanos debe tener el mismo signo que el campo seconds. Debe ser un valor entre -999,999,999 y +999,999,999, inclusive.

QueryResult

Representación JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Campos
columns[]

object (Column)

Es la lista de columnas incluidas en el resultado. Esto también incluye el tipo de datos de la columna.
rows[]

object (Row)

Son las filas que devuelve la instrucción de SQL.
message

string

Es un mensaje relacionado con el resultado de la ejecución de SQL.
partialResult

boolean

Se establece en verdadero si el resultado de la ejecución de SQL se trunca debido a límites de tamaño o a un error al recuperar los resultados.
status

object (Status)

Son los detalles del error si los resultados se truncaron debido a un error.

Columna

Representación JSON 
{
  "name": string,
  "type": string
}
Campos
name

string

Nombre de la columna.
type

string

Es el tipo de datos de la columna.

Fila

Representación JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campos
values[]

object (Value)

Son los valores de la fila.

Valor

Representación JSON 
{
  "value": string,
  "nullValue": boolean
}
Campos
value

string

Es el valor de la celda en formato de cadena.
nullValue

boolean

Si el valor de la celda es nulo, esta marca se establecerá en verdadero.

Estado

Representación JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

El código de estado, que debe ser un valor enum de google.rpc.Code.
message

string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.
details[]

object

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.

Un objeto que contiene campos de un tipo arbitrario. Un campo adicional "@type" contiene una URI que identifica el tipo. Ejemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Cualquiera

Representación JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Es una URL o un nombre de recurso que identifica de forma única el tipo de mensaje del búfer de protocolo serializado. Esta cadena debe contener al menos un carácter "/". El último segmento de la ruta de acceso de la URL debe representar el nombre completamente calificado del tipo (como en path/google.protobuf.Duration). El nombre debe estar en formato canónico (p.ej., no se acepta el "." inicial).

En la práctica, los equipos suelen precompilar en el archivo binario todos los tipos que esperan que se usen en el contexto de Any. Sin embargo, para las URLs que usan el esquema http, https o ningún esquema, se puede configurar de forma opcional un servidor de tipos que asigne URLs de tipos a definiciones de mensajes de la siguiente manera:

  • Si no se proporciona un esquema, se supone que es https.
  • Una solicitud HTTP GET en la URL debe producir un valor google.protobuf.Type en formato binario o generar un error.
  • Las aplicaciones pueden almacenar en caché los resultados de la búsqueda según la URL o precompilarlos en un archivo binario para evitar cualquier búsqueda. Por lo tanto, la compatibilidad binaria debe conservarse en los cambios de tipos. (Usa nombres de tipos con versiones para administrar los cambios que generan interrupciones).

Nota: Actualmente, esta funcionalidad no está disponible en la versión oficial de Protobuf y no se usa para las URLs de tipo que comienzan con type.googleapis.com. A partir de mayo de 2023, no hay implementaciones de servidores de tipos ampliamente utilizadas ni planes para implementar una.

Se pueden usar esquemas distintos de http, https (o el esquema vacío) con una semántica específica de la implementación.
value

string (bytes format)

Debe ser un búfer de protocolo serializado válido del tipo especificado anteriormente.

Es una cadena codificada en Base64.

Anotaciones de herramientas

Sugerencia destructiva: ✅ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ❌ | Sugerencia de mundo abierto: ❌