搭配使用 AlloyDB for PostgreSQL 與 MCP、Gemini CLI 和其他代理程式

如要透過 IDE 或終端機,使用自然語言查詢 AlloyDB for PostgreSQL 資料庫、檢查結構定義及管理資料庫資源,可以將執行個體連結至支援模型內容通訊協定 (MCP) 的 AI 工具。

建議使用 Gemini CLI 專用的 AlloyDB 擴充功能。Gemini CLI 會將基礎 MCP 伺服器直接整合至擴充功能,因此您不必另外設定伺服器。您可以設定 Gemini Code Assist 使用 Gemini CLI,在 IDE 中享有類似的設定優勢。

或者,其他支援 MCP 的 IDE 和代理,可透過 MCP Toolbox for Databases 連線。Toolbox 是開放原始碼 MCP 伺服器,可將 AI 代理連結至資料。這項工具會處理驗證和連線集區等工作,讓您直接在 IDE 中使用自然語言與資料互動。

事前準備

如要連線至 AlloyDB 執行個體並使用可用工具,您必須具備下列其中一個 Identity and Access Management (IAM) 角色,或具備同等權限的自訂角色:

工作 角色名稱 必要的 IAM 角色
使用唯讀工具列出及取得 AlloyDB 資源 AlloyDB 檢視者 roles/alloydb.viewer
連線至執行個體並執行查詢 AlloyDB 用戶端 roles/alloydb.client
服務使用情形消費者 roles/serviceusage.serviceUsageConsumer
執行管理工作 (例如建立或管理叢集、執行個體和使用者) AlloyDB 管理員 roles/alloydb.admin
使用觀測能力擴充功能 監控檢視者 roles/monitoring.viewer

您必須先完成下列步驟,設定專案和資料庫,才能連線至 AlloyDB 執行個體。

  1. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud,歡迎 建立帳戶,親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額,用於執行、測試及部署工作負載。
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 啟用必要的 Cloud API,以便建立及連線至 AlloyDB。

    啟用 API

    1. 在「確認專案」步驟中,點選「下一步」,確認要變更的專案名稱。

    2. 在「啟用 API」步驟中,點選「啟用」來啟用下列項目:

      • AlloyDB API
      • Compute Engine API
      • Cloud Resource Manager API
      • Service Networking API

      如要使用與 AlloyDB 位於相同 Google Cloud 專案的虛擬私有雲網路 (VPC 網路),設定 AlloyDB 的網路連線,就必須啟用 Service Networking API。

      如要使用位於其他 Google Cloud 專案的虛擬私有雲網路,設定 AlloyDB 的網路連線,則須啟用 Compute Engine API 和 Cloud Resource Manager API。

  7. 建立或選取叢集及其主要執行個體。
  8. 為環境設定應用程式預設憑證 (ADC)。
  9. 建立或重複使用資料庫使用者。準備輸入使用者名稱和密碼。

使用 AlloyDB 專用的 Gemini CLI 擴充功能

Gemini CLI 是開放原始碼 AI 代理,可協助編寫程式碼、偵錯、探索資料和創作內容,輔助開發工作流程。其宗旨是提供互動式介面,讓使用者與 Data Cloud 服務和熱門開放原始碼資料庫互動。

與 Gemini CLI 的整合是透過專屬擴充功能進行,相較於標準 MCP Toolbox 連線,可提供額外功能。以下各節將說明 alloydb 和 alloydb-observability 擴充功能,這些功能提供安裝程序和一組工具。開放原始碼擴充功能包含安裝、設定和使用範例的詳細資訊。詳情請參閱「Gemini CLI 擴充功能 - AlloyDB for PostgreSQL」。

AlloyDB 擴充功能

alloydb 擴充功能包含查詢資料庫、管理 AlloyDB 資源,以及監控資料庫健康狀態的工具。

下列範例使用範例 ecommerce 資料庫,其中包含以下資料表:

  • products:包含產品資訊,包括 product_id、product_name、category 和 price。
  • customers:儲存客戶資料,例如 customer_id、first_name、last_name 和 email。
  • orders:保留訂單資訊,包括 order_id、customer_id 和 order_date。
類別 工具 自然語言提示範例
資料庫作業 database_overview 提供目前資料庫的總覽。
list_tables 顯示目前資料庫中的所有資料表。
execute_sql 顯示「筆電」類別中價格最高的 10 項產品。
list_active_queries 資料庫正在執行哪些查詢?
get_query_plan 說明查詢計畫,找出過去 6 個月內未下單的所有顧客。
list_available_extensions 我可以安裝哪些擴充功能?
list_installed_extensions 列出所有已安裝的擴充功能。
list_indexes 列出 products 資料表中的所有索引。
list_locks 顯示資料庫中所有有效的鎖定。
list_schemas 列出資料庫中的所有結構定義。
list_sequences 顯示目前結構定義中的所有序列。
list_triggers 列出 orders 資料表的所有觸發條件。
list_views 顯示 sales 結構定義中的所有檢視表。
資源管理
叢集、執行個體、使用者
create_cluster 在 us-east1 區域建立名為 sales-quarterly-db 的 AlloyDB 叢集。
get_cluster 取得叢集 sales-quarterly-db 的詳細資料。
list_clusters 列出我所有的 AlloyDB 叢集。
create_instance 在 sales-quarterly-db 叢集建立新的讀取執行個體。
get_instance 顯示執行個體 sales-quarterly-db-rp 的資訊。
list_instances 列出 sales-quarterly-db 叢集中的所有執行個體。
create_user 建立新的資料庫使用者,名稱為 reporting_user,密碼為 report_password。
為 reporting_user@example.com 建立新的 IAM 資料庫使用者。
get_user 取得使用者 reporting_user 的資訊。
list_users 列出所有資料庫使用者。
wait_for_operation 作業 operation-163562789 的狀態為何?
資料庫健康狀態和維護 list_autovacuum_configurations 顯示目前的自動清理設定。
list_memory_configurations 主要執行個體目前的記憶體設定為何?
list_top_bloated_tables 列出前五個最臃腫的資料表。
list_replication_slots 顯示所有使用中的複製槽。
replication_stats 顯示目前的複製統計資料。
list_invalid_indexes 檢查 ecommerce 資料庫中是否有任何無效索引。
long_running_transactions 是否有長時間執行的交易?

AlloyDB Observability 擴充功能

alloydb-observability 擴充功能提供統一介面,可直接透過 Gemini CLI 管理及監控資料庫效能和健康狀態。

類別 工具 自然語言提示範例
觀測能力 get_system_metrics 過去一小時的系統指標 (例如 CPU 用量) 為何?
get_query_metrics 顯示過去 15 分鐘的查詢成效指標。

AlloyDB 專用 Gemini CLI 擴充功能有兩種使用方式:

  • 獨立指令列工具
  • 透過 Gemini Code Assist 整合至 IDE

Gemini CLI

  1. 安裝 Gemini CLI。
  2. 使用下列指令,從 GitHub 存放區安裝 Gemini CLI 的 AlloyDB 擴充功能:
    gemini extensions install https://github.com/gemini-cli-extensions/alloydb
    
  3. 設定環境變數,連線至 AlloyDB 執行個體:
    export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID"
    export ALLOYDB_POSTGRES_REGION="REGION"
    export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME"
    export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME"
    export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"
    

    根據預設,AlloyDB 專用 Gemini CLI 擴充功能會使用應用程式預設憑證 (ADC) 進行驗證。如要改以資料庫使用者身分連線,請設定下列選用環境變數:

    #Optional: Set for database user authentication
    export ALLOYDB_POSTGRES_USER="USERNAME"
    export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"
    

    如要使用私人 IP 位址連線,您也必須設定下列環境變數:

    export ALLOYDB_POSTGRES_IP_TYPE="private"
    
  4. 在互動模式下啟動 Gemini CLI:
    gemini
    
    CLI 會自動載入 AlloyDB 專用 Gemini CLI 擴充功能和相關工具,方便您與資料庫互動。

Gemini Code Assist

建議您設定 Gemini Code Assist,以便使用 Gemini CLI,這樣就不必手動設定 MCP 伺服器。

  1. 確認您已安裝並設定 Gemini CLI 和 alloydb 擴充功能。
  2. 設定 Gemini Code Assist,以便使用 Gemini CLI。
  3. 直接在 Gemini Code Assist 對話中,使用自然語言與 AlloyDB 執行個體互動。

連線至 Antigravity

您可以透過下列方式將 AlloyDB 連結至 Antigravity:

  • 使用 MCP 商店
  • 使用自訂設定

注意:您不需要下載 MCP Toolbox 二進位檔,即可使用這些方法。

MCP 商店

在 Antigravity 中,最推薦的 AlloyDB 連線方式是使用內建的 MCP 商店。

  1. 開啟 Antigravity,然後開啟編輯器的代理面板。
  2. 按一下面板頂端的「...」圖示,然後選取「MCP 伺服器」。
  3. 在可用伺服器清單中,找到「AlloyDB for PostgreSQL」,然後點選「安裝」。
  4. 按照畫面上的指示,安全地連結帳戶 (如適用)。

在 MCP 商店安裝 AlloyDB 後,編輯器會自動取得伺服器的資源和工具。

自訂設定

如要連線至自訂 MCP 伺服器,請按照下列步驟操作:

  1. 開啟 Antigravity,然後開啟編輯器的代理面板。
  2. 按一下面板頂端的「...」圖示,然後選取「MCP 伺服器」。
  3. 依序點選「管理 MCP 伺服器」>「查看原始設定」,開啟 mcp_config.json 檔案。
  4. 將下列設定新增至 mcp_config.json 檔案並儲存。
{
  "mcpServers": {
    "alloydb-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
更改下列內容:
  • PROJECT_ID:您的 Google Cloud 專案 ID。
  • REGION:AlloyDB 區域名稱。
  • CLUSTER_NAME:AlloyDB 叢集名稱。
  • INSTANCE_NAME:AlloyDB 執行個體名稱。
  • DATABASE_NAME:AlloyDB 資料庫名稱。
  • USERNAME:ALLOYDB_POSTGRES_USER 變數的 AlloyDB 使用者名稱。
  • PASSWORD:ALLOYDB_POSTGRES_PASSWORD 變數的 AlloyDB 密碼。

使用 MCP Toolbox for Databases 連結其他 IDE

本節說明如何使用 MCP Toolbox for Databases,從各種代理連線至 AlloyDB 執行個體。Toolbox 是開放原始碼的 Model Context Protocol (MCP) 伺服器,介於 IDE 和資料庫之間,可做為 AI 工具的控制層。本節說明如何使用公開或私人 IP 位址連線至 AlloyDB 執行個體。根據預設,Toolbox 會使用公開 IP 位址,但您可以設定 ALLOYDB_POSTGRES_IP_TYPE 環境變數,建立私人 IP 連線,如設定範例所示。

安裝 MCP Toolbox for Databases

如要將 IDE 連結至 AlloyDB,必須安裝 MCP Toolbox for Databases,這個開放原始碼伺服器可將 AI 代理連結至資料。

  1. 以二進位檔形式下載最新版本 Toolbox。選取與作業系統和 CPU 架構對應的二進位檔。您必須使用 Toolbox v0.15.0 以上版本。

    linux/amd64

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

    darwin/arm64

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

    darwin/amd64

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

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox
  2. 將二進位檔設為可執行檔。

    chmod +x toolbox
    
  3. 驗證安裝。

    ./toolbox --version
    

設定用戶端

從下列選項中選取代理工具:

Claude Code

  1. 安裝 Claude Code。
  2. 在專案根目錄中建立 .mcp.json 檔案 (如果不存在)。
  3. 新增設定,將環境變數替換為您的值,然後儲存。

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude 電腦版

  1. 開啟 Claude Desktop,然後前往「設定」。
  2. 在「開發人員」分頁中,點選「編輯設定」開啟設定檔。
  3. 新增設定,將環境變數替換為您的值,然後儲存。

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
  1. 重新啟動 Claude Desktop。
  2. 新的對話畫面會顯示鎚子 (MCP) 圖示和新的 MCP 伺服器。

Cline

  1. 在 VS Code 中開啟 Cline 擴充功能,然後點按「MCP 伺服器」圖示。
  2. 按一下「設定 MCP 伺服器」,開啟設定檔。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存。

{
  "mcpServers": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

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

Cursor

  1. 如果專案根目錄中沒有 .cursor 目錄,請建立該目錄。
  2. 如果 .cursor/mcp.json 檔案不存在,請建立並開啟該檔案。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存。
{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
  1. 開啟 Cursor,然後依序前往「Settings」>「Cursor Settings」>「MCP」。伺服器連線後,會顯示綠色的「有效」狀態。

Visual Studio Code (Copilot)

  1. 開啟 VS Code,並在專案根目錄中建立 .vscode 目錄 (如果尚未建立)。
  2. 如果 .vscode/mcp.json 檔案不存在,請建立並開啟該檔案。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存。
{
  "servers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
        "ALLOYDB_POSTGRES_REGION": "REGION",
        "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
        "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
        "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
        "ALLOYDB_POSTGRES_USER": "USERNAME",
        "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

風浪板

  1. 開啟 Windsurf,然後前往 Cascade 助理。
  2. 依序點按 MCP 圖示和「設定」,開啟設定檔。
  3. 新增下列設定,將環境變數替換為您的值,然後儲存。
{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

使用 MCP Toolbox for Databases 存取進階查詢洞察

您可以使用 MCP Toolbox for Databases,直接在 IDE 中存取 AlloyDB 觀測能力功能和進階查詢洞察。這樣一來,AI 代理就能分析查詢執行統計資料、監控等待事件,以及擷取索引建議,排解資料庫效能問題。

必要的角色

如要取得在 MCP Toolbox for Databases 使用 AlloyDB 觀測能力預先建構設定所需的權限,請要求管理員在您要使用工具的專案中,授予下列 IAM 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備必要權限,可在 MCP Toolbox for Databases 使用 AlloyDB 觀測能力預先建構設定。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

必須具備下列權限,才能在 MCP Toolbox for Databases 使用 AlloyDB 觀測能力預建設定:

  • 取得查詢指標:queryMetrics.fetch
  • 取得系統指標: systemMetrics.fetch
  • 取得進階匯總查詢統計資料: queryStats.fetch
  • 取得進階時間序列查詢統計資料:queryTimeSeries.fetch
  • 取得進階匯總等待事件統計資料:waitEventStats.fetch
  • 取得進階時間序列等待事件統計資料: waitEventTimeSeries.fetch
  • 取得索引建議: recommendations.query, resourceRecommendations.query
  • 查看 Monitoring 指標:monitoring.timeseries.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要設定 IDE 使用 alloydb-postgres-observability 預先建構的設定,請將下列設定新增至用戶端的 MCP 設定檔。

詳情請參閱「MCP Toolbox for Databases:AlloyDB for PostgreSQL」說明文件。

{
  "mcpServers": {
    "alloydb-observability": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt", "alloydb-postgres-observability", "--stdio"]
    }
  }
}

連結這項預先建構的設定後,代理就能叫用下列 AlloyDB 進階查詢洞察工具,排解效能問題:

  • get_advanced_aggregated_query_stats:擷取匯總的查詢執行統計資料。
  • get_advanced_aggregated_wait_event_stats:擷取匯總的等待事件瓶頸指標。
  • get_advanced_time_series_query_stats:擷取查詢在一段時間內的時序成效指標。
  • get_advanced_time_series_wait_event_stats:擷取等待事件的時間序列指標。
  • get_index_recommendations:擷取索引建議,盡可能提高查詢效能。

使用 Data Agent Kit 連結

Google Cloud Data Agent Kit 可讓您直接在 VS Code、以 VS Code 為基礎的 IDE 和支援的 CLI 中,連線及查詢 AlloyDB 資料庫。

使用 Data Agent Kit 的好處包括:

  • 資料探索功能,可讓您以自然語言詢問 AlloyDB 資料相關問題
  • 不需在 AlloyDB 工具和開發環境之間切換
  • 可讓您透過互動式 CLI 使用 Google Cloud 資源的外掛程式

詳情請參閱「Data Agent Kit 總覽」。