1. Giới thiệu
Để cấp cho các tác nhân AI (chẳng hạn như Antigravity CLI) quyền truy cập an toàn và có cấu trúc vào cơ sở dữ liệu, bạn có thể tích hợp AlloyDB Omni với MCP Toolbox for Databases.
AlloyDB Omni là phiên bản đóng gói có thể tải xuống của AlloyDB cho PostgreSQL, được thiết kế để chạy ở mọi nơi (tại chỗ, trên máy trạm của nhà phát triển, tại biên hoặc trên đám mây) đồng thời mang lại hiệu suất và khả năng tương thích PostgreSQL cấp doanh nghiệp.
Bộ công cụ MCP cho cơ sở dữ liệu là một máy chủ nguồn mở của Google, triển khai Giao thức ngữ cảnh mô hình (MCP) để giúp việc xây dựng các công cụ AI tạo sinh tương tác với cơ sở dữ liệu trở nên dễ dàng, nhanh chóng và an toàn hơn. Lớp này nằm giữa khung điều phối của tác nhân và cơ sở dữ liệu, đồng thời cung cấp các chức năng sau:
- Phát triển đơn giản: Các công cụ cơ sở dữ liệu tạo sẵn hoặc tuỳ chỉnh kết nối với tác nhân của bạn mà không cần nhiều cấu hình và có thể được sử dụng lại trên nhiều tác nhân hoặc khung.
- Hiệu suất tốt hơn: Các phương pháp hay nhất được tích hợp sẵn như gộp kết nối và quản lý vòng đời.
- Bảo mật nâng cao: Quản lý thông tin xác thực và xác thực tập trung để các tác nhân không cần thông tin xác thực cơ sở dữ liệu thô.
- Khả năng ghi nhận toàn diện: Các chỉ số và hoạt động theo dõi có sẵn, hỗ trợ sẵn OpenTelemetry.
Khi kết thúc lớp học lập trình này, bạn sẽ có một vùng chứa AlloyDB Omni đang chạy, được điền sẵn dữ liệu thương mại điện tử mẫu, một máy chủ Bộ công cụ MCP hiển thị 31 công cụ quản trị và công cụ truy vấn AlloyDB Omni được tạo sẵn, cùng một tác nhân Antigravity CLI (agy) được định cấu hình có khả năng kiểm tra lược đồ, chạy truy vấn SQL, phân tích kế hoạch truy vấn và chẩn đoán tình trạng cơ sở dữ liệu bằng cách sử dụng câu lệnh bằng ngôn ngữ tự nhiên.
Điều kiện tiên quyết
- Quyền truy cập vào một dự án Google Cloud và Cloud Shell từ Google Cloud Console hoặc máy trạm Linux.
- Docker đã được cài đặt và đang chạy.
- Đã cài đặt ứng dụng PostgreSQL
psql. - Đã cài đặt
curlvàjqđể thiết lập Antigravity CLI và MCP Toolbox.
Kiến thức bạn sẽ học được
- Cách triển khai và chạy vùng chứa máy chủ cơ sở dữ liệu AlloyDB Omni bằng Docker.
- Cách tạo bảng, dữ liệu và chỉ mục mẫu trong AlloyDB Omni.
- Cách tải xuống, định cấu hình và khởi động MCP Toolbox for Databases bằng bộ công cụ
alloydb-omnitạo sẵn. - Cách định cấu hình Antigravity CLI làm ứng dụng MCP để kết nối với máy chủ MCP Toolbox.
- Cách sử dụng câu lệnh bằng ngôn ngữ tự nhiên trong Antigravity CLI để kiểm tra tình trạng cơ sở dữ liệu, khám phá giản đồ, chạy truy vấn SQL, phân tích kế hoạch truy vấn và thực hiện chẩn đoán bảo trì.
Bạn cần có
- Một môi trường dòng lệnh đang hoạt động có Docker,
psql,curlvàjq. Bạn có thể sử dụng Google Cloud Shell, một công cụ được cài đặt sẵn các công cụ này.
2. Thiết lập và yêu cầu
Thiết lập dự án
Tạo một dự án trên Google Cloud
- Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Xác minh rằng bạn đã bật tính năng thanh toán cho dự án Google Cloud của mình. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trong dự án hay không.
Bắt đầu Cloud Shell
Mặc dù có thể chạy AlloyDB Omni và MCP Toolbox trên máy tính xách tay, nhưng trong lớp học lập trình này, bạn có thể sử dụng Google Cloud Shell, một môi trường dòng lệnh chạy trên đám mây được cài đặt trước Docker, psql, curl và jq.
- Mở Google Cloud Console rồi nhấp vào Activate Cloud Shell (Kích hoạt Cloud Shell) trên thanh công cụ ở trên cùng bên phải.Bạn cũng có thể mở Cloud Shell theo một trong những cách sau:
- Nếu bạn đang sử dụng Google Cloud Console, hãy nhấn
Grồi nhấnS. - Mở trực tiếp Cloud Shell.
- Nếu bạn đang sử dụng Google Cloud Console, hãy nhấn
Thông thường, bạn sẽ mất vài phút để cấp phép và kết nối với môi trường. Khi thao tác này hoàn tất, bạn sẽ thấy kết quả tương tự như sau:
3. Chuẩn bị và chạy máy chủ cơ sở dữ liệu AlloyDB Omni
Trong phần này, bạn sẽ lấy và chạy vùng chứa Docker của AlloyDB Omni, sau đó điền dữ liệu mẫu về thương mại điện tử vào vùng chứa đó để thử nghiệm.
Khởi động máy chủ cơ sở dữ liệu AlloyDB Omni
- Xác định các biến môi trường cho máy chủ, cổng, cơ sở dữ liệu, người dùng và mật khẩu được tạo của 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" - Khởi động vùng chứa AlloyDB Omni ở chế độ tách rời bằng cách sử dụng Docker:
docker run --name alloydbomni \ -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \ -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \ -d google/alloydbomni:latest - Xác minh rằng vùng chứa đang chạy và bạn có thể kết nối với máy chủ AlloyDB Omni bằng cách sử dụng
psql: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;"
Tạo dữ liệu mẫu để kiểm thử
Tạo các bảng mẫu categories, products, customers và orders, chèn bản ghi kiểm thử và tạo chỉ mục để bạn có thể kiểm thử quy trình kiểm tra giản đồ, truy vấn SQL và kế hoạch thực thi truy vấn thông qua MCP Toolbox:
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. Khởi động máy chủ MCP Toolbox
Trong phần này, bạn sẽ tải tệp nhị phân của Bộ công cụ MCP xuống, định cấu hình các định nghĩa công cụ AlloyDB Omni tạo sẵn và khởi động máy chủ Bộ công cụ MCP.
Tải Hộp công cụ MCP xuống
- Tạo một thư mục cho Bộ công cụ MCP và tải tệp nhị phân
toolboxxuống: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
Định cấu hình và khởi động máy chủ MCP Toolbox
- Tải cấu hình công cụ
alloydb-omni.yamltạo sẵn xuống và khởi động máy chủ MCP Toolbox trên cổng5000(bằng cách sử dụng các biến môi trườngALLOYDB_OMNI_*đã xuất trước đó):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.1alloydb-omni.yamlcung cấp 31 công cụ tạo sẵn, bao gồm cả các công cụ chính được minh hoạ trong lớp học lập trình này:execute_sqlget_query_plandatabase_overviewlist_active_querieslist_tables,list_indexes,list_views,list_triggerslist_top_bloated_tables,list_locks,list_autovacuum_configurations,list_invalid_indexes
alloydb-omni.yamltrên GitHub. - Trong một thẻ dòng lệnh mới, hãy xác minh rằng máy chủ MCP Toolbox đang chạy và hiển thị các công cụ của bạn qua điểm cuối 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. Định cấu hình ứng dụng MCP (Antigravity CLI)
Trong phần này, bạn sẽ cài đặt Antigravity CLI (agy) và định cấu hình để kết nối với máy chủ Hộp công cụ MCP.
Cài đặt Antigravity CLI
- Nếu bạn chưa cài đặt, hãy tải xuống và chạy trình cài đặt Antigravity CLI (
agy) rồi xác minh phiên bản: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
Định cấu hình Antigravity CLI
Thêm mục máy chủ MCP Toolbox vào tệp cấu hình MCP của ứng dụng khách (chẳng hạn như ~/.gemini/config/mcp_config.json cho Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json hoặc .mcp.json cho Claude Code).
- Để kết nối Antigravity CLI với máy chủ HTTP MCP Toolbox đang chạy trên cổng
5000, hãy chạyagy mcp addvà xác minh mục nhập bằngagy 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 listalloydb-omnivào~/.gemini/config/mcp_config.json:{ "mcpServers": { "alloydb-omni": { "url": "http://127.0.0.1:5000/mcp" } } }
Xác minh cấu hình
- Khởi động Antigravity CLI:
agyagy, hãy làm theo lời nhắc trên màn hình để đăng nhập (bằng Google OAuth hoặc dự án trên đám mây của Google Cloud) rồi chọn Yes, I trust this folder (Có, tôi tin tưởng thư mục này) khi được hỏi có tin tưởng thư mục hiện tại hay không. - Tại lời nhắc của Antigravity CLI, hãy nhập
/mcpđể mở bảng điều khiển Máy chủ MCP và xác minh rằngalloydb-omniđã kết nối:/mcpMCP 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
- Nhấn phím
Escđể đóng bảng điều khiển Máy chủ MCP và quay lại câu lệnh Antigravity CLI.
6. Kiểm thử bằng cách sử dụng truy vấn cho AlloyDB Omni
Giờ đây, khi Antigravity CLI đã kết nối với thực thể AlloyDB Omni thông qua MCP Toolbox, bạn có thể tương tác với cơ sở dữ liệu bằng cách sử dụng câu lệnh bằng ngôn ngữ tự nhiên.
Chạy truy vấn tổng quan về cơ sở dữ liệu
- Tại câu lệnh Antigravity CLI, hãy yêu cầu cung cấp thông tin tổng quan về cơ sở dữ liệu hiện tại:
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)
Ví dụ về bài kiểm tra theo danh mục
Đưa ra câu lệnh cho Antigravity CLI bằng các yêu cầu ngôn ngữ tự nhiên sau đây. Tác nhân sẽ tự động liên kết từng yêu cầu với công cụ tương ứng trong bộ công cụ AlloyDB Omni MCP:
1. Tổng quan và tình trạng cơ sở dữ liệu
Mục tiêu thử nghiệm | Câu lệnh bằng ngôn ngữ tự nhiên | Đã gọi công cụ |
Kiểm tra hệ thống |
|
|
Kết nối đang hoạt động |
|
|
Các tiện ích đã cài đặt |
|
|
Các tiện ích hiện có |
|
|
2. Khám phá giản đồ và danh mục
Mục tiêu thử nghiệm | Câu lệnh bằng ngôn ngữ tự nhiên | Đã gọi công cụ |
Liệt kê bảng |
|
|
Kiểm tra chỉ mục |
|
|
Khám phá các chế độ xem |
|
|
Kiểm tra trình kích hoạt bảng |
|
|
3. Truy vấn và lọc dữ liệu (execute_sql)
Mục tiêu thử nghiệm | Câu lệnh bằng ngôn ngữ tự nhiên | Đã gọi công cụ |
Truy vấn tổng hợp |
|
|
Truy vấn kết hợp |
|
|
Bản ghi không khớp |
|
|
4. Hiệu suất truy vấn và kế hoạch giải thích (get_query_plan)
Mục tiêu thử nghiệm | Câu lệnh bằng ngôn ngữ tự nhiên | Đã gọi công cụ |
Giải thích kế hoạch |
|
|
Xác minh chỉ mục |
|
|
5. Bảo trì và chẩn đoán cơ sở dữ liệu
Mục tiêu thử nghiệm | Câu lệnh bằng ngôn ngữ tự nhiên | Đã gọi công cụ |
Bảng phình to |
|
|
Tranh chấp khoá |
|
|
Chế độ cài đặt Autovacuum |
|
|
Chỉ mục không hợp lệ |
|
|
7. Dọn dẹp
Sau khi bạn hoàn tất lớp học lập trình, hãy dọn dẹp vùng chứa cục bộ và các quy trình bạn đã bắt đầu.
- Thoát khỏi Antigravity CLI bằng cách nhập
/quit(hoặc nhấnCtrl+Dhai lần). - Chuyển sang thẻ dòng lệnh đang chạy máy chủ MCP Toolbox rồi nhấn
Ctrl+Cđể dừng máy chủ. - Dừng và xoá vùng chứa Docker của AlloyDB Omni:
docker stop alloydbomni docker rm alloydbomni
8. Xin chúc mừng
Chúc mừng bạn đã hoàn thành lớp học lập trình! Bạn đã triển khai thành công AlloyDB Omni trong một vùng chứa, định cấu hình MCP Toolbox for Databases bằng bộ công cụ AlloyDB Omni tạo sẵn và tích hợp bộ công cụ này với Antigravity CLI để truy vấn và quản lý cơ sở dữ liệu bằng ngôn ngữ tự nhiên.
Nội dung bạn đã đề cập
- Cách triển khai và xác minh vùng chứa AlloyDB Omni bằng Docker.
- Cách điền dữ liệu vào bảng và chỉ mục mẫu để kiểm thử quy trình làm việc của tác nhân.
- Cách định cấu hình và chạy Bộ công cụ MCP cho cơ sở dữ liệu bằng cấu hình công cụ
alloydb-omnitạo sẵn. - Cách kết nối Antigravity CLI với Bộ công cụ MCP và chạy câu lệnh bằng ngôn ngữ tự nhiên để khám phá giản đồ, truy vấn SQL, phân tích kế hoạch truy vấn và chẩn đoán cơ sở dữ liệu.
Để biết thêm thông tin, hãy xem các tài nguyên sau: