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 uma instância do MySQL, a flag de 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.
  • Uma conta de usuário ou de serviço do IAM (CLOUD_IAM_USER ou CLOUD_IAM_SERVICE_ACCOUNT) é necessária para chamar a ferramenta execute_sql. A ferramenta executa as instruções SQL usando os privilégios do usuário do banco de dados conectado com a autenticação de banco de dados do IAM.

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 o MCP.

SqlInstancesExecuteSqlMcpRequest

Representação JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": 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.

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 com 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 e "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

Um URL/nome de recurso que identifica exclusivamente o tipo da mensagem serializada do buffer de protocolo. Essa string precisa conter pelo menos um caractere "/". O último segmento do caminho do URL precisa representar o nome totalmente qualificado do tipo (como em path/google.protobuf.Duration). O nome precisa estar em um formato canônico (por exemplo, "." no início não é aceito).

Na prática, as equipes geralmente pré-compilam no binário todos os tipos que esperam que ele use no contexto de Any. No entanto, para URLs que usam o esquema http, https ou nenhum esquema, é possível configurar um servidor de tipo que mapeia URLs de tipo para definições de mensagens da seguinte maneira:

  • Se nenhum esquema for fornecido, https será usado.
  • Um HTTP GET no URL precisa gerar um valor google.protobuf.Type em formato binário ou produzir um erro.
  • Os aplicativos podem armazenar em cache os resultados da pesquisa com base no URL ou pré-compilá-los em um binário para evitar qualquer pesquisa. Portanto, a compatibilidade binária precisa ser preservada em mudanças nos tipos. Use nomes de tipos com controle de versão para gerenciar mudanças incompatíveis.

Observação: no momento, essa funcionalidade não está disponível na versão oficial do protobuf e não é usada para URLs de tipo que começam com type.googleapis.com. Em maio de 2023, não havia implementações de servidor de tipo amplamente usadas nem planos para implementar uma.

Esquemas diferentes de http, https (ou o esquema vazio) podem ser usados com semântica específica da implementação.
value

string (bytes format)

Precisa ser um buffer de protocolo serializado válido do tipo especificado acima.

Uma string codificada em base64.

Anotações de ferramentas

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