Questa pagina è stata tradotta dall'API Cloud Translation.

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 la CLI Gemini. L'interfaccia a riga di comando di Gemini integra il server MCP sottostante direttamente nell'estensione, quindi non è necessario eseguire una configurazione separata del server. Puoi configurare Gemini Code Assist per utilizzare l'interfaccia a riga di comando di Gemini, 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 IAM (Identity and Access Management) richiesto
Utilizzare strumenti di sola lettura per elencare e ottenere risorse AlloyDB	AlloyDB Viewer	`roles/alloydb.viewer`
Connettersi a un'istanza ed eseguire query	Cloud AlloyDB Client	`roles/alloydb.client`
Connettersi a un'istanza ed eseguire query	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.

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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 Google Cloud progetto 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.
Crea o seleziona un cluster e la relativa istanza principale.
Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.
Crea o riutilizza un utente del database. Tieni a portata di mano nome utente e password.

Utilizzare le estensioni dell'interfaccia a riga di comando di Gemini per AlloyDB

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 l'interfaccia a riga di comando di Gemini avviene tramite estensioni dedicate che offrono funzionalità aggiuntive rispetto a una connessione standard di MCP Toolbox. 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.

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

Categoria	Strumenti	Esempio di prompt in linguaggio naturale
Operazioni del database	`list_tables`	Mostrami tutte le tabelle nel database corrente.
	`execute_sql`	Esegui la query: SELECT * FROM products WHERE category = 'electronics';
	`list_active_queries`	Quali query vengono eseguite sul database?
	`get_query_plan`	Spiega il piano di query per "SELECT * FROM customers WHERE last_seen > '2025-08-01'"
	`list_available_extensions`	Quali sono le estensioni disponibili che posso installare?
	`list_installed_extensions`	Elenca tutte le estensioni installate.
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`	Crea un nuovo utente del database denominato `reporting_user`.
	`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.
	`list_invalid_indexes`	Controlla la presenza di indici non validi nel database `orders`.

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

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?
Osservabilità	`get_query_metrics`	Mostrami le metriche sul rendimento delle query degli ultimi 15 minuti.

Puoi utilizzare l'estensione dell'interfaccia a riga di comando di Gemini per AlloyDB in due modi:

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

Interfaccia a riga di comando di Gemini

Installa l'interfaccia a riga di comando di Gemini.
Installa l'estensione AlloyDB per l'interfaccia a riga di comando di Gemini dal repository GitHub utilizzando il seguente comando:
```
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
```
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"
```
Avvia l'interfaccia a riga di comando di Gemini 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 in modo che utilizzi la CLI Gemini. Questo approccio elimina la necessità di configurare manualmente un server MCP.

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

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 piano di controllo 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.

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

Rendi il binario un eseguibile.
```
chmod +x toolbox
```
Verifica l'installazione.
```
./toolbox --version
```

Configura il client

Seleziona lo strumento per agenti tra le seguenti opzioni:

Codice Claude

Installa Claude Code.
Crea il file .mcp.json nella root del progetto, se non esiste.
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

Apri Claude Desktop e vai a Impostazioni.
Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
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"

Riavvia Claude Desktop.
Nella nuova schermata della chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.

Cline

Apri l'estensione Cline in VS Code e tocca l'icona Server MCP.
Fai clic su Configura server MCP per aprire il file di configurazione.
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

Crea la directory .cursor nella root del progetto, se non esiste.
Crea il file .cursor/mcp.json se non esiste e aprilo.
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"

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

Visual Studio Code (Copilot)

Apri VS Code e crea la directory .vscode nella radice del progetto, se non esiste.
Crea il file .vscode/mcp.json se non esiste e aprilo.
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

Apri Windsurf e vai all'assistente per le cascate.
Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
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"

Utilizzare AlloyDB per PostgreSQL con MCP, Gemini CLI e altri agenti Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Utilizzare le estensioni dell'interfaccia a riga di comando di Gemini per AlloyDB

Interfaccia a riga di comando di Gemini

Gemini Code Assist

Connettiti ad altri IDE utilizzando MCP Toolbox for Databases

Installare MCP Toolbox for Databases

linux/amd64

darwin/arm64

darwin/amd64

windows/amd64

Configura il client

Codice Claude

Claude desktop

Cline

Cursore

Visual Studio Code (Copilot)

Windsurf

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