Utilizzare AlloyDB per PostgreSQL con MCP, Gemini CLI e altri agenti

Questo documento descrive come connettere l'istanza AlloyDB a vari agenti che supportano il Model Context Protocol (MCP).

Ti consigliamo di utilizzare l'estensione AlloyDB dedicata per Gemini CLI. Gemini CLI integra il server MCP sottostante direttamente nell'estensione, quindi non è necessario eseguire una configurazione separata del server. Puoi configurare Gemini Code Assist per utilizzare Gemini CLI, che offre vantaggi di configurazione simili nel tuo IDE.

In alternativa, altri IDE e agenti che supportano MCP possono connettersi tramite MCP Toolbox for Databases. Toolbox è un server MCP open source progettato per connettere gli agenti AI ai tuoi dati. Gestisce attività come l'autenticazione e il raggruppamento delle connessioni, consentendoti di interagire con i tuoi dati con il linguaggio naturale direttamente dal tuo IDE.

Prima di iniziare

Per connetterti all'istanza AlloyDB e utilizzare gli strumenti disponibili, devi disporre di uno dei seguenti ruoli Identity and Access Management (IAM) o di un ruolo personalizzato con autorizzazioni equivalenti:

Attività	Nome ruolo	Ruolo Identity and Access Management (IAM) richiesto
Utilizzare strumenti di sola lettura per elencare e recuperare le risorse AlloyDB	AlloyDB Viewer	roles/alloydb.viewer
Connettersi a un'istanza ed eseguire query	Cloud AlloyDB Client	roles/alloydb.client
	Service Usage Consumer	roles/serviceusage.serviceUsageConsumer
Eseguire attività amministrative (come la creazione o la gestione di cluster, istanze e utenti)	AlloyDB Admin	roles/alloydb.admin
Utilizzare l'estensione di osservabilità	Monitoring Viewer	roles/monitoring.viewer

Prima di poterti connettere all'istanza AlloyDB, completa i seguenti passaggi per configurare il progetto e il database.

1. 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 role (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

2. Verify that billing is enabled for your Google Cloud project.

3. Abilita le API Cloud necessarie per creare e connetterti ad AlloyDB.

   Abilita le API

   1. Nel passaggio Conferma progetto, fai clic su Avanti per confermare il nome del progetto a cui apporterai le modifiche.

   2. Nel passaggio Abilita API, fai clic su Abilita per abilitare quanto segue:

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

      L'API Service Networking è necessaria se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova nello stesso progetto Google Cloud di AlloyDB.

      L'API Compute Engine e l'API Cloud Resource Manager sono necessarie se prevedi di configurare la connettività di rete ad AlloyDB utilizzando una rete VPC che si trova in un progetto Google Cloud diverso.

4. Crea o seleziona un cluster e la relativa istanza principale.
5. Configura le Credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
6. Crea o riutilizza un utente del database. Tieni a portata di mano nome utente e password.

Utilizzare le estensioni Gemini CLI per AlloyDB

Nota :l'estensione Gemini CLI per AlloyDB si basa su MCP Toolbox for Databases. MCP Toolbox for Databases è attualmente in versione beta (pre-v1.0) e potrebbe subire modifiche che causano interruzioni fino alla prima release stabile (v1.0).

Gemini CLI è un agente AI open source progettato per assistere i workflow di sviluppo aiutando con la programmazione, il debug, l'esplorazione dei dati e la creazione di contenuti. La sua missione è fornire un'interfaccia di agente per interagire con i servizi Data Cloud e i database open source più diffusi.

L'integrazione con Gemini CLI avviene tramite estensioni dedicate che offrono funzionalità aggiuntive rispetto a una connessione MCP Toolbox standard. Le sezioni seguenti descrivono le estensioni alloydb e alloydb-observability, che offrono un processo di installazione e un insieme di strumenti. Le estensioni open source contengono informazioni dettagliate su installazione, configurazione ed esempi di utilizzo. Per saperne di più, consulta l'estensione Gemini CLI - AlloyDB per PostgreSQL.

Estensione AlloyDB

L'estensione alloydb include strumenti per eseguire query sul database, gestire le risorse AlloyDB e monitorare l'integrità del database.

Gli esempi riportati di seguito utilizzano un database ecommerce di esempio con le seguenti tabelle:

• products: contiene informazioni sul prodotto, tra cui product_id, product_name, category e price.
• customers: memorizza i dati dei clienti, ad esempio customer_id, first_name, last_name e email.
• orders: contiene le informazioni sull'ordine, tra cui order_id, customer_id e order_date.

Categoria	Strumenti	Esempio di prompt in linguaggio naturale
Operazioni del database	database_overview	Dammi una panoramica del database attuale.
	list_tables	Mostrami tutte le tabelle nel database corrente.
	execute_sql	Mostrami i 10 prodotti più costosi nella categoria "Laptop".
	list_active_queries	Quali query vengono eseguite sul database?
	get_query_plan	Spiega il piano di esecuzione di una query che trova tutti i clienti che non hanno effettuato un ordine negli ultimi 6 mesi.
	list_available_extensions	Quali sono le estensioni disponibili che posso installare?
	list_installed_extensions	Elenca tutte le estensioni installate.
	list_indexes	Elenca tutti gli indici nella tabella products.
	list_locks	Mostra tutti i blocchi attivi sul database.
	list_schemas	Elenca tutti gli schemi nel database.
	list_sequences	Mostra tutte le sequenze nello schema corrente.
	list_triggers	Elenca tutti i trigger per la tabella orders.
	list_views	Mostrami tutte le visualizzazioni nello schema sales.
Gestione delle risorse cluster, istanze, utenti	create_cluster	Crea un cluster AlloyDB denominato sales-quarterly-db nella regione us-east1.
	get_cluster	Recupera i dettagli del cluster sales-quarterly-db.
	list_clusters	Elenca tutti i miei cluster AlloyDB.
	create_instance	Crea una nuova istanza di lettura nel cluster sales-quarterly-db.
	get_instance	Mostrami le informazioni per l'istanza sales-quarterly-db-rp.
	list_instances	Elenca tutte le istanze nel cluster sales-quarterly-db.
	create_user	Nota:lo strumento create_user può creare due tipi di utenti del database: Utenti del database con autenticazione integrata: questi utenti vengono gestiti all'interno del database ed eseguono l'autenticazione con una password. Utenti IAM: questi utenti vengono gestiti in IAM e si autenticano utilizzando le proprie credenziali IAM. Quando crei un utente del database con l'autenticazione integrata, devi fornire una password. Quando crei un utente IAM, devi fornire l'entità IAM. Crea un nuovo utente del database denominato reporting_user con password report_password. Crea un nuovo utente di database IAM per [e-mail].
	get_user	Recupera le informazioni per l'utente reporting_user.
	list_users	Elenca tutti gli utenti del database.
	wait_for_operation	Qual è lo stato dell'operazione operation-163562789?
Integrità e manutenzione del database	list_autovacuum_configurations	Mostrami la configurazione attuale di autovacuum.
	list_memory_configurations	Quali sono le configurazioni di memoria attuali per l'istanza principale?
	list_top_bloated_tables	Elenca le prime cinque tabelle più gonfie.
	list_replication_slots	Visualizza tutti gli slot di replica attivi.
	replication_stats	Mostra le statistiche di replica attuali.
	list_invalid_indexes	Controlla la presenza di indici non validi nel database ecommerce.
	long_running_transactions	Ci sono transazioni in esecuzione da più tempo?

Estensione di osservabilità di AlloyDB

L'estensione alloydb-observability fornisce un'interfaccia unificata per la gestione e il monitoraggio delle prestazioni e dell'integrità del database direttamente dalla Gemini CLI.

Categoria	Strumenti	Esempio di prompt in linguaggio naturale
Osservabilità	get_system_metrics	Quali sono le metriche di sistema, come l'utilizzo della CPU, per l'ultima ora?
	get_query_metrics	Mostrami le metriche sul rendimento delle query degli ultimi 15 minuti.

Puoi utilizzare l'estensione Gemini CLI per AlloyDB in due modi:

• Uno strumento a riga di comando autonomo
• Integrato nel tuo IDE con Gemini Code Assist

Gemini CLI

1. Installa la Gemini CLI.
2. Installa l'estensione AlloyDB per Gemini CLI dal repository GitHub utilizzando il seguente comando:

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

3. Imposta le variabili di ambiente per connetterti all'istanza AlloyDB:

   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"
   

   L'estensione Gemini CLI per AlloyDB utilizza per impostazione predefinita le [credenziali predefinite dell'applicazione (ADC)](/authentication/application-default-credentials) per l'autenticazione. Se vuoi connetterti come utente del database, imposta le seguenti variabili di ambiente facoltative:

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

   Per connetterti utilizzando un indirizzo IP privato, devi impostare anche la seguente variabile di ambiente:

   export ALLOYDB_POSTGRES_IP_TYPE="private"
   

4. Avvia Gemini CLI in modalità interattiva:

   gemini
   

   La CLI carica automaticamente l'estensione AlloyDB per l'estensione Gemini CLI e i relativi strumenti, che puoi utilizzare per interagire con il tuo database.

Gemini Code Assist

Ti consigliamo di configurare Gemini Code Assist per utilizzare Gemini CLI. Questo approccio elimina la necessità di configurare manualmente un server MCP.

1. Assicurati di aver installato e configurato la CLI Gemini e l'estensione alloydb.
2. Configura Gemini Code Assist per utilizzare Gemini CLI.
3. Inizia a interagire con la tua istanza AlloyDB utilizzando il linguaggio naturale direttamente nella chat di Gemini Code Assist.

Contattare Antigravity

Puoi connettere AlloyDB ad Antigravity nei seguenti modi:

• Utilizzo dello Store MCP
• Utilizzo di una configurazione personalizzata

Nota:non è necessario scaricare il file binario di MCP Toolbox per utilizzare questi metodi.

MCP Store

Il metodo più consigliato per connettersi ad AlloyDB in Antigravity è l'utilizzo dell'archivio MCP integrato.

1. Apri Antigravity e il riquadro dell'agente dell'editor.
2. Fai clic sull'icona "..." nella parte superiore del riquadro e seleziona Server MCP.
3. Individua AlloyDB per PostgreSQL nell'elenco dei server disponibili e fai clic su Installa.
4. Segui le istruzioni sullo schermo per collegare in modo sicuro i tuoi account (se applicabile).

Dopo aver installato AlloyDB in MCP Store, le risorse e gli strumenti del server sono disponibili automaticamente per l'editor.

Configurazione personalizzata

Per connetterti a un server MCP personalizzato:

1. Apri Antigravity e il riquadro dell'agente dell'editor.
2. Fai clic sull'icona "..." nella parte superiore del riquadro e seleziona Server MCP.
3. Fai clic su Gestisci server MCP > Visualizza configurazione non elaborata per aprire il file mcp_config.json.
4. Aggiungi e salva la seguente configurazione nel file mcp_config.json.

{
  "mcpServers": {
    "alloydb-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--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"
      }
    }
  }
}

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la proprietà "ALLOYDB_POSTGRES_IP_TYPE": "private" all'oggetto env. Assicurati di aggiungere una virgola alla riga precedente per mantenere valido il JSON.

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto Google Cloud .
• REGION: il nome della regione AlloyDB.
• CLUSTER_NAME: il nome del tuo cluster AlloyDB.
• INSTANCE_NAME: il nome dell'istanza AlloyDB.
• DATABASE_NAME: il nome del database AlloyDB.
• USERNAME: il tuo nome utente AlloyDB per la variabile ALLOYDB_POSTGRES_USER.
• PASSWORD: la password di AlloyDB per la variabile ALLOYDB_POSTGRES_PASSWORD.

Connettiti ad altri IDE utilizzando MCP Toolbox for Databases

Questa sezione descrive come connettersi all'istanza AlloyDB da vari agenti utilizzando MCP Toolbox for Databases. Toolbox funge da server Model Context Protocol (MCP) open source che si trova tra l'IDE e il database, fornendo un control plane per gli strumenti di AI. Questa sezione fornisce istruzioni per connettersi a un'istanza AlloyDB utilizzando un indirizzo IP pubblico o privato. Per impostazione predefinita, Toolbox utilizza un indirizzo IP pubblico, ma puoi configurare una connessione IP privato impostando la variabile di ambiente ALLOYDB_POSTGRES_IP_TYPE come mostrato negli esempi di configurazione.

Installare MCP Toolbox for Databases

Per connettere il tuo IDE ad AlloyDB, devi installare MCP Toolbox for Databases, un server open source che connette gli agenti AI ai tuoi dati.

1. Scarica l'ultima versione di Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare Toolbox versione v0.15.0 o successive.

   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. Rendi il file binario eseguibile.

   chmod +x toolbox
   

3. Verifica l'installazione.

   ./toolbox --version
   

Configura il client

Seleziona lo strumento per agenti tra le seguenti opzioni:

Claude Code

1. Installa Claude Code.
2. Crea il file .mcp.json nella directory root del progetto, se non esiste.
3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Claude desktop

1. Apri Claude Desktop e vai a Impostazioni.
2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Riavvia Claude Desktop.
5. La nuova schermata della chat mostra un'icona a forma di martello (MCP) con il nuovo server MCP.

Cline

1. Apri l'estensione Cline in VS Code e tocca l'icona Server MCP.
2. Fai clic su Configura server MCP per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Cursore

1. Crea la directory .cursor nella root del progetto, se non esiste.
2. Crea il file .cursor/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

4. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Visual Studio Code (Copilot)

1. Apri VS Code e crea la directory .vscode nella directory principale del progetto, se non esiste.
2. Crea il file .vscode/mcp.json se non esiste e aprilo.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Windsurf

1. Apri Windsurf e vai all'assistente Cascade.
2. Fai clic sull'icona MCP, quindi su Configura per aprire il file di configurazione.
3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.

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

Nota:per connetterti utilizzando un indirizzo IP privato, aggiungi la seguente riga all'oggetto env: "ALLOYDB_POSTGRES_IP_TYPE": "private"

Connettiti utilizzando l'estensione Data Agent Kit

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

L'estensione Google Cloud Data Agent Kit ti consente di connetterti al tuo database AlloyDB ed eseguire query direttamente in VS Code o in altri IDE basati su VS Code.

I vantaggi dell'utilizzo di Data Agent Kit includono quanto segue:

• Funzionalità di rilevamento ed esplorazione dei dati che ti consentono di porre domande sui dati AlloyDB in linguaggio naturale
• L'eliminazione del cambio di contesto tra gli strumenti AlloyDB e l'ambiente di sviluppo
• Plug-in che ti consentono di utilizzare le CLI agentiche con le tue risorse Google Cloud

Per ulteriori informazioni, consulta la panoramica dell'estensione Data Agent Kit per VS Code.