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 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.
  • Per chiamare lo strumento execute_sql è necessario un account utente IAM o un account di servizio IAM (CLOUD_IAM_USER o CLOUD_IAM_SERVICE_ACCOUNT). Lo strumento esegue le istruzioni SQL utilizzando i privilegi dell'utente del database che ha eseguito l'accesso con l'autenticazione IAM dei database.

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 sull'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
}
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.

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

Imposta il valore 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

Un URL/nome risorsa che identifica in modo univoco il tipo di messaggio del buffer del protocollo serializzato. Questa stringa deve contenere almeno un carattere "/". L'ultimo segmento del percorso dell'URL deve rappresentare il nome completo del tipo (come in path/google.protobuf.Duration). Il nome deve essere in forma canonica (ad esempio, il carattere "." iniziale non è accettato).

In pratica, i team precompilano nel binario tutti i tipi che prevedono di utilizzare nel contesto di Any. Tuttavia, per gli URL che utilizzano lo schema http, https o nessuno schema, è possibile configurare facoltativamente un server di tipi che mappa gli URL dei tipi alle definizioni dei messaggi nel seguente modo:

  • Se non viene fornito alcuno schema, viene utilizzato https.
  • Un HTTP GET sull'URL deve restituire un valore google.protobuf.Type in formato binario o produrre un errore.
  • Le applicazioni possono memorizzare nella cache i risultati di ricerca in base all'URL o precompilarli in un file binario per evitare qualsiasi ricerca. Pertanto, la compatibilità binaria deve essere mantenuta in caso di modifiche ai tipi. (Utilizza nomi di tipi con controllo delle versioni per gestire le modifiche che causano interruzioni.)

Nota: questa funzionalità non è attualmente disponibile nella release ufficiale di protobuf e non viene utilizzata per gli URL di tipo che iniziano con type.googleapis.com. A partire da maggio 2023, non esistono implementazioni di server di tipo ampiamente utilizzate e non sono previsti piani per implementarne una.

Gli schemi diversi da http, https (o lo schema vuoto) potrebbero essere utilizzati con una semantica specifica dell'implementazione.
value

string (bytes format)

Deve essere un buffer di protocollo serializzato valido del tipo specificato sopra.

Una stringa con codifica in base64.

Annotazioni dello strumento

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