MCP Tools Reference: cloud-sql

Strumento: execute_sql

Esegui qualsiasi istruzione SQL valida, incluse istruzioni DDL (Data Definition Language), DCL (Data Control Language), DQL (Data Query Language) o DML (Data Manipulation Language), su un'istanza Cloud SQL.

Per supportare lo strumento execute_sql, un'istanza Cloud SQL deve soddisfare i seguenti requisiti:

  • Il valore di data_api_access deve essere impostato su ALLOW_DATA_API.
  • Per gli utenti integrati, deve essere impostata password_secret_version.
  • In caso contrario, per gli utenti IAM, per un'istanza MySQL, il flag di database cloudsql_iam_authentication deve essere impostato su on. Per un'istanza PostgreSQL, il flag di database cloudsql.iam_authentication deve essere impostato su on.
  • Dopo aver utilizzato lo strumento create_instance per creare un'istanza, puoi utilizzare lo strumento create_user per creare un account utente IAM per l'utente attualmente connesso al progetto.

Lo strumento execute_sql presenta le seguenti limitazioni:

  • Se un'istruzione SQL restituisce una risposta superiore a 10 MB, la risposta verrà troncata.
  • Lo strumento execute_sql ha un timeout predefinito di 30 secondi. Se una query viene eseguita per più di 30 secondi, lo strumento restituisce un errore DEADLINE_EXCEEDED.
  • Lo strumento execute_sql non è supportato per SQL Server.

Se ricevi errori simili a "L'autenticazione IAM non è abilitata per l'istanza", puoi utilizzare lo strumento get_instance per controllare il valore del flag di autenticazione database IAM per l'istanza.

Se ricevi errori come "L'istanza non consente l'utilizzo di executeSql per accedere a questa istanza", puoi utilizzare lo strumento get_instance per controllare l'impostazione data_api_access.

Quando ricevi errori di autenticazione:

  1. Controlla se l'account utente attualmente connesso esiste come utente IAM nell'istanza utilizzando lo strumento list_users.
  2. Se l'account utente IAM non esiste, utilizza lo strumento create_user per creare l'account utente IAM per l'utente che ha eseguito l'accesso.
  3. Se l'utente attualmente connesso non dispone dei ruoli utente del database appropriati, puoi utilizzare lo strumento update_user per concedere i ruoli del database all'utente. Ad esempio, il ruolo cloudsqlsuperuser può fornire a un utente IAM molte autorizzazioni richieste.

  4. Controlla se all'utente attualmente connesso sono assegnate le autorizzazioni IAM corrette per il progetto. Puoi utilizzare il comando gcloud projects get-iam-policy [PROJECT_ID] per verificare se all'utente sono assegnati i ruoli o le autorizzazioni IAM appropriati per il progetto.

    • L'utente deve disporre dell'autorizzazione cloudsql.instance.login per eseguire l'autenticazione IAM dei database automatica.
    • L'utente deve disporre dell'autorizzazione cloudsql.instances.executeSql per eseguire istruzioni SQL utilizzando lo strumento execute_sql o l'API executeSql.
    • Ruoli IAM comuni che contengono le autorizzazioni richieste: Utente istanza Cloud SQL (roles/cloudsql.instanceUser) o Amministratore Cloud SQL (roles/cloudsql.admin)

Quando ricevi un ExecuteSqlResponse, controlla sempre i campi message e status nel corpo della risposta. Un codice di stato HTTP riuscito non garantisce la riuscita completa di tutte le istruzioni SQL. I campi message e status indicheranno se si sono verificati errori o avvisi parziali durante l'esecuzione dell'istruzione SQL.

Il seguente esempio mostra come utilizzare curl per richiamare lo strumento MCP execute_sql.

Curl Request 
                  
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
}'

Schema di input

Richiesta di esecuzione SQL dell'istanza per MCP.

SqlInstancesExecuteSqlMcpRequest

Rappresentazione JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string,
  "user": string,
  "passwordSecretVersion": string
}
Campi
instance

string

Obbligatorio. ID istanza database. L'ID progetto non è incluso.
project

string

Obbligatorio. ID progetto del progetto che contiene l'istanza.
sqlStatement

string

Obbligatorio. Istruzioni SQL da eseguire sul database. Può trattarsi di una singola istruzione o di una sequenza di istruzioni separate da punti e virgola.
database

string

Facoltativo. Nome del database su cui verrà eseguita l'istruzione. Per Postgres è obbligatorio, per MySQL è facoltativo. Per Postgres, se la query non è limitata a un database esistente, ad esempio elenca database / crea nuovo database / concedi ruoli, puoi passare il valore predefinito come postgres.
user

string

Facoltativo. Il nome di un utente del database esistente per connettersi al database. Se auto_iam_authn è impostato su true, questo campo viene ignorato e viene utilizzato l'utente IAM del chiamante API.
passwordSecretVersion

string

Facoltativo. Il nome della risorsa del secret di Secret Manager contenente la password per l'accesso dell'utente al database. Il formato previsto è projects/{project}/secrets/{secret}/versions/{secret_version}. Il nome della risorsa secret non verrà archiviato.

Schema di output

Esegui la risposta delle istruzioni SQL.

SqlInstancesExecuteSqlResponse

Rappresentazione JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Campi
messages[]

object (Message)

Un elenco di avvisi e avvisi generati durante l'esecuzione della query. Per PostgreSQL, sono inclusi tutti gli avvisi e gli avvertimenti. Per MySQL, sono inclusi gli avvisi generati dall'ultima istruzione eseguita. Per recuperare tutti gli avvisi per una query con più istruzioni, SHOW WARNINGS deve essere eseguito dopo ogni istruzione.
metadata

object (Metadata)

Le informazioni aggiuntive sui metadati relative all'esecuzione delle istruzioni SQL.
results[]

object (QueryResult)

L'elenco dei risultati dopo l'esecuzione di tutte le istruzioni SQL.
status

object (Status)

Contiene l'errore del database se l'esecuzione SQL non è riuscita.

Messaggio

Rappresentazione 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.
}
Campi

Campo unione _message.

_message può essere solo uno dei seguenti tipi:
message

string

La stringa del messaggio completa. Per PostgreSQL, si tratta di una stringa formattata che può includere gravità, codice e il messaggio di avviso/notifica. Per MySQL, questo campo contiene il messaggio di avviso.

Campo unione _severity.

_severity può essere solo uno dei seguenti tipi:
severity

string

La gravità del messaggio (ad es. "NOTICE" per PostgreSQL, "WARNING" per MySQL).

Metadati

Rappresentazione JSON 
{
  "sqlStatementExecutionTime": string
}
Campi
sqlStatementExecutionTime

string (Duration format)

Il tempo impiegato per eseguire le istruzioni SQL.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

Durata

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Secondi firmati dell'intervallo di tempo. Deve essere compreso tra -315.576.000.000 e +315.576.000.000 inclusi. Nota: questi limiti vengono calcolati in base a: 60 sec/min * 60 min/ora * 24 ore/giorno * 365,25 giorni/anno * 10.000 anni
nanos

integer

Frazioni di secondo con segno con risoluzione di nanosecondi dell'intervallo di tempo. Le durate inferiori a un secondo sono rappresentate con un campo seconds pari a 0 e un campo nanos positivo o negativo. Per durate di un secondo o più, un valore diverso da zero per il campo nanos deve avere lo stesso segno del campo seconds. Deve essere compreso tra -999.999.999 e +999.999.999 inclusi.

QueryResult

Rappresentazione JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Campi
columns[]

object (Column)

Elenco delle colonne incluse nel risultato. È incluso anche il tipo di dati della colonna.
rows[]

object (Row)

Righe restituite dall'istruzione SQL.
message

string

Messaggio relativo al risultato dell'esecuzione SQL.
partialResult

boolean

Impostato su true se il risultato dell'esecuzione SQL viene troncato a causa dei limiti di dimensione o di un errore durante il recupero dei risultati.
status

object (Status)

Se i risultati sono stati troncati a causa di un errore, i dettagli dell'errore.

Colonna

Rappresentazione JSON 
{
  "name": string,
  "type": string
}
Campi
name

string

Nome della colonna.
type

string

Tipo di dati della colonna.

Riga

Rappresentazione JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campi
values[]

object (Value)

I valori per la riga.

Valore

Rappresentazione JSON 
{
  "value": string,
  "nullValue": boolean
}
Campi
value

string

Il valore della cella in formato stringa.
nullValue

boolean

Se il valore della cella è nullo, questo flag verrà impostato su true.

Stato

Rappresentazione JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campi
code

integer

Il codice di stato, che deve essere un valore enum di google.rpc.Code.
message

string

Un messaggio di errore rivolto agli sviluppatori, che deve essere in inglese. Qualsiasi messaggio di errore rivolto agli utenti deve essere localizzato e inviato nel campo google.rpc.Status.details o localizzato dal client.
details[]

object

Un elenco di messaggi contenenti i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.

Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo "@type" contenente un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.

Qualsiasi

Rappresentazione JSON 
{
  "typeUrl": string,
  "value": string
}
Campi
typeUrl

string

Identifica il tipo di messaggio Protobuf serializzato con un riferimento URI costituito da un prefisso che termina con una barra e il nome del tipo completo.

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

Questa stringa deve contenere almeno un carattere / e il contenuto dopo l'ultimo / deve essere il nome completo del tipo in forma canonica, senza un punto iniziale. Non scrivere uno schema su questi riferimenti URI in modo che i client non tentino di contattarli.

Il prefisso è arbitrario e le implementazioni di Protobuf devono semplicemente rimuovere tutto fino all'ultimo / incluso per identificare il tipo. type.googleapis.com/ è un prefisso predefinito comune richiesto da alcune implementazioni legacy. Questo prefisso non indica l'origine del tipo e non è previsto che gli URI che lo contengono rispondano a richieste.

Tutte le stringhe URL di tipo devono essere riferimenti URI validi con l'ulteriore limitazione (per il formato di testo) che il contenuto del riferimento deve essere costituito solo da caratteri alfanumerici, sequenze di escape codificate in percentuale e caratteri del seguente insieme (esclusi i backtick esterni): /-.~_!$&()*+,;=. Nonostante consentiamo le codifiche in percentuale, le implementazioni non devono eseguirne l'escape per evitare confusione con i parser esistenti. Ad esempio, type.googleapis.com%2FFoo deve essere rifiutato.

Nel design originale di Any, è stata presa in considerazione la possibilità di lanciare un servizio di risoluzione dei tipi in questi URL di tipo, ma Protobuf non ne ha mai implementato uno e considera il contatto con questi URL problematico e un potenziale problema di sicurezza. Non tentare di contattare gli URL di tipo.
value

string (bytes format)

Contiene una serializzazione Protobuf del tipo descritto da type_url.

Una stringa con codifica in base64.

Annotazioni dello strumento

Suggerimento distruttivo: ✅ | Suggerimento idempotente: ❌ | Suggerimento di sola lettura: ❌ | Suggerimento open world: ❌