搭配使用 AlloyDB Omni 和 MCP Toolbox 整合代理

1. 簡介

如要讓 AI 代理 (例如 Antigravity CLI) 安全、有條理地存取資料庫，您可以將 AlloyDB Omni 與 MCP Toolbox for Databases 整合。

AlloyDB Omni 是 AlloyDB for PostgreSQL 的可下載容器化版本，可在任何位置執行 (包括地端部署、開發人員工作站、邊緣或雲端)，同時提供企業級 PostgreSQL 效能和相容性。

MCP Toolbox for Databases 是 Google 的開放原始碼伺服器，可實作 Model Context Protocol (MCP)，讓您更輕鬆、快速、安全地建構與資料庫互動的生成式 AI 工具。這項服務介於代理的自動化調度管理架構和資料庫之間，提供下列功能：

  • 簡化開發作業：預先建構或自訂的資料庫工具，只需進行最少設定即可連結至代理，並可在多個代理或框架中重複使用。
  • 效能更佳：內建連線集區和生命週期管理等最佳做法。
  • 強化安全性：集中管理憑證和驗證，代理不需原始資料庫憑證。
  • 端對端觀測能力：立即可用的指標和追蹤功能，內建 OpenTelemetry 支援。

完成本程式碼實驗室後，您將擁有一個執行中的 AlloyDB Omni 容器，其中填入範例電子商務資料、一個 MCP Toolbox 伺服器，其中公開 31 個預先建構的 AlloyDB Omni 管理和查詢工具，以及一個設定好的 Antigravity CLI (agy) 代理，能使用自然語言提示詞檢查結構定義、執行 SQL 查詢、分析查詢計畫，以及診斷資料庫健康狀態。

架構圖：顯示從代理到 MCP 用戶端 (Antigravity CLI)、MCP Toolbox 和 AlloyDB Omni 的端對端工作流程

必要條件

  • 可透過 Google Cloud 控制台或 Linux 工作站，存取 Google Cloud 專案和 Cloud Shell。
  • 已安裝並執行 Docker。
  • 已安裝 psql PostgreSQL 用戶端。
  • 已安裝 curl 和 jq，可設定 Antigravity CLI 和 MCP Toolbox。

課程內容

  • 如何使用 Docker 部署及執行 AlloyDB Omni 資料庫伺服器容器。
  • 如何在 AlloyDB Omni 建立範例資料表、資料和索引。
  • 如何下載、設定及啟動 MCP Toolbox for Databases，並使用預先建構的 alloydb-omni 工具集。
  • 如何將 Antigravity CLI 設為 MCP 用戶端，連線至 MCP Toolbox 伺服器。
  • 如何在 Antigravity CLI 中使用自然語言提示詞，檢查資料庫健康狀態、探索結構定義、執行 SQL 查詢、分析查詢計畫，以及執行維護診斷。

軟硬體需求

  • 具備 Docker、psql、curl 和 jq 的運作中終端機環境。您可以使用 Google Cloud Shell，該環境已預先安裝這些工具。

2. 設定和需求

專案設定

建立 Google Cloud 專案

  1. 在 Google Cloud 控制台的專案選取器頁面，選取或建立 Google Cloud 專案。
  2. 確認 Google Cloud 專案已啟用計費功能。瞭解如何確認專案是否已啟用計費功能。

啟動 Cloud Shell

雖然您可以在筆電本機執行 AlloyDB Omni 和 MCP Toolbox，但在本程式碼實驗室中，您可以使用 Google Cloud Shell，這是在雲端執行的指令列環境，已預先安裝 Docker、psql、curl 和 jq。

啟用 Cloud Shell 的圖示

  1. 開啟 Google Cloud 控制台，然後點選右上角工具列中的「啟用 Cloud Shell」。您也可以透過下列任一方式開啟 Cloud Shell：
    • 如果使用 Google Cloud 控制台，請依序按下 G 和 S。
    • 直接開啟 Cloud Shell。

佈建並連至環境預計只需要幾分鐘，這項作業完成後，您會看到類似下方的內容：

Google Cloud Shell 終端機顯示環境已連線

3. 準備及執行 AlloyDB Omni 資料庫伺服器

在本節中，您會提取並執行 AlloyDB Omni Docker 容器，並填入範例電子商務資料，以便測試。

啟動 AlloyDB Omni 資料庫伺服器

  1. 定義 AlloyDB Omni 主機、通訊埠、資料庫、使用者和生成密碼的環境變數：
    export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"
  2. 使用 Docker，以分離模式啟動 AlloyDB Omni 容器：
    docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest
  3. 確認容器正在運作，且您可以使用 psql 連線至 AlloyDB Omni 伺服器：
    docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

建立測試用的範例資料

建立 categories、products、customers 和 orders 範例資料表、插入測試記錄，並建立索引，以便透過 MCP Toolbox 測試結構定義檢查、SQL 查詢和查詢執行計畫：

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. 啟動 MCP Toolbox 伺服器

在本節中，您將下載 MCP Toolbox 二進位檔、設定預先建構的 AlloyDB Omni 工具定義，並啟動 MCP Toolbox 伺服器。

下載 MCP Toolbox

  1. 為 MCP Toolbox 建立目錄，並下載 toolbox 二進位檔：
    mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

設定及啟動 MCP Toolbox 伺服器

  1. 下載預先建構的 alloydb-omni.yaml 工具設定，並在通訊埠 5000 啟動 MCP Toolbox 伺服器 (使用先前匯出的 ALLOYDB_OMNI_* 環境變數)：
    curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
    alloydb-omni.yaml 設定提供 31 項預先建構的工具，包括本程式碼實驗室示範的重要工具：
    • execute_sql
    • get_query_plan
    • database_overview
    • list_active_queries
    • list_tables、list_indexes、list_views、list_triggers
    • list_top_bloated_tables、list_locks、list_autovacuum_configurations、list_invalid_indexes
    如需完整工具清單，請參閱 GitHub 上的 alloydb-omni.yaml。
  2. 在新的終端機分頁中，確認 MCP Toolbox 伺服器正在執行，並透過 JSON-RPC /mcp 端點公開工具：
    curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. 設定 MCP 用戶端 (Antigravity CLI)

在本節中，您將安裝 Antigravity CLI (agy)，並設定連線至 MCP Toolbox 伺服器。

安裝 Antigravity CLI

  1. 如果尚未安裝，請下載並執行 Antigravity CLI (agy) 安裝程式，然後驗證版本：
    curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

設定 Antigravity CLI

將 MCP Toolbox 伺服器項目新增至用戶端的 MCP 設定檔 (例如 Antigravity CLI 的 ~/.gemini/config/mcp_config.json、.cursor/mcp.json、.vscode/mcp.json、claude_desktop_config.json 或 Claude Code 的 .mcp.json)。

  1. 如要將 Antigravity CLI 連至在通訊埠 5000 執行的 MCP Toolbox HTTP 伺服器，請執行 agy mcp add，並使用 agy mcp list 驗證項目：
    export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
    這會將 alloydb-omni 伺服器設定寫入 ~/.gemini/config/mcp_config.json：
    {
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

驗證設定

  1. 啟動 Antigravity CLI：
    agy
    如果這是您第一次啟動 agy，請按照畫面上的指示登入 (使用 Google OAuth 或 Google Cloud 雲端專案)，並在系統詢問是否信任目前目錄時，選取「Yes, I trust this folder」。
  2. 在 Antigravity CLI 提示中輸入 /mcp，開啟「MCP 伺服器」面板，並確認 alloydb-omni 已連線：
    /mcp
    輸出內容大致如下：
    MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions
  3. 按下 Esc 鍵關閉「MCP 伺服器」面板，返回 Antigravity CLI 提示。

6. 使用 AlloyDB Omni 查詢進行測試

Antigravity CLI 已透過 MCP Toolbox 連結至 AlloyDB Omni 執行個體，現在您可以使用自然語言提示詞與資料庫互動。

執行資料庫總覽查詢

  1. 在 Antigravity CLI 提示詞中，要求提供目前資料庫的總覽：
    Give me an overview of the current database.
    系統提示是否允許呼叫工具時，請選取「是」(或「是，一律允許」，即可在這個對話中一律允許)。輸出結果會與下列內容相似：
    > Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

依類別測試範例

請使用下列自然語言要求，向 Antigravity CLI 輸入提示。代理會自動將每項要求對應至 AlloyDB Omni MCP 工具組中的相應工具：

1. 資料庫總覽和健康狀態

測試目標

自然語言提示詞

叫用工具

系統檢查

Give me an overview of the current database.

database_overview

有效連線數

What queries are currently running on the database?

list_active_queries

已安裝的擴充功能

What extensions are installed in this database?

list_installed_extensions

可用的擴充功能

What extensions are available that I can install?

list_available_extensions

2. 結構定義和目錄探索

測試目標

自然語言提示詞

叫用工具

列出資料表

Show me all the tables in the current database.

list_tables

檢查索引

List all indexes in the database and which tables they belong to.

list_indexes

探索檢視畫面

What views are available in the public schema?

list_views

檢查資料表觸發條件

Show me the triggers defined on the orders table.

list_triggers

3. 資料查詢和篩選 (execute_sql)

測試目標

自然語言提示詞

叫用工具

匯總查詢

Show me the 3 most expensive products in the 'Laptops' category.

execute_sql

JOIN 查詢

Find all customers who have placed an order in the last 6 months.

execute_sql

不相符的記錄

Which customers haven't placed any orders yet?

execute_sql

4. 查詢效能和說明計畫 (get_query_plan)

測試目標

自然語言提示詞

叫用工具

說明計畫

Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.

get_query_plan

索引驗證

Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.

get_query_plan

5. 資料庫維護和診斷

測試目標

自然語言提示詞

叫用工具

資料表膨脹

List the top five most bloated tables.

list_top_bloated_tables

鎖定爭用

Show me if there are any active locks or blocked transactions.

list_locks

Autovacuum 設定

Show me the current autovacuum configuration.

list_autovacuum_configurations

無效索引

Check for any invalid indexes in the database.

list_invalid_indexes

7. 清除

完成程式碼實驗室後，請清除本機容器和您啟動的程序。

  1. 輸入 /quit (或連按兩次 Ctrl+D)，即可退出 Antigravity CLI。
  2. 切換至執行 MCP Toolbox 伺服器的終端機分頁，然後按下 Ctrl+C 停止伺服器。
  3. 停止並移除 AlloyDB Omni Docker 容器：
    docker stop alloydbomni
docker rm alloydbomni

8. 恭喜

恭喜您完成程式碼實驗室！您已成功在容器中部署 AlloyDB Omni、使用預先建構的 AlloyDB Omni 工具組設定 MCP Toolbox for Databases，並與 Antigravity CLI 整合，以便使用自然語言查詢及管理資料庫。

涵蓋內容

  • 如何使用 Docker 部署及驗證 AlloyDB Omni 容器。
  • 如何填入範例資料表和索引，以便測試 Agentic Workflows。
  • 如何使用預先建構的 alloydb-omni 工具設定，設定及執行 MCP Toolbox for Databases。
  • 如何將 Antigravity CLI 連結至 MCP Toolbox，並執行自然語言提示詞，探索結構定義、SQL 查詢、分析查詢計畫，以及診斷資料庫。

詳情請參閱下列資源：

9. 問卷調查

您會如何使用這個教學課程？

只閱讀內容 閱讀內容並完成練習