將 PostgreSQL 適用的 Cloud SQL 與 MCP、Gemini CLI 和其他代理程式搭配使用

本頁面說明如何將 Cloud SQL 執行個體連線至各種 AI 開發人員輔助工具，包括：

如要獲得整合式體驗，建議使用專用的 Gemini CLI 擴充功能，搭配 PostgreSQL 適用的 Cloud SQL。

Gemini CLI 是 Google Cloud的下一代指令列介面，可將基礎 MCP 伺服器直接整合至擴充功能，簡化設定和配置程序。您可以設定 Gemini Code Assist 使用 Gemini CLI，在 IDE 中享有類似的設定優勢。

如要連結支援模型上下文協定 (MCP) 的其他開發人員工具，請手動設定資料庫適用的 MCP Toolbox (Toolbox)。Toolbox 是開放原始碼 MCP 伺服器，可管理驗證和連線集區等工作，將 AI 代理連結至您的資料。這樣一來，您就能直接在 IDE 中使用自然語言與資料互動。對於這些工具，這個方法提供核心資料庫互動功能。

詳情請參閱「預先建構的工具」和「GitHub 上的資料庫用 MCP 工具箱」。

關於 Gemini CLI 和擴充功能

Gemini CLI 是開放原始碼 AI 代理，可協助您完成程式碼撰寫、偵錯、資料探索和內容建立等開發工作流程。這項工具提供代理介面，可與資料庫和分析服務，以及熱門的開放原始碼資料庫互動。

擴充功能的運作方式

Gemini CLI 具備高度擴充性，可透過擴充功能新增工具和功能。您可以從 GitHub 網址、本機目錄或可設定的登錄檔載入擴充功能。這些外掛程式提供新的工具、斜線指令和提示，可協助您完成工作流程。

在 PostgreSQL 適用的 Cloud SQL 中使用 Gemini CLI 擴充功能

Cloud SQL Gemini CLI 擴充功能是以 MCP Toolbox for Databases 為基礎。MCP Toolbox for Databases 目前為 Beta 版 (v1.0 前期版本)，在第一個穩定版 (v1.0) 發布前，可能會出現重大變更。

與 Gemini CLI 整合時，您會使用專屬擴充功能，與標準工具箱連線相比，這項擴充功能提供更多功能。這項擴充功能提供簡化的安裝程序和一系列工具。

詳情請參閱 GitHub 說明文件，瞭解 PostgreSQL 適用的 Cloud SQL Gemini CLI 擴充功能。

適用於 PostgreSQL 適用的 Cloud SQL 資料庫的 Gemini CLI 擴充功能

cloud-sql-postgresql 擴充功能包含查詢資料庫、管理 Cloud SQL 資源，以及監控資料庫健康狀態的工具。

類別 工具
資料庫作業
  • list_tables：列出資料庫中的所有資料表及其對應說明。
  • execute_sql：執行任何 SQL 陳述式。
  • list_active_queries：列出 Cloud SQL 執行個體目前執行的查詢。
  • list_available_extensions：列出可安裝在 Cloud SQL 執行個體上的 PostgreSQL 擴充功能。
  • list_installed_extensions：列出 Cloud SQL 執行個體上安裝的 PostgreSQL 擴充功能。
  • get_query_plan：從 Cloud SQL 執行個體取得單一陳述式的查詢計畫。
管理執行個體和使用者的資源
  • create_user：在 Cloud SQL 執行個體中建立新使用者。
  • list_databases：列出 Cloud SQL 執行個體的所有資料庫。
  • create_database：在 Cloud SQL 執行個體中建立新的資料庫。
  • list_instances：列出指定專案中的 Cloud SQL 執行個體。
  • get_instance：取得特定 Cloud SQL 執行個體的詳細資料。
  • create_instance：建立新的 Cloud SQL 執行個體。
  • wait_for_operation：輪詢 Operations API，直到作業完成為止。
資料庫健康狀態與維護
  • list_autovacuum_configurations：列出 Cloud SQL 執行個體的自動清除設定。清除作業會移除無效的元組，藉此釋出磁碟空間、防止資料表膨脹，並提升讀取和寫入效能。
  • list_memory_configurations：列出 Cloud SQL 執行個體上的執行個體層級記憶體設定。 顯示 shared_buffers 和 work_mem 等參數，協助您評估及最佳化查詢執行和快取的資源分配。
  • list_top_bloated_tables： 列出 Cloud SQL 執行個體中未使用空間最多的資料表 (膨脹)。您可以根據這項資訊安排維護作業 (包括清除或重新建立索引)，藉此回收磁碟空間並提升查詢速度。
  • list_replication_slots：列出複製時段詳細資料，例如 Cloud SQL 執行個體上的預先寫入記錄 (WAL)。協助管理及排解複製相關問題。
  • list_invalid_indexes：列出 Cloud SQL 執行個體上的無效索引。您可以根據這項資訊重建或捨棄無效索引，進而提升查詢效能。

cloud-sql-postgresql-observability 擴充功能提供統一介面，可直接從 Gemini CLI 管理及監控資料庫效能和健康狀態。

類別 工具
觀測能力
  • get_system_metrics：擷取 Cloud SQL 執行個體的系統指標。
  • get_query_metrics：擷取 Cloud SQL 執行個體的查詢相關指標。

適用於 PostgreSQL 資料庫的 Gemini CLI 擴充功能

如需這些作業的清單，請參閱 MCP Toolbox for Databases 和 Gemini CLI extension for PostgreSQL。

事前準備

  • 在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。

  • 確認您已為 Google Cloud 專案啟用計費功能。

  • 在 Google Cloud 專案中啟用 Cloud SQL Admin API。

  • 根據預設，Cloud SQL 會為新執行個體指派公開 IP 位址。請根據用途，確保 Cloud SQL 執行個體已設定公開 IP 或私人 IP。Toolbox 會使用 Cloud SQL 語言連接器安全連線。

  • 授予執行 MCP 伺服器的使用者必要的 Identity and Access Management (IAM) 角色。可用的工具取決於獲派的角色：

    工作 角色名稱 必要 IAM 角色
    提供資源的唯讀存取權，包括下列作業：
    • get_instance
    • list_instances
    • list_databases
    • wait_for_operation
    		 Cloud SQL 檢視者 roles/cloudsql.viewer
    提供監控資料的唯讀存取權，例如時間序列指標。 Cloud Monitoring 檢視者 roles/monitoring.viewer
    提供管理現有資源的權限，包括：
    • 所有viewer工具
    • create_database
    		 Cloud SQL 編輯者 roles/cloudsql.editor
    提供所有資源的完整控制權，包括：
    • 所有 viewer 和 editor 工具
    • create_instance
    • create_user
    		 Cloud SQL 管理員 roles/cloudsql.admin

  • 為環境設定應用程式預設憑證 (ADC)。

  • 建立或重複使用資料庫使用者，並準備好使用者名稱和密碼。

安裝 MCP Toolbox

  1. 如要安裝工具箱，請下載與作業系統和 CPU 架構對應的二進位檔。

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/windows/amd64/toolbox

  2. 將二進位檔設為可執行檔：

    chmod +x toolbox

  3. 使用下列指令驗證安裝作業：

    ./toolbox --version

設定 MCP 用戶端

本節說明如何設定各種開發人員工具，使用 Toolbox 連線至 Cloud SQL 執行個體。Toolbox 充當開放原始碼的模型上下文協定 (MCP) 伺服器，位於 IDE 和資料庫之間，為 AI 工具提供安全有效率的控制平面。選取特定工具的分頁標籤，查看設定操作說明。

適用於 PostgreSQL 適用的 Cloud SQL 的 Gemini CLI


  1. 安裝 Gemini CLI。
  2. 使用下列指令，從 GitHub 存放區安裝 Gemini CLI 的 PostgreSQL 適用的 Cloud SQL 擴充功能：
      gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
  3. 設定環境變數，連線至 Cloud SQL 執行個體： 
      export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
  export CLOUD_SQL_POSTGRES_REGION="REGION"
  export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
  export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
  export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
  export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
  export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
    取代下列項目：
    • PROJECT_NAME：專案 ID。 Google Cloud
    • REGION：Cloud SQL 執行個體所在的區域。
    • INSTANCE_NAME：Cloud SQL 執行個體的 ID。
    • DATABASE_NAME：要連線的資料庫名稱。
    • DATABASE_USER_NAME：(選填) 資料庫使用者名稱。如未指定，預設為 IAM 驗證。
    • PASSWORD：(選填) 資料庫使用者的密碼。如未指定，預設為 IAM 驗證。
    • IP_TYPE：選用：IP 類型，例如「Public」(預設) 或「Private」。
  4. 在互動模式中啟動 Gemini CLI： 
      gemini

    CLI 會自動載入 Cloud SQL 的 Gemini CLI 擴充功能及其工具，方便您與資料庫互動。

    在 Gemini CLI 中，使用 /extensions 指令確認擴充功能已安裝，並使用 /mcp list 指令查看工具。

PostgreSQL 適用的 Gemini CLI


1. 安裝 Gemini CLI。
2. 使用下列指令，從 GitHub 存放區安裝 Gemini CLI 的 PostgreSQL 軟體擴充功能：
      gemini extensions install https://github.com/gemini-cli-extensions/postgres
3. 設定環境變數，連線至 PostgreSQL 執行個體： 
      export POSTGRES_HOST="HOST"
      export POSTGRES_PORT="PORT"
      export POSTGRES_DATABASE="DATABASE"
      export POSTGRES_USER="USER"
      export POSTGRES_PASSWORD="PASSWORD"
      export POSTGRES_QUERY_PARAMETERS="QUERY_PARAMETERS"
取代下列項目：
  • HOST：PostgreSQL 伺服器的主機名稱或 IP 位址。
  • PORT：PostgreSQL 伺服器的通訊埠號碼。
  • DATABASE：要連線的資料庫名稱。
  • USER：資料庫使用者名稱。
  • PASSWORD：資料庫使用者的密碼。
  • QUERY_PARAMETERS：(選填) 要加入 db 連線字串的原始查詢。
4. 在互動模式中啟動 Gemini CLI： 
      gemini

CLI 會自動載入 PostgreSQL 適用的 Gemini CLI 擴充功能及其工具，方便您與資料庫互動。

Gemini Code Assist


1. 在 Visual Studio Code 中安裝 Gemini Code Assist 擴充功能。
2. 在 Gemini Code Assist 對話中啟用代理程式模式。
3. 在工作目錄中，建立名為 .gemini 的資料夾。在其中建立 settings.json 檔案。
4. 新增下列設定，將環境變數替換為您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude 代碼


1. 安裝 Claude Code。
2. 如果專案根目錄中沒有 .mcp.json 檔案，請建立該檔案。
3. 新增設定、將環境變數換成您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude 電腦版


1. 開啟 Claude Desktop，然後前往「設定」。
2. 在「開發人員」分頁下方，輕觸「編輯設定」開啟設定檔。
3. 新增設定、將環境變數換成您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
    }
  }
}

5. 重新啟動 Claude Desktop。
6. 新的即時通訊畫面會顯示槌子 (MCP) 圖示，並提供新的 MCP 伺服器。

Cline


1. 在 VS Code 中開啟 Cline 擴充功能，然後輕觸「MCP Servers」圖示。
2. 輕觸「Configure MCP Servers」開啟設定檔。
3. 新增下列設定，將環境變數替換為您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

4. 伺服器連線成功後，會顯示綠色的「有效」狀態。

Cursor


1. 如果專案根目錄中沒有 .cursor 目錄，請建立該目錄。
2. 如果 .cursor/mcp.json 檔案不存在，請建立並開啟該檔案。
3. 新增下列設定，將環境變數替換為您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

4. 開啟「游標」，然後依序前往「設定」>「游標設定」>「MCP」。伺服器連線後，會顯示綠色的「有效」狀態。

Visual Studio Code (Copilot)


1. 開啟 VS Code，並在專案根目錄中建立 .vscode 目錄 (如果不存在)。
2. 如果 .vscode/mcp.json 檔案不存在，請建立並開啟該檔案。
3. 新增下列設定，將環境變數替換為您的值，然後儲存：


{
  "servers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

滑浪風帆


1. 開啟 Windsurf，然後前往 Cascade 助理。
2. 輕觸 MCP 圖示，然後輕觸「設定」開啟設定檔。
3. 新增下列設定，將環境變數替換為您的值，然後儲存：


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}