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 Gemini CLI, offrendo 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 ottenere 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. 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.

  2. 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.

    Go to project selector

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

  4. 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.

    Go to project selector

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

  6. 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 di AlloyDB. Google Cloud

      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.

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

    10. Utilizzare le estensioni Gemini CLI 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.

    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 della 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 Crea un nuovo utente del database denominato reporting_user con password report_password.
    Crea un nuovo utente di database IAM per reporting_user@example.com.
    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 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 molto 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

    Interfaccia a riga di comando di Gemini

    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 l'interfaccia a riga di comando di 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.

    Store MCP

    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"
      }
    }
  }
}
    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 tuo 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 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.

    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 binario un eseguibile.

      chmod +x toolbox

    3. Verifica l'installazione.

      ./toolbox --version

    Configura il client

    Seleziona lo strumento per agenti tra le seguenti opzioni:

    Codice Claude

    1. Installa Claude Code.
    2. Crea il file .mcp.json nella directory principale 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"
      }
    }
  }
}

    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"
      }
    }
  }
}
    1. Riavvia Claude Desktop.
    2. Nella nuova schermata della chat viene visualizzata 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.

    Cursore

    1. Crea la directory .cursor nella radice 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"
      }
    }
  }
}
    1. 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 radice 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"
      }
    }
  }
}

    Windsurf

    1. Apri Windsurf e vai all'assistente per le cascate.
    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"
      }
    }
  }
}