MCP Tools Reference: cloud-sql

工具：execute_sql_readonly

在 Cloud SQL 執行個體上執行任何有效的唯讀 SQL 陳述式。

如要支援 execute_sql_readonly 工具，Cloud SQL 執行個體必須符合下列條件：

  • data_api_access 的值必須設為 ALLOW_DATA_API。
  • 如果是 MySQL 執行個體，資料庫旗標 cloudsql_iam_authentication 必須設為 on。如果是 PostgreSQL 執行個體，資料庫旗標 cloudsql.iam_authentication 必須設為 on。
  • 您必須使用 IAM 使用者帳戶或 IAM 服務帳戶 (CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT)，才能呼叫 execute_sql_readonly 工具。這項工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

使用 create_instance 工具建立執行個體後，您可以使用 create_user 工具，為目前登入專案的使用者建立 IAM 使用者帳戶。

execute_sql_readonly 工具具有下列限制：

  • 如果 SQL 陳述式傳回的回應大於 10 MB，系統就會截斷回應。
  • 這項工具的預設逾時時間為 30 秒。如果查詢執行時間超過 30 秒，工具會傳回 DEADLINE_EXCEEDED 錯誤。
  • 這項工具不支援 SQL Server。

如果收到類似「執行個體未啟用 IAM 驗證」的錯誤訊息，可以使用 get_instance 工具檢查執行個體的 IAM 資料庫驗證旗標值。

如果收到「The instance doesn't allow using executeSql to access this instance」等錯誤訊息，可以使用 get_instance 工具檢查 data_api_access 設定。

收到驗證錯誤訊息時：

  1. 使用 list_users 工具，檢查目前登入的使用者帳戶是否為執行個體上的 IAM 使用者。
  2. 如果 IAM 使用者帳戶不存在，請使用 create_user 工具為登入的使用者建立 IAM 使用者帳戶。
  3. 如果目前登入的使用者沒有適當的資料庫使用者角色，可以使用 update_user 工具授予使用者資料庫角色。舉例來說，cloudsqlsuperuser 角色可為 IAM 使用者提供許多必要權限。

  4. 檢查目前登入的使用者是否已獲派專案的正確 IAM 權限。您可以使用 gcloud projects get-iam-policy [PROJECT_ID] 指令，檢查使用者是否已獲派專案的適當 IAM 角色或權限。

    • 使用者必須具備 cloudsql.instance.login 權限，才能進行自動 IAM 資料庫驗證。
    • 使用者必須具備 cloudsql.instances.executeSql 權限，才能使用 execute_sql_readonly 工具或 executeSql API 執行 SQL 陳述式。
    • 包含必要權限的常見 IAM 角色：Cloud SQL 執行個體使用者 (roles/cloudsql.instanceUser) 或 Cloud SQL 管理員 (roles/cloudsql.admin)

收到 ExecuteSqlResponse 時，請務必檢查回覆主體中的 message 和 status 欄位。HTTP 狀態碼成功不代表所有 SQL 陳述式都完全成功。message 和 status 欄位會指出 SQL 陳述式執行期間是否有任何部分錯誤或警告。

以下範例示範如何使用 curl 叫用 execute_sql_readonly MCP 工具。

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_readonly",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

執行個體執行 MCP 的 SQL 要求。

SqlInstancesExecuteSqlMcpRequest

JSON 表示法 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string,
  "user": string,
  "passwordSecretVersion": string
}
欄位
instance

string

這是必要旗標，資料庫執行個體 ID。這不包括專案 ID。
project

string

這是必要旗標，包含執行個體的專案 ID。
sqlStatement

string

這是必要旗標，要在資料庫上執行的 SQL 陳述式。可以是單一陳述式，也可以是多個以半形分號分隔的陳述式。
database

string

選用。要執行陳述式的資料庫名稱。Postgres 必須提供，MySQL 則為選填。如果是 Postgres，如果查詢未限定現有資料庫 (例如列出資料庫 / 建立新資料庫 / 授予角色)，您可以傳遞預設值 (postgres)。
user

string

選用。用來連線至資料庫的現有資料庫使用者名稱。如果 auto_iam_authn 設為 true，系統會忽略這個欄位，並使用 API 呼叫者的 IAM 使用者。
passwordSecretVersion

string

選用。Secret Manager 密鑰的資源名稱，內含使用者登入資料庫的密碼。預期格式為 projects/{project}/secrets/{secret}/versions/{secret_version}。系統不會儲存密鑰資源名稱。

輸出內容的結構定義

執行 SQL 陳述式回應。

SqlInstancesExecuteSqlResponse

JSON 表示法 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
欄位
messages[]

object (Message)

查詢執行期間產生的通知和警告清單。如果是 PostgreSQL，這包括所有通知和警告。如果是 MySQL，這包括最後執行的陳述式產生的警告。如要擷取多重陳述式查詢的所有警告，必須在每個陳述式後執行 SHOW WARNINGS。
metadata

object (Metadata)

SQL 陳述式執行作業的其他中繼資料資訊。
results[]

object (QueryResult)

執行所有 SQL 陳述式後的結果清單。
status

object (Status)

如果 SQL 執行失敗，則包含資料庫中的錯誤。

訊息

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.
}
欄位

聯集欄位 _message。

_message 只能是下列其中一項：
message

string

完整訊息字串。如果是 PostgreSQL，這會是格式化字串，可能包含嚴重程度、程式碼和通知/警告訊息。如果是 MySQL，這會包含警告訊息。

聯集欄位 _severity。

_severity 只能是下列其中一項：
severity

string

訊息的嚴重程度 (例如 PostgreSQL 的「NOTICE」、MySQL 的「WARNING」)。

中繼資料

JSON 表示法 
{
  "sqlStatementExecutionTime": string
}
欄位
sqlStatementExecutionTime

string (Duration format)

執行 SQL 陳述式所花費的時間。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。

時間長度

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

時間範圍的秒數 (可為負值)。必須介於 -315,576,000,000 至 +315,576,000,000 之間 (含這兩個值)。注意：這些界限是根據以下計算得出：60 秒/分 * 60 分/時 * 24 時/天 * 365.25 天/年 * 10000 年
nanos

integer

時間跨度的小數部分 (以奈秒為單位)，可為正數或負數。如果時間長度不到一秒，系統會以 0 seconds 欄位和正數或負數 nanos 欄位表示。如果時間長度為一秒以上，nanos 欄位的非零值必須與 seconds 欄位相同。值必須介於 -999,999,999 到 +999,999,999 之間 (含)。

QueryResult

JSON 表示法 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
欄位
columns[]

object (Column)

結果中包含的資料欄清單。包括資料欄的資料類型。
rows[]

object (Row)

SQL 陳述式傳回的資料列。
message

string

與 SQL 執行結果相關的訊息。
partialResult

boolean

如果 SQL 執行結果因大小限制或擷取結果時發生錯誤而遭到截斷，請設為 true。
status

object (Status)

如果結果因發生錯誤而遭到截斷，則會顯示該錯誤的詳細資料。

欄

JSON 表示法 
{
  "name": string,
  "type": string
}
欄位
name

string

資料欄名稱。
type

string

資料欄的資料類型。

列

JSON 表示法 
{
  "values": [
    {
      object (Value)
    }
  ]
}
欄位
values[]

object (Value)

資料列的值。

值

JSON 表示法 
{
  "value": string,
  "nullValue": boolean
}
欄位
value

string

字串格式的儲存格值。
nullValue

boolean

如果儲存格值為空值，這個旗標就會設為 true。

狀態

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
欄位
code

integer

狀態碼，應為 google.rpc.Code 的列舉值。
message

string

向開發人員顯示的錯誤訊息，應以英文呈現。所有面向使用者的錯誤訊息都應經過本地化，並透過 google.rpc.Status.details 欄位傳送，或是由用戶端加以本地化。
details[]

object

包含錯誤詳細資料的訊息清單。這是供 API 使用的一組常用訊息類型。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

不限

JSON 表示法 
{
  "typeUrl": string,
  "value": string
}
欄位
typeUrl

string

以 URI 參照識別序列化 Protobuf 訊息的類型，該參照由以斜線結尾的前置字串和完整合格的類型名稱組成。

範例：type.googleapis.com/google.protobuf.StringValue

這個字串至少須包含一個 / 字元，且最後一個 / 後的內容必須是正規形式的類型完整名稱，且開頭不得有半形句號。請勿在這些 URI 參照中寫入配置，以免用戶端嘗試與其聯絡。

前置字元是任意的，Protobuf 實作項目應會直接去除最後一個 / 之前的所有內容，以識別類型。type.googleapis.com/ 是常見的預設前置字串，部分舊版實作方式需要使用這個前置字串。這個前置字串不會指出型別的來源，且含有這個前置字串的 URI 不會回應任何要求。

所有型別網址字串都必須是合法的 URI 參照，且參照內容只能包含英數字元、百分比編碼逸出字元，以及下列字元集中的字元 (不含外側的反引號)：/-.~_!$&()*+,;=。雖然我們允許百分比編碼，但實作時不應取消逸出，以免與現有剖析器混淆。舉例來說，type.googleapis.com%2FFoo 應遭拒絕。

在 Any 的原始設計中，我們曾考慮在這些類型網址啟動類型解析服務，但 Protobuf 從未實作這項服務，且認為聯絡這些網址有問題，可能造成安全性問題。請勿嘗試聯絡類型網址。
value

string (bytes format)

保存 type_url 所述類型的 Protobuf 序列化。

Base64 編碼字串。

工具註解

破壞性提示：❌ | 等冪提示：✅ | 唯讀提示：✅ | 開放世界提示：❌