Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menggunakan AlloyDB Omni dengan MCP Toolbox untuk integrasi agen

1. Pengantar

Untuk memberi agen AI—seperti Antigravity CLI—akses yang aman dan terstruktur ke database Anda, Anda dapat mengintegrasikan AlloyDB Omni dengan MCP Toolbox for Databases.

AlloyDB Omni adalah edisi AlloyDB untuk PostgreSQL dalam container yang dapat didownload dan dirancang untuk berjalan di mana saja—di infrastruktur lokal, di workstation developer, di edge, atau di cloud—sekaligus memberikan performa dan kompatibilitas PostgreSQL tingkat perusahaan.

MCP Toolbox for Databases adalah server open source dari Google yang mengimplementasikan Model Context Protocol (MCP) untuk mempermudah, mempercepat, dan mengamankan pembuatan alat AI generatif yang berinteraksi dengan database. Alat ini berada di antara framework orkestrasi agen dan database Anda, serta menyediakan kemampuan berikut:

Pengembangan yang disederhanakan: Alat database bawaan atau kustom yang terhubung ke agen Anda dengan konfigurasi minimal dan dapat digunakan kembali di beberapa agen atau framework.
Performa yang lebih baik: Praktik terbaik bawaan seperti penggabungan koneksi dan pengelolaan siklus proses.
Keamanan yang ditingkatkan: Pengelolaan kredensial dan autentikasi terpusat sehingga agen tidak memerlukan kredensial database mentah.
Kemampuan observasi menyeluruh: Metrik dan pelacakan siap pakai dengan dukungan bawaan untuk OpenTelemetry.

Di akhir codelab ini, Anda akan memiliki container AlloyDB Omni yang berjalan dan diisi dengan data e-commerce contoh, server MCP Toolbox yang mengekspos 31 alat administrasi dan kueri AlloyDB Omni bawaan, serta agen Antigravity CLI (agy) yang dikonfigurasi dan mampu memeriksa skema, menjalankan kueri SQL, menganalisis rencana kueri, dan mendiagnosis kondisi database menggunakan perintah bahasa alami.

Diagram arsitektur yang menunjukkan alur kerja menyeluruh dari Agen ke Klien MCP (Antigravity CLI) ke MCP Toolbox ke AlloyDB Omni

Prasyarat

Akses ke project Google Cloud dan Cloud Shell dari konsol Google Cloud, atau workstation Linux.
Docker diinstal dan berjalan.
Klien PostgreSQL psql telah diinstal.
curl dan jq diinstal untuk menyiapkan Antigravity CLI dan MCP Toolbox.

Yang akan Anda pelajari

Cara men-deploy dan menjalankan container server database AlloyDB Omni menggunakan Docker.
Cara membuat tabel, data, dan indeks contoh di AlloyDB Omni.
Cara mendownload, mengonfigurasi, dan memulai MCP Toolbox for Databases dengan set alat alloydb-omni bawaan.
Cara mengonfigurasi Antigravity CLI sebagai klien MCP untuk terhubung ke server MCP Toolbox.
Cara menggunakan perintah bahasa alami di Antigravity CLI untuk memeriksa kondisi database, menjelajahi skema, menjalankan kueri SQL, menganalisis rencana kueri, dan melakukan diagnostik pemeliharaan.

Yang Anda butuhkan

Lingkungan terminal yang berfungsi dengan Docker, psql, curl, dan jq. Anda dapat menggunakan Google Cloud Shell, yang telah diinstal sebelumnya dengan alat ini.

2. Penyiapan dan persyaratan

Penyiapan project

Membuat project Google Cloud

Di Konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan untuk project Google Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Meskipun Anda dapat menjalankan AlloyDB Omni dan MCP Toolbox secara lokal di laptop, dalam codelab ini, Anda dapat menggunakan Google Cloud Shell, lingkungan command line yang berjalan di cloud dan telah dilengkapi dengan Docker, psql, curl, dan jq.

Ikon untuk mengaktifkan Cloud Shell

Buka Konsol Google Cloud dan klik Activate Cloud Shell di toolbar kanan atas.Anda juga dapat membuka Cloud Shell dengan salah satu cara berikut:
- Jika Anda menggunakan Konsol Google Cloud, tekan G, lalu S.
- Buka Cloud Shell secara langsung.

Biasanya, perlu waktu beberapa saat untuk menyediakan dan terhubung ke lingkungan. Setelah operasi ini selesai, Anda akan melihat tampilan yang mirip dengan berikut ini:

Terminal Google Cloud Shell yang menunjukkan bahwa lingkungan telah terhubung

3. Menyiapkan dan menjalankan server database AlloyDB Omni

Di bagian ini, Anda akan mengambil dan menjalankan container Docker AlloyDB Omni dan mengisinya dengan data e-commerce sampel untuk pengujian.

Memulai server database AlloyDB Omni

Tentukan variabel lingkungan untuk host, port, database, pengguna, dan sandi yang dihasilkan 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"

Mulai container AlloyDB Omni dalam mode terpisah menggunakan Docker:

docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest

Pastikan container berjalan dan Anda dapat terhubung ke server AlloyDB Omni menggunakan 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;"

Membuat data sampel untuk pengujian

Buat tabel contoh categories, products, customers, dan orders, sisipkan data pengujian, dan buat indeks agar Anda dapat menguji pemeriksaan skema, kueri SQL, dan rencana eksekusi kueri melalui 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. Memulai server MCP Toolbox

Di bagian ini, Anda akan mendownload biner MCP Toolbox, mengonfigurasi definisi alat AlloyDB Omni bawaan, dan memulai server MCP Toolbox.

Mendownload MCP Toolbox

Buat direktori untuk MCP Toolbox dan download biner 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

Mengonfigurasi dan memulai server MCP Toolbox

Download konfigurasi alat alloydb-omni.yaml bawaan dan mulai server MCP Toolbox di port 5000 (menggunakan variabel lingkungan ALLOYDB_OMNI_* yang diekspor sebelumnya):
```
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
```
Konfigurasi alloydb-omni.yaml menyediakan 31 alat bawaan, termasuk alat utama yang ditunjukkan dalam codelab ini:
- 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
Untuk mengetahui daftar lengkap alat, lihat alloydb-omni.yaml di GitHub.
Tips: Biarkan server MCP Toolbox tetap berjalan di tab terminal ini, dan buka tab terminal baru (+ di Cloud Shell) untuk menjalankan perintah yang tersisa di codelab ini.

Di tab terminal baru, verifikasi bahwa server MCP Toolbox berjalan dan mengekspos alat Anda melalui endpoint /mcp JSON-RPC:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. Mengonfigurasi klien MCP (Antigravity CLI)

Di bagian ini, Anda akan menginstal Antigravity CLI (agy) dan mengonfigurasinya untuk terhubung ke server MCP Toolbox Anda.

Menginstal Antigravity CLI

Jika belum diinstal, download dan jalankan penginstal Antigravity CLI (agy) dan verifikasi versinya:

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

Mengonfigurasi Antigravity CLI

Tambahkan entri server MCP Toolbox ke file konfigurasi MCP klien Anda (seperti ~/.gemini/config/mcp_config.json untuk Antigravity CLI, .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json, atau .mcp.json untuk Claude Code).

Untuk menghubungkan Antigravity CLI ke server HTTP MCP Toolbox yang berjalan di port 5000, jalankan agy mcp add dan verifikasi entri dengan 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

Tindakan ini akan menulis konfigurasi server alloydb-omni ke ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

Memverifikasi konfigurasi

Mulai Antigravity CLI:
```
agy
```
Jika ini pertama kalinya Anda meluncurkan agy, ikuti perintah di layar untuk login (dengan Google OAuth atau project cloud Google) dan pilih Yes, I trust this folder saat ditanya apakah akan memercayai direktori saat ini.

Di prompt Antigravity CLI, masukkan /mcp untuk membuka panel MCP Servers dan verifikasi bahwa alloydb-omni terhubung:

/mcp

Outputnya mirip dengan berikut ini:

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

Tekan Esc untuk menutup panel MCP Servers dan kembali ke prompt CLI Antigravity.

6. Menguji menggunakan kueri untuk AlloyDB Omni

Setelah Antigravity CLI terhubung ke instance AlloyDB Omni melalui MCP Toolbox, Anda dapat berinteraksi dengan database menggunakan perintah bahasa alami.

Menjalankan kueri ringkasan database

Di prompt Antigravity CLI, minta ringkasan database saat ini:

Give me an overview of the current database.

Saat diminta untuk mengizinkan pemanggilan alat, pilih Ya (atau Ya, dan selalu izinkan dalam percakapan ini). Outputnya mirip dengan hal berikut ini:

> 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)

Contoh pengujian menurut kategori

Berikan perintah berikut kepada Antigravity CLI menggunakan bahasa alami. Agen akan otomatis memetakan setiap permintaan ke alat yang sesuai dalam toolset MCP AlloyDB Omni Anda:

1. Ringkasan dan kondisi database

Sasaran pengujian	Perintah bahasa alami	Alat dipanggil
Pemeriksaan sistem	`Give me an overview of the current database.`	`database_overview`
Koneksi aktif	`What queries are currently running on the database?`	`list_active_queries`
Ekstensi yang diinstal	`What extensions are installed in this database?`	`list_installed_extensions`
Ekstensi yang tersedia	`What extensions are available that I can install?`	`list_available_extensions`

2. Eksplorasi skema dan katalog

Sasaran pengujian	Perintah bahasa alami	Alat dipanggil
Mencantumkan tabel	`Show me all the tables in the current database.`	`list_tables`
Memeriksa indeks	`List all indexes in the database and which tables they belong to.`	`list_indexes`
Menjelajahi tampilan	`What views are available in the public schema?`	`list_views`
Memeriksa pemicu tabel	`Show me the triggers defined on the orders table.`	`list_triggers`

3. Pembuatan kueri dan pemfilteran data (`execute_sql`)

Sasaran pengujian	Perintah bahasa alami	Alat dipanggil
Kueri gabungan	`Show me the 3 most expensive products in the 'Laptops' category.`	`execute_sql`
Kueri gabungan	`Find all customers who have placed an order in the last 6 months.`	`execute_sql`
Data yang tidak cocok	`Which customers haven't placed any orders yet?`	`execute_sql`

4. Performa kueri dan rencana penjelasan (`get_query_plan`)

Sasaran pengujian	Perintah bahasa alami	Alat dipanggil
Explain 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`
Verifikasi indeks	`Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.`	`get_query_plan`

5. Pemeliharaan dan diagnostik database

Sasaran pengujian	Perintah bahasa alami	Alat dipanggil
Pembengkakan tabel	`List the top five most bloated tables.`	`list_top_bloated_tables`
Pertentangan kunci	`Show me if there are any active locks or blocked transactions.`	`list_locks`
Setelan autovacuum	`Show me the current autovacuum configuration.`	`list_autovacuum_configurations`
Indeks tidak valid	`Check for any invalid indexes in the database.`	`list_invalid_indexes`

7. Pembersihan

Setelah Anda menyelesaikan codelab, bersihkan container lokal dan proses yang Anda mulai.

Keluar dari Antigravity CLI dengan mengetik /quit (atau menekan Ctrl+D dua kali).
Beralihlah ke tab terminal yang menjalankan server MCP Toolbox, lalu tekan Ctrl+C untuk menghentikannya.
Hentikan dan hapus container Docker AlloyDB Omni:
```
docker stop alloydbomni
docker rm alloydbomni
```

8. Selamat

Selamat, Anda telah menyelesaikan codelab. Anda berhasil men-deploy AlloyDB Omni dalam container, mengonfigurasi MCP Toolbox for Databases dengan toolset AlloyDB Omni bawaan, dan mengintegrasikannya dengan Antigravity CLI untuk membuat kueri dan mengelola database Anda menggunakan bahasa alami.

Yang telah Anda bahas

Cara men-deploy dan memverifikasi container AlloyDB Omni menggunakan Docker.
Cara mengisi tabel dan indeks sampel untuk menguji alur kerja agen.
Cara mengonfigurasi dan menjalankan MCP Toolbox for Databases dengan konfigurasi alat alloydb-omni bawaan.
Cara menghubungkan Antigravity CLI ke MCP Toolbox dan menjalankan perintah bahasa alami untuk penemuan skema, kueri SQL, analisis rencana kueri, dan diagnostik database.

Untuk informasi selengkapnya, lihat referensi berikut:

9. Survei

Bagaimana Anda akan menggunakan tutorial ini?

Hanya membacanya

Membaca dan menyelesaikan latihannya