MCP Tools Reference: cloud-sql

工具：execute_sql

在 Cloud SQL 執行個體上執行任何有效的 SQL 陳述式，包括資料定義語言 (DDL)、資料控制語言 (DCL)、資料查詢語言 (DQL) 或資料操縱語言 (DML) 陳述式。

如要支援 execute_sql 工具，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 工具。這項工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

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

execute_sql 工具具有下列限制：

• 如果 SQL 陳述式傳回的回應大於 10 MB，系統就會截斷回應。
• execute_sql 工具的預設逾時時間為 30 秒。如果查詢執行時間超過 30 秒，工具會傳回 DEADLINE_EXCEEDED 錯誤。
• execute_sql 工具不支援 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 工具或 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 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", "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 }

欄位
instance	string 這是必要旗標，資料庫執行個體 ID。這不包括專案 ID。
project	string 這是必要旗標，包含執行個體的專案 ID。
sqlStatement	string 這是必要旗標，要在資料庫上執行的 SQL 陳述式。可以是單一陳述式，也可以是多個以半形分號分隔的陳述式。
database	string 選用。要執行陳述式的資料庫名稱。Postgres 必須提供，MySQL 則為選填。如果是 Postgres，如果查詢未限定於現有資料庫 (例如列出資料庫 / 建立新資料庫 / 授予角色)，您可以傳遞預設值 (postgres)。

輸出內容的結構定義

執行 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 可唯一識別序列化通訊協定緩衝區訊息類型的網址/資源名稱。這個字串必須包含至少一個「/」字元。網址路徑的最後一個區段必須代表類型的完整名稱 (如 path/google.protobuf.Duration)。名稱應採用標準形式 (例如不接受開頭為「.」)。 實際上，團隊通常會將預期在 Any 內容中使用的所有型別預先編譯為二進位檔。不過，對於使用 http、https 配置或沒有配置的網址，您可以選擇設定類型伺服器，將類型網址對應至訊息定義，如下所示： 如未提供架構，系統會假設為 https。 對網址執行 HTTP GET 時，必須產生二進位格式的 google.protobuf.Type 值，否則會發生錯誤。 應用程式可以根據網址快取查詢結果，或將查詢結果預先編譯為二進位檔，避免任何查詢。因此，變更型別時必須保留二進位檔相容性。(使用已加入版本的型別名稱來管理重大變更)。 注意：這項功能目前尚未在正式版 protobuf 中推出，也不適用於以 type.googleapis.com 開頭的型別網址。截至 2023 年 5 月，沒有廣泛使用的型別伺服器實作項目，也沒有實作計畫。 http、https (或空白配置) 以外的配置可能會搭配實作專屬語意使用。
value	string (bytes format) 必須是上述指定類型的有效序列化通訊協定緩衝區。 Base64 編碼字串。

工具註解

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