In diesem Dokument wird beschrieben, wie Sie Ihre AlloyDB-Instanz mit verschiedenen Agents verbinden, die das Model Context Protocol (MCP) unterstützen.
Wir empfehlen, die dedizierte AlloyDB-Erweiterung für die Gemini CLI zu verwenden. Bei der Gemini CLI ist der zugrunde liegende MCP-Server direkt in die Erweiterung integriert, sodass Sie keine separate Servereinrichtung vornehmen müssen. Sie können Gemini Code Assist so konfigurieren, dass die Gemini-Befehlszeile verwendet wird. Das bietet ähnliche Einrichtungsvorteile in Ihrer IDE.
Alternativ können andere IDEs und Agents, die das MCP unterstützen, über die MCP Toolbox for Databases verbunden werden. Toolbox ist ein Open-Source-MCP-Server, der KI-Agents mit Ihren Daten verbindet. Sie übernimmt Aufgaben wie die Authentifizierung und das Connection Pooling, sodass Sie direkt über Ihre IDE in natürlicher Sprache mit Ihren Daten interagieren können.
Hinweise
Um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen und die verfügbaren Tools zu verwenden, benötigen Sie eine der folgenden IAM-Rollen (Identity and Access Management) oder eine benutzerdefinierte Rolle mit entsprechenden Berechtigungen:
| Aufgabe | Rollenname | Erforderliche IAM-Rolle (Identity and Access Management) |
|---|---|---|
| Schreibgeschützte Tools zum Auflisten und Abrufen von AlloyDB-Ressourcen verwenden | AlloyDB Viewer | roles/alloydb.viewer |
| Verbindung zu einer Instanz herstellen und Abfragen ausführen | Cloud AlloyDB-Client | roles/alloydb.client |
| Service Usage Consumer | roles/serviceusage.serviceUsageConsumer |
|
| Administrative Aufgaben ausführen, z. B. Cluster, Instanzen und Nutzer erstellen oder verwalten | AlloyDB Admin | roles/alloydb.admin |
| Observability-Erweiterung verwenden | Monitoring-Betrachter | roles/monitoring.viewer |
Bevor Sie eine Verbindung zu Ihrer AlloyDB-Instanz herstellen können, müssen Sie die folgenden Schritte ausführen, um Ihr Projekt und Ihre Datenbank einzurichten.
- 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Aktivieren Sie die Cloud APIs, die zum Erstellen einer Verbindung zu AlloyDB erforderlich sind.
Klicken Sie im Schritt Projekt bestätigen auf Weiter, um den Namen des Projekts zu bestätigen, an dem Sie Änderungen vornehmen möchten.
Klicken Sie im Schritt APIs aktivieren auf Aktivieren, um Folgendes zu aktivieren:
- AlloyDB API
- Compute Engine API
- Cloud Resource Manager API
- Service Networking API
Die Service Networking API ist erforderlich, wenn Sie die Netzwerkkonnektivität zu AlloyDB über ein VPC-Netzwerk konfigurieren möchten, das sich im selben Google Cloud Projekt wie AlloyDB befindet.
Die Compute Engine API und die Cloud Resource Manager API sind erforderlich, wenn Sie die Netzwerkverbindung zu AlloyDB über ein VPC-Netzwerk konfigurieren möchten, das sich in einem anderen Google Cloud -Projekt befindet.
- Cluster und primäre Instanz erstellen oder auswählen
- Konfigurieren Sie Standardanmeldedaten für Anwendungen (ADC) für Ihre Umgebung.
- Erstellen Sie einen Datenbanknutzer oder verwenden Sie einen vorhandenen. Halten Sie den Nutzernamen und das Passwort bereit.
- Eigenständiges Befehlszeilentool
- In Ihre IDE mit Gemini Code Assist integriert
- Installieren Sie die Gemini-Befehlszeile.
- Installieren Sie die AlloyDB-Erweiterung für die Gemini CLI aus dem GitHub-Repository mit dem folgenden Befehl:
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
- Legen Sie Umgebungsvariablen fest, um eine Verbindung zu Ihrer AlloyDB-Instanz herzustellen:
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"
Die Gemini CLI-Erweiterung für AlloyDB verwendet standardmäßig Ihre [Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC)](/authentication/application-default-credentials) für die Authentifizierung. Wenn Sie stattdessen als Datenbanknutzer eine Verbindung herstellen möchten, legen Sie die folgenden optionalen Umgebungsvariablen fest:
#Optional: Set for database user authentication export ALLOYDB_POSTGRES_USER="USERNAME" export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"
Wenn Sie eine Verbindung über eine private IP-Adresse herstellen möchten, müssen Sie auch die folgende Umgebungsvariable festlegen:
export ALLOYDB_POSTGRES_IP_TYPE="private"
- Starten Sie die Gemini CLI im interaktiven Modus:
gemini
- Prüfen Sie, ob die Gemini CLI und die
alloydb-Erweiterung installiert und konfiguriert sind. - Gemini Code Assist für die Verwendung der Gemini-Befehlszeile konfigurieren
- Sie können direkt im Gemini Code Assist-Chat in natürlicher Sprache mit Ihrer AlloyDB-Instanz interagieren.
Laden Sie die aktuelle Version der Toolbox als Binärdatei herunter. Wählen Sie die Binärdatei aus, die Ihrem Betriebssystem und Ihrer CPU-Architektur entspricht. Sie müssen mindestens die Toolbox-Version v0.15.0 verwenden.
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
Machen Sie die Binärdatei ausführbar.
chmod +x toolboxPrüfen Sie die Installation.
./toolbox --version- Installieren Sie Claude Code.
- Erstellen Sie die Datei
.mcp.jsonim Stammverzeichnis Ihres Projekts, falls sie noch nicht vorhanden ist. - Fügen Sie die Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
- Öffnen Sie Claude Desktop und rufen Sie die Einstellungen auf.
- Klicken Sie auf dem Tab Entwickler auf Konfiguration bearbeiten, um die Konfigurationsdatei zu öffnen.
- Fügen Sie die Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
- Starten Sie Claude Desktop neu.
- Auf dem neuen Chatbildschirm wird ein Hammersymbol (MCP) mit dem neuen MCP-Server angezeigt.
- Öffnen Sie die Cline-Erweiterung in VS Code und tippen Sie auf das Symbol MCP Servers (MCP-Server).
- Klicken Sie auf MCP-Server konfigurieren, um die Konfigurationsdatei zu öffnen.
- Fügen Sie die folgende Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
- Erstellen Sie das Verzeichnis
.cursorim Stammverzeichnis Ihres Projekts, falls es noch nicht vorhanden ist. - Erstellen Sie die Datei
.cursor/mcp.json, falls sie noch nicht vorhanden ist, und öffnen Sie sie. - Fügen Sie die folgende Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
- Öffnen Sie Cursor und gehen Sie zu Einstellungen > Cursoreinstellungen > MCP. Wenn der Server verbunden ist, wird ein grüner aktiver Status angezeigt.
- Öffnen Sie VS Code und erstellen Sie das Verzeichnis
.vscodeim Stammverzeichnis Ihres Projekts, falls es noch nicht vorhanden ist. - Erstellen Sie die Datei
.vscode/mcp.json, falls sie noch nicht vorhanden ist, und öffnen Sie sie. - Fügen Sie die folgende Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
- Öffnen Sie Windsurf und rufen Sie den Cascade-Assistenten auf.
- Klicken Sie auf das MCP-Symbol und dann auf Konfigurieren, um die Konfigurationsdatei zu öffnen.
- Fügen Sie die folgende Konfiguration hinzu, ersetzen Sie die Umgebungsvariablen durch Ihre Werte und speichern Sie die Datei.
Gemini CLI-Erweiterungen für AlloyDB verwenden
Gemini CLI ist ein Open-Source-KI-Agent, der Sie bei Entwicklungs-Workflows unterstützt, indem er Ihnen beim Programmieren, Debuggen, bei der Datenexploration und beim Erstellen von Inhalten hilft. Ziel ist es, eine Schnittstelle für die Interaktion mit Data Cloud-Diensten und beliebten Open-Source-Datenbanken bereitzustellen.
Die Integration in die Gemini CLI erfolgt über spezielle Erweiterungen, die im Vergleich zu einer Standardverbindung mit der MCP Toolbox zusätzliche Funktionen bieten. In den folgenden Abschnitten werden die Erweiterungen alloydb und alloydb-observability beschrieben, die einen Installationsprozess und eine Reihe von Tools bieten. Die Open-Source-Erweiterungen enthalten detaillierte Informationen zur Installation, Konfiguration und Anwendungsbeispiele. Weitere Informationen finden Sie unter Gemini CLI Extension – AlloyDB for PostgreSQL.
Die alloydb-Erweiterung enthält Tools zum Abfragen der Datenbank, zum Verwalten von AlloyDB-Ressourcen und zum Überwachen des Datenbankstatus.
| Kategorie | Tools | Beispiel für einen Prompt in natürlicher Sprache |
|---|---|---|
| Datenbankvorgänge |
list_tables |
Zeige mir alle Tabellen in der aktuellen Datenbank. |
execute_sql |
Führen Sie die Abfrage aus: SELECT * FROM products WHERE category = 'electronics'; | |
list_active_queries |
Welche Abfragen werden in der Datenbank ausgeführt? | |
get_query_plan |
Erkläre den Abfrageplan für „SELECT * FROM customers WHERE last_seen > '2025-08-01'“ | |
list_available_extensions |
Welche Erweiterungen kann ich installieren? | |
list_installed_extensions |
Alle installierten Erweiterungen auflisten. | |
| Ressourcenverwaltung Cluster, Instanzen, Nutzer |
create_cluster |
Erstellen Sie einen AlloyDB-Cluster mit dem Namen sales-quarterly-db in der Region us-east1. |
get_cluster |
Rufen Sie die Details für den Cluster sales-quarterly-db ab. |
|
list_clusters |
Liste alle meine AlloyDB-Cluster auf. | |
create_instance |
Erstellen Sie eine neue Leseinstanz im Cluster sales-quarterly-db. |
|
get_instance |
Zeige mir die Informationen für die Instanz sales-quarterly-db-rp. |
|
list_instances |
Alle Instanzen im Cluster sales-quarterly-db auflisten |
|
create_user |
Erstellen Sie einen neuen Datenbanknutzer mit dem Namen reporting_user. |
|
get_user |
Rufen Sie die Informationen für den Nutzer reporting_user ab. |
|
list_users |
Alle Datenbanknutzer auflisten | |
wait_for_operation |
Welchen Status hat der Vorgang operation-163562789? |
|
| Datenbankstatus und ‑wartung | list_autovacuum_configurations |
Zeige mir die aktuelle Autovacuum-Konfiguration. |
list_memory_configurations |
Welche Speicherkonfigurationen gibt es derzeit für die primäre Instanz? | |
list_top_bloated_tables |
Liste die fünf Tabellen mit den meisten Daten auf. | |
list_replication_slots |
Alle aktiven Replikations-Slots anzeigen. | |
list_invalid_indexes |
Prüfen Sie, ob in der orders-Datenbank ungültige Indexe vorhanden sind. |
Die alloydb-observability-Erweiterung bietet eine einheitliche Oberfläche zum Verwalten und Überwachen der Datenbankleistung und des Datenbankzustands direkt über die Gemini-Befehlszeile.
| Kategorie | Tools | Beispiel für einen Prompt in natürlicher Sprache |
|---|---|---|
| Beobachtbarkeit | get_system_metrics |
Wie lauten die Systemmesswerte, z. B. die CPU-Auslastung, für die letzte Stunde? |
get_query_metrics |
Zeige mir die Messwerte zur Abfrageleistung der letzten 15 Minuten. |
Sie haben zwei Möglichkeiten, die Gemini CLI-Erweiterung für AlloyDB zu verwenden:
Gemini-Befehlszeile
Gemini Code Assist
Wir empfehlen, Gemini Code Assist so zu konfigurieren, dass die Gemini CLI verwendet wird. Bei diesem Ansatz ist es nicht erforderlich, einen MCP-Server manuell zu konfigurieren.
Verbindung zu anderen IDEs über die MCP Toolbox for Databases herstellen
In diesem Abschnitt wird beschrieben, wie Sie mit der MCP Toolbox for Databases eine Verbindung zu Ihrer AlloyDB-Instanz von verschiedenen Agents aus herstellen. Die Toolbox fungiert als Open-Source-MCP-Server (Model Context Protocol), der sich zwischen Ihrer IDE und Ihrer Datenbank befindet und eine Steuerungsebene für Ihre KI-Tools bietet. In diesem Abschnitt finden Sie eine Anleitung zum Herstellen einer Verbindung zu einer AlloyDB-Instanz über eine öffentliche oder private IP-Adresse. Standardmäßig verwendet Toolbox eine öffentliche IP-Adresse. Sie können jedoch eine private IP-Verbindung konfigurieren, indem Sie die Umgebungsvariable ALLOYDB_POSTGRES_IP_TYPE festlegen, wie in den Konfigurationsbeispielen gezeigt.
MCP-Toolbox für Datenbanken installieren
Wenn Sie Ihre IDE mit AlloyDB verbinden möchten, müssen Sie die MCP Toolbox for Databases installieren. Das ist ein Open-Source-Server, der KI-Agents mit Ihren Daten verbindet.
Client konfigurieren
Wählen Sie das gewünschte Agent-Tool aus den folgenden Optionen aus:
Claude-Code
{
"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 für Computer
{
"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"
}
}
}
}
Cline
{
"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"
}
}
}
}
Nachdem der Server erfolgreich verbunden wurde, wird ein grüner aktiver Status angezeigt.
Cursor
{
"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"
}
}
}
}
Visual Studio Code (Copilot)
{
"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"
}
}
}
}
Windsurfen
{
"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"
}
}
}
}