Menggunakan AlloyDB untuk PostgreSQL dengan MCP, Gemini CLI, dan agen lainnya

Dokumen ini menjelaskan cara menghubungkan instance AlloyDB Anda ke berbagai agen yang mendukung Model Context Protocol (MCP).

Sebaiknya gunakan ekstensi AlloyDB khusus untuk Gemini CLI. Gemini CLI mengintegrasikan server MCP pokok langsung ke dalam ekstensi, sehingga Anda tidak perlu melakukan penyiapan server terpisah. Anda dapat mengonfigurasi Gemini Code Assist untuk menggunakan Gemini CLI, yang menawarkan manfaat penyiapan serupa di IDE Anda.

Atau, IDE dan agen lain yang mendukung MCP dapat terhubung melalui MCP Toolbox for Databases. Toolbox adalah server MCP open source yang dirancang untuk menghubungkan agen AI ke data Anda. Alat ini menangani tugas seperti autentikasi dan penggabungan koneksi, sehingga Anda dapat berinteraksi dengan data menggunakan bahasa natural langsung dari IDE.

Sebelum memulai

Untuk terhubung ke instance AlloyDB dan menggunakan alat yang tersedia, Anda harus memiliki salah satu peran Identity and Access Management (IAM) berikut, atau peran kustom dengan izin yang setara:

Tugas	Nama peran	Peran Identity and Access Management (IAM) yang diperlukan
Menggunakan alat hanya baca untuk mencantumkan dan mendapatkan resource AlloyDB	Pelihat AlloyDB	roles/alloydb.viewer
Menghubungkan ke instance dan menjalankan kueri	Klien AlloyDB Cloud	roles/alloydb.client
	Service Usage Consumer	roles/serviceusage.serviceUsageConsumer
Melakukan tugas administratif (seperti membuat atau mengelola cluster, instance, dan pengguna)	Admin AlloyDB	roles/alloydb.admin
Menggunakan ekstensi kemampuan observasi	Penampil Pemantauan	roles/monitoring.viewer

Sebelum Anda dapat terhubung ke instance AlloyDB, selesaikan langkah-langkah berikut untuk menyiapkan project dan database Anda.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Aktifkan Cloud API yang diperlukan untuk membuat dan terhubung ke AlloyDB.

   Aktifkan API

   1. Pada langkah Confirm project, klik Next untuk mengonfirmasi nama project yang akan Anda ubah.

   2. Pada langkah Enable APIs, klik Enable untuk mengaktifkan berikut ini:

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

      Service Networking API diperlukan jika Anda berencana mengonfigurasi konektivitas jaringan ke AlloyDB menggunakan jaringan VPC yang berada di project yang sama Google Cloud dengan AlloyDB.

      Compute Engine API dan Cloud Resource Manager API diperlukan jika Anda berencana mengonfigurasi konektivitas jaringan ke AlloyDB menggunakan jaringan VPC yang berada di project Google Cloud lain.

2. Buat atau pilih cluster dan instance utamanya.
3. Konfigurasi Kredensial Default Aplikasi (ADC) untuk lingkungan Anda.
4. Buat atau gunakan kembali pengguna database. Siap untuk memasukkan nama pengguna dan sandi.

Menggunakan ekstensi Gemini CLI untuk AlloyDB

Catatan: Ekstensi AlloyDB Gemini CLI didasarkan pada MCP Toolbox for Databases. MCP Toolbox for Databases saat ini dalam versi beta (pra-v1.0), dan mungkin mengalami perubahan yang dapat menyebabkan gangguan hingga rilis stabil pertama (v1.0).

Gemini CLI adalah agen AI open source yang dirancang untuk membantu alur kerja pengembangan dengan membantu coding, proses debug, eksplorasi data, dan pembuatan konten. Misi ini adalah menyediakan antarmuka agentik untuk berinteraksi dengan layanan Data Cloud dan database open source populer.

Integrasi dengan Gemini CLI dilakukan melalui ekstensi khusus yang menawarkan kemampuan tambahan dibandingkan dengan koneksi MCP Toolbox standar. Bagian berikut menjelaskan ekstensi alloydb dan alloydb-observability, yang menawarkan proses penginstalan dan serangkaian alat. Ekstensi open source ini berisi informasi mendetail tentang penginstalan, konfigurasi, dan contoh penggunaan. Untuk mengetahui informasi selengkapnya, lihat Ekstensi CLI Gemini - AlloyDB untuk PostgreSQL.

Ekstensi alloydb mencakup alat untuk membuat kueri database, mengelola resource AlloyDB, dan memantau kondisi database.

Kategori	Alat	Contoh perintah bahasa alami
Operasi database	list_tables	Tampilkan semua tabel dalam database saat ini.
	execute_sql	Jalankan kueri: SELECT * FROM products WHERE category = 'electronics';
	list_active_queries	Kueri apa yang berjalan di database?
	get_query_plan	Jelaskan rencana kueri untuk "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
	list_available_extensions	Apa saja ekstensi yang tersedia yang dapat saya instal?
	list_installed_extensions	Mencantumkan semua ekstensi yang diinstal.
Pengelolaan resource cluster, instance, pengguna	create_cluster	Buat cluster AlloyDB bernama sales-quarterly-db di region us-east1.
	get_cluster	Dapatkan detail untuk cluster sales-quarterly-db.
	list_clusters	Mencantumkan semua cluster AlloyDB saya.
	create_instance	Buat instance baca baru di cluster sales-quarterly-db.
	get_instance	Tampilkan informasi untuk instance sales-quarterly-db-rp.
	list_instances	Mencantumkan semua instance di cluster sales-quarterly-db.
	create_user	Buat pengguna database baru bernama reporting_user.
	get_user	Dapatkan informasi untuk pengguna reporting_user.
	list_users	Mencantumkan semua pengguna database.
	wait_for_operation	Apa status operasi operation-163562789?
Kesehatan & pemeliharaan database	list_autovacuum_configurations	Tunjukkan konfigurasi autovacuum saat ini.
	list_memory_configurations	Apa konfigurasi memori saat ini untuk instance utama?
	list_top_bloated_tables	Mencantumkan lima tabel yang paling membengkak.
	list_replication_slots	Menampilkan semua slot replikasi aktif.
	list_invalid_indexes	Periksa apakah ada indeks yang tidak valid dalam database orders.

Ekstensi alloydb-observability menyediakan antarmuka terpadu untuk mengelola dan memantau performa dan kondisi database langsung dari Gemini CLI.

Kategori	Alat	Contoh perintah bahasa alami
Kemampuan observasi	get_system_metrics	Berapa metrik sistem, seperti penggunaan CPU, untuk satu jam terakhir?
	get_query_metrics	Tampilkan metrik performa kueri dari 15 menit terakhir.

Anda dapat menggunakan ekstensi Gemini CLI untuk AlloyDB dengan dua cara:

• Alat command line mandiri
• Terintegrasi ke dalam IDE Anda dengan Gemini Code Assist

Gemini CLI

1. Instal Gemini CLI.
2. Instal ekstensi AlloyDB untuk Gemini CLI dari repositori GitHub menggunakan perintah berikut:

   gemini extensions install https://github.com/gemini-cli-extensions/alloydb
   

3. Tetapkan variabel lingkungan untuk terhubung ke instance AlloyDB Anda:

   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"
   

   Ekstensi Gemini CLI untuk AlloyDB menggunakan [kredensial default aplikasi (ADC)](/authentication/application-default-credentials) Anda untuk autentikasi secara default. Jika Anda ingin terhubung sebagai pengguna database, tetapkan variabel lingkungan opsional berikut:

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

   Untuk terhubung menggunakan alamat IP pribadi, Anda juga harus menetapkan variabel lingkungan berikut:

   export ALLOYDB_POSTGRES_IP_TYPE="private"
   

4. Mulai Gemini CLI dalam mode interaktif:

   gemini
   

   CLI akan otomatis memuat ekstensi AlloyDB untuk ekstensi Gemini CLI dan alatnya, yang dapat Anda gunakan untuk berinteraksi dengan database Anda.

Gemini Code Assist

Sebaiknya konfigurasi Gemini Code Assist agar menggunakan Gemini CLI. Pendekatan ini menghilangkan kebutuhan untuk mengonfigurasi server MCP secara manual.

1. Pastikan Anda telah menginstal dan mengonfigurasi Gemini CLI dan ekstensi alloydb.
2. Konfigurasi Gemini Code Assist untuk menggunakan Gemini CLI.
3. Mulai berinteraksi dengan instance AlloyDB Anda menggunakan bahasa alami langsung dalam chat Gemini Code Assist.

Terhubung dengan IDE lain menggunakan MCP Toolbox for Databases

Bagian ini menjelaskan cara terhubung ke instance AlloyDB Anda dari berbagai agen menggunakan MCP Toolbox for Databases. Toolbox bertindak sebagai server Model Context Protocol (MCP) open source yang berada di antara IDE dan database Anda, sehingga menyediakan bidang kontrol untuk alat AI Anda. Bagian ini memberikan petunjuk untuk terhubung ke instance AlloyDB menggunakan alamat IP publik atau pribadi. Secara default, Toolbox menggunakan alamat IP publik, tetapi Anda dapat mengonfigurasi koneksi IP pribadi dengan menyetel variabel lingkungan ALLOYDB_POSTGRES_IP_TYPE seperti yang ditunjukkan dalam contoh konfigurasi.

Menginstal MCP Toolbox for Databases

Untuk menghubungkan IDE Anda ke AlloyDB, Anda harus menginstal MCP Toolbox for Databases, server open source yang menghubungkan agen AI ke data Anda.

1. Download Toolbox versi terbaru sebagai biner. Pilih biner yang sesuai dengan sistem operasi (OS) dan arsitektur CPU Anda. Anda harus menggunakan Toolbox versi v0.15.0 atau yang lebih baru.

   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. Jadikan biner sebagai file yang dapat dieksekusi.

   chmod +x toolbox
   

3. Verifikasi penginstalannya.

   ./toolbox --version
   

Mengonfigurasi klien Anda

Pilih alat agen Anda dari opsi berikut:

Kode Claude

1. Instal Claude Code.
2. Buat file .mcp.json di root project Anda, jika belum ada.
3. Tambahkan konfigurasi, ganti variabel lingkungan dengan nilai Anda, lalu simpan.




{
  "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"
      }
    }
  }
}

Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Claude desktop

1. Buka Claude Desktop, lalu buka Settings.
2. Di tab Developer, klik Edit Config untuk membuka file konfigurasi.
3. Tambahkan konfigurasi, ganti variabel lingkungan dengan nilai Anda, lalu simpan.




{
  "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"
      }
    }
  }
}

Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Mulai ulang Claude Desktop.
5. Layar chat baru menampilkan ikon palu (MCP) dengan server MCP baru.

Cline

1. Buka ekstensi Cline di VS Code, lalu ketuk ikon MCP Servers.
2. Klik Configure MCP Servers untuk membuka file konfigurasi.
3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan.




{
  "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"
      }
    }
  }
}


Status aktif hijau akan muncul setelah server berhasil terhubung.



Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Kursor

1. Buat direktori .cursor di root project Anda jika belum ada.
2. Buat file .cursor/mcp.json jika tidak ada, lalu buka.
3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan.

{
  "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"
      }
    }
  }
}

Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Buka Kursor, lalu buka Setelan > Setelan Kursor > MCP. Status aktif berwarna hijau akan muncul saat server terhubung.

Visual Studio Code (Copilot)

1. Buka VS Code dan buat direktori .vscode di root project Anda jika belum ada.
2. Buat file .vscode/mcp.json jika tidak ada, lalu buka.
3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan.

{
  "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"
      }
    }
  }
}

Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Windsurf

1. Buka Windsurf dan buka asisten Cascade.
2. Klik ikon MCP, lalu klik Configure untuk membuka file konfigurasi.
3. Tambahkan konfigurasi berikut, ganti variabel lingkungan dengan nilai Anda, lalu simpan.

{
  "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"
      }
    }
  }
}

Catatan: Untuk terhubung menggunakan alamat IP pribadi, tambahkan baris berikut ke objek env: "ALLOYDB_POSTGRES_IP_TYPE": "private"