MCP Tools Reference: cloud-sql

Ferramenta: execute_sql

Execute qualquer instrução SQL válida, incluindo instruções de linguagem de definição de dados (DDL), linguagem de controle de dados (DCL), linguagem de consulta de dados (DQL) ou linguagem de manipulação de dados (DML), em uma instância do Cloud SQL.

Para oferecer suporte à ferramenta execute_sql, uma instância do Cloud SQL precisa atender aos seguintes requisitos:

  • O valor de data_api_access precisa ser definido como ALLOW_DATA_API.
  • Para usuários built_in, password_secret_version precisa ser definido.
  • Caso contrário, para usuários do IAM em uma instância do MySQL, a flag do banco de dados cloudsql_iam_authentication precisa ser definida como on. Para uma instância do PostgreSQL, a flag de banco de dados cloudsql.iam_authentication precisa ser definida como on.
  • Depois de usar a ferramenta create_instance para criar uma instância, use a ferramenta create_user para criar uma conta de usuário do IAM para o usuário conectado ao projeto.

A ferramenta execute_sql tem as seguintes limitações:

  • Se uma instrução SQL retornar uma resposta maior que 10 MB, ela será truncada.
  • A ferramenta execute_sql tem um tempo limite padrão de 30 segundos. Se uma consulta levar mais de 30 segundos, a ferramenta vai retornar um erro DEADLINE_EXCEEDED.
  • A ferramenta execute_sql não é compatível com o SQL Server.

Se você receber erros semelhantes a "A autenticação do IAM não está ativada para a instância", use a ferramenta get_instance para verificar o valor da flag de autenticação do banco de dados do IAM para a instância.

Se você receber erros como "A instância não permite o uso de executeSql para acessar esta instância", use a ferramenta get_instance para verificar a configuração data_api_access.

Quando você recebe erros de autenticação:

  1. Verifique se a conta de usuário conectada no momento existe como um usuário do IAM na instância usando a ferramenta list_users.
  2. Se a conta de usuário do IAM não existir, use a ferramenta create_user para criar a conta de usuário do IAM para o usuário conectado.
  3. Se o usuário conectado no momento não tiver as funções de usuário do banco de dados adequadas, use a ferramenta update_user para conceder funções de banco de dados ao usuário. Por exemplo, a função cloudsqlsuperuser pode fornecer a um usuário do IAM muitas permissões necessárias.

  4. Verifique se o usuário conectado no momento tem as permissões corretas do IAM atribuídas ao projeto. Use o comando gcloud projects get-iam-policy [PROJECT_ID] para verificar se o usuário tem as permissões ou os papéis do IAM adequados atribuídos ao projeto.

    • O usuário precisa ter a permissão cloudsql.instance.login para fazer a autenticação automática de banco de dados do IAM.
    • O usuário precisa ter a permissão cloudsql.instances.executeSql para executar instruções SQL usando a ferramenta execute_sql ou a API executeSql.
    • Papéis comuns do IAM que contêm as permissões necessárias: usuário da instância do Cloud SQL (roles/cloudsql.instanceUser) ou administrador do Cloud SQL (roles/cloudsql.admin)

Ao receber um ExecuteSqlResponse, sempre verifique os campos message e status no corpo da resposta. Um código de status HTTP bem-sucedido não garante o sucesso total de todas as instruções SQL. Os campos message e status indicam se houve erros ou avisos parciais durante a execução da instrução SQL.

O exemplo a seguir demonstra como usar curl para invocar a ferramenta execute_sql MCP.

Solicitação 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

Solicitação de execução de SQL da instância para MCP.

SqlInstancesExecuteSqlMcpRequest

Representação JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string,
  "user": string,
  "passwordSecretVersion": string
}
Campos
instance

string

Obrigatório. ID da instância do banco de dados. Isso não inclui o ID do projeto.
project

string

Obrigatório. ID do projeto com a instância.
sqlStatement

string

Obrigatório. Instruções SQL a serem executadas no banco de dados. Pode ser uma única instrução ou uma sequência de instruções separadas por ponto e vírgula.
database

string

Opcional. Nome do banco de dados em que a instrução será executada. É obrigatório para o Postgres e opcional para o MySQL. Para o Postgres, se a consulta não estiver no escopo de um banco de dados existente, como listar bancos de dados / criar um banco de dados / conceder funções, transmita o valor padrão como postgres.
user

string

Opcional. O nome de um usuário de banco de dados existente para se conectar ao banco de dados. Quando auto_iam_authn é definido como "true", esse campo é ignorado e o usuário do IAM do autor da chamada da API é usado.
passwordSecretVersion

string

Opcional. O nome do recurso do secret do Secret Manager que contém a senha para o usuário fazer login no banco de dados. O formato esperado é projects/{project}/secrets/{secret}/versions/{secret_version}. O nome do recurso secreto não será armazenado.

Esquema de saída

Resposta da execução de instruções SQL.

SqlInstancesExecuteSqlResponse

Representação JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Campos
messages[]

object (Message)

Uma lista de avisos e alertas gerados durante a execução da consulta. No PostgreSQL, isso inclui todos os avisos e alertas. No MySQL, isso inclui avisos gerados pela última instrução executada. Para recuperar todos os avisos de uma consulta de várias instruções, SHOW WARNINGS precisa ser executado após cada instrução.
metadata

object (Metadata)

As informações de metadados adicionais sobre a execução das instruções SQL.
results[]

object (QueryResult)

A lista de resultados após a execução de todas as instruções SQL.
status

object (Status)

Contém o erro do banco de dados se a execução do SQL falhar.

Mensagem

Representação 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ão _message.

_message pode ser apenas de um dos tipos a seguir:
message

string

A string de mensagem completa. Para o PostgreSQL, é uma string formatada que pode incluir gravidade, código e a mensagem de aviso/notificação. Para o MySQL, isso contém a mensagem de aviso.

Campo de união _severity.

_severity pode ser apenas de um dos tipos a seguir:
severity

string

A gravidade da mensagem (por exemplo, "NOTICE" para PostgreSQL, "WARNING" para MySQL).

Metadados

Representação JSON 
{
  "sqlStatementExecutionTime": string
}
Campos
sqlStatementExecutionTime

string (Duration format)

O tempo gasto para executar as instruções SQL.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

Duração

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Segundos assinados do período. Precisa estar entre -315.576.000.000 e +315.576.000.000 (inclusive). Observação: esses limites são calculados da seguinte forma: 60 s/min * 60 min/h * 24 h/dia * 365,25 dias/ano * 10.000 anos
nanos

integer

Frações assinadas de um segundo com resolução de nanossegundos do período. Durações menores que um segundo são representadas com um campo seconds 0 e um campo nanos positivo ou negativo. Para durações de um segundo ou mais, um valor diferente de zero para o campo nanos precisa ter o mesmo sinal do campo seconds. Precisa estar entre -999.999.999 e +999.999.999 (inclusive).

QueryResult

Representação JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Campos
columns[]

object (Column)

Lista de colunas incluídas no resultado. Isso também inclui o tipo de dados da coluna.
rows[]

object (Row)

Linhas retornadas pela instrução SQL.
message

string

Mensagem relacionada ao resultado da execução do SQL.
partialResult

boolean

Definido como "true" se o resultado da execução do SQL for truncado devido a limites de tamanho ou a um erro ao recuperar resultados.
status

object (Status)

Se os resultados foram truncados devido a um erro, detalhes desse erro.

Coluna

Representação JSON 
{
  "name": string,
  "type": string
}
Campos
name

string

Nome da coluna.
type

string

Tipo de dados da coluna.

Linha

Representação JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campos
values[]

object (Value)

Os valores da linha.

Valor

Representação JSON 
{
  "value": string,
  "nullValue": boolean
}
Campos
value

string

O valor da célula no formato de string.
nullValue

boolean

Se o valor da célula for nulo, essa flag será definida como "true".

Status

Representação JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

O código de status, que precisa ser um valor de enumeração de google.rpc.Code.
message

string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário precisa ser localizada e enviada no campo google.rpc.Status.details, ou localizada pelo cliente.
details[]

object

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Qualquer

Representação JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica o tipo da mensagem Protobuf serializada com uma referência de URI que consiste em um prefixo que termina em uma barra e o nome do tipo totalmente qualificado.

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

Essa string precisa conter pelo menos um caractere /, e o conteúdo após o último / precisa ser o nome totalmente qualificado do tipo na forma canônica, sem um ponto inicial. Não escreva um esquema nessas referências de URI para que os clientes não tentem entrar em contato com elas.

O prefixo é arbitrário, e as implementações do Protobuf devem remover tudo até o último /, inclusive, para identificar o tipo. type.googleapis.com/ é um prefixo padrão comum exigido por algumas implementações legadas. Esse prefixo não indica a origem do tipo, e não é esperado que URIs que o contenham respondam a solicitações.

Todas as strings de URL de tipo precisam ser referências de URI válidas com a restrição adicional (para o formato de texto) de que o conteúdo da referência deve consistir apenas em caracteres alfanuméricos, escapes codificados por porcentagem e caracteres no seguinte conjunto (sem incluir as crases externas): /-.~_!$&()*+,;=. Embora permitamos codificações de porcentagem, as implementações não devem remover o escape delas para evitar confusão com analisadores atuais. Por exemplo, type.googleapis.com%2FFoo deve ser rejeitado.

No design original do Any, foi considerada a possibilidade de iniciar um serviço de resolução de tipos nesses URLs de tipo, mas o Protobuf nunca implementou um e considera o contato com esses URLs problemático e um possível problema de segurança. Não tente usar URLs de tipo de contato.
value

string (bytes format)

Contém uma serialização Protobuf do tipo descrito por type_url.

Uma string codificada em base64.

Anotações de ferramentas

Dica destrutiva: ✅ | Dica idempotente: ❌ | Dica somente leitura: ❌ | Dica de mundo aberto: ❌