Utilizzare AlloyDB Omni con MCP, l'interfaccia a riga di comando di Gemini e altri agenti

Seleziona una versione della documentazione:

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

Poiché AlloyDB Omni è compatibile con PostgreSQL, puoi utilizzare strumenti ed estensioni progettati per PostgreSQL.

Per la configurazione più semplice, utilizza l'estensione PostgreSQL dedicata per Gemini CLI, che integra il server MCP sottostante direttamente nell'estensione, in modo da non dover eseguire una configurazione del server separata. Puoi configurare Gemini Code Assist in modo che utilizzi Gemini CLI, offrendo vantaggi di configurazione simili nel tuo IDE.

In alternativa, altri IDE e agenti che supportano l'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 pooling delle connessioni, consentendoti di interagire con i tuoi dati con il linguaggio naturale direttamente dal tuo IDE.

Prima di iniziare

Prima di connetterti all'istanza AlloyDB Omni, assicurati di:

  1. Installa AlloyDB Omni su Kubernetes e avere un'istanza di database in esecuzione.
  2. Crea o riutilizza un utente del database. Preparati a inserire il nome utente e la password.

Utilizza l'estensione Gemini CLI per PostgreSQL

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

L'integrazione con Gemini CLI per AlloyDB Omni avviene tramite l'estensione PostgreSQL. Questa estensione fornisce un insieme di strumenti per interagire con PostgreSQL e AlloyDB Omni, consentendoti di gestire i tuoi database, eseguire query ed esplorare gli schemi direttamente dalla Gemini CLI utilizzando prompt in linguaggio naturale.

Gli esempi seguenti 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: archivia 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.

Nell'estensione PostgreSQL sono disponibili i seguenti strumenti:

Categoria Strumento Esempio di prompt in linguaggio naturale
Operazioni del database execute_sql Mostrami i 10 prodotti più costosi nella categoria "Laptop".
get_query_plan Spiega il piano di query per una query che trova tutti i clienti che non hanno effettuato un ordine negli ultimi 6 mesi.
list_active_queries Quali query vengono eseguite sul database?
database_overview Dammi una panoramica del database attuale.
list_tables Mostrami tutte le tabelle nel database corrente.
list_views Quali visualizzazioni sono disponibili?
list_schemas Elenca tutti gli schemi.
list_triggers Mostrami i trigger nella tabella degli ordini.
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.
list_sequences Elenca tutte le sequenze.
Integrità e manutenzione del database list_autovacuum_configurations Mostrami la configurazione attuale di autovacuum.
list_memory_configurations Quali sono le configurazioni di memoria attuali?
list_top_bloated_tables Elenca le cinque tabelle più gonfie.
list_replication_slots Visualizza tutti gli slot di replica attivi.
list_invalid_indexes Verifica la presenza di indici non validi nel database ecommerce.
long_running_transactions Mostrami le transazioni a lunga esecuzione.
list_locks Elenca tutte le serrature.
replication_stats Mostrami le statistiche di replica.

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

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

Gemini CLI

  1. Installa Gemini CLI (versione 0.6.0 o successive).
  2. Installa l'estensione PostgreSQL per Gemini CLI dal repository GitHub utilizzando il seguente comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/postgres
  3. Imposta le variabili di ambiente per connetterti all'istanza AlloyDB Omni: 
    export POSTGRES_HOST="DATABASE_HOST"
export POSTGRES_PORT="DATABASE_PORT"
export POSTGRES_DATABASE="DATABASE_NAME"
export POSTGRES_USER="DATABASE_USER"
export POSTGRES_PASSWORD="DATABASE_PASSWORD"

    Puoi anche caricare queste variabili da un file .env nella tua directory di lavoro.

  4. Avvia Gemini CLI in modalità interattiva: 
    gemini
     L'interfaccia a riga di comando carica automaticamente l'estensione PostgreSQL e i relativi strumenti, che puoi utilizzare per interagire con il tuo database.

Gemini Code Assist

Per evitare di configurare manualmente un server MCP, configura Gemini Code Assist in modo che utilizzi Gemini CLI.

  1. Installa e configura Gemini CLI e l'estensione postgres come descritto nella scheda Gemini CLI.
  2. Configura Gemini Code Assist per utilizzare Gemini CLI.
  3. Inizia a interagire con la tua istanza AlloyDB Omni utilizzando il linguaggio naturale direttamente nella chat di Gemini Code Assist.

Connettiti ad altri IDE utilizzando MCP Toolbox for Databases

Questa sezione descrive come connetterti alla tua istanza AlloyDB Omni da vari agenti utilizzando MCP Toolbox for Databases.

Installa MCP Toolbox for Databases

Per connettere l'IDE ad AlloyDB Omni, 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 (OS) e all'architettura della CPU.

    linux/amd64

    curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/linux/amd64/toolbox

    darwin/arm64

    curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/arm64/toolbox

    darwin/amd64

    curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/darwin/amd64/toolbox

    windows/amd64

    curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/windows/amd64/toolbox.exe

  2. Rendi eseguibile il file binario.

    chmod +x toolbox

  3. Verifica l'installazione.

    ./toolbox --version

Configura il client

Seleziona lo strumento agente tra le seguenti opzioni:

Cursore

  1. Se non esiste, crea la directory .cursor nella directory root del progetto.
  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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Apri Cursor e vai a Impostazioni > Impostazioni di Cursor > MCP. Quando il server si connette, viene visualizzato lo stato attivo verde.

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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Visual Studio Code (Copilot)

  1. Apri VS Code e crea la directory .vscode nella directory root 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Cline

  1. Apri l'estensione Cline in VS Code e fai clic sull'icona Server MCP.
  2. Fai clic su Configura i 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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Una volta stabilita la connessione al server, viene visualizzato uno stato attivo verde.

Claude per computer

  1. Apri Claude Desktop e vai a Impostazioni.
  2. Nella scheda Developer (Sviluppatore), fai clic su Edit Config (Modifica configurazione) per aprire il file di configurazione.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Riavvia Claude Desktop.
  2. La nuova schermata della chat mostra un'icona a forma di martello (MCP) con il nuovo server MCP.

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": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Riavvia Claude Code per applicare la nuova configurazione.