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

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

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

1. Installa AlloyDB Omni per Kubernetes o AlloyDB Omni per i container e disponi di un'istanza di database in esecuzione.
2. Crea o riutilizza un utente del database. Tieni a portata di mano nome utente e password.

Utilizzare l'estensione Gemini CLI per PostgreSQL

Nota :l'estensione dell'interfaccia a riga di comando di Gemini per PostgreSQL si basa su MCP Toolbox for Databases. MCP Toolbox for Databases è in versione beta (pre-v1.0) e potrebbe subire modifiche sostanziali 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 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 database, eseguire query ed esplorare gli schemi direttamente dalla CLI Gemini utilizzando prompt in linguaggio naturale.

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.

I seguenti strumenti sono disponibili all'interno dell'estensione PostgreSQL:

Categoria	Strumento	Esempio di prompt in linguaggio naturale
Operazioni del database	execute_sql	Mostrami i 10 prodotti più costosi della categoria "Laptop".
	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_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 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 ecommerce.
	long_running_transactions	Mostrami le transazioni in esecuzione da più tempo.
	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

Interfaccia a riga di comando di Gemini

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 directory di lavoro.

4. Avvia Gemini CLI in modalità interattiva:

   gemini

   La CLI carica automaticamente l'estensione PostgreSQL e i relativi strumenti, che puoi utilizzare per interagire con il 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 la 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 connettersi all'istanza AlloyDB Omni da vari agenti utilizzando MCP Toolbox for Databases.

Installare MCP Toolbox for Databases

Per connettere il tuo 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 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 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:

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

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

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": {
    "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 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": {
    "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 MCP Servers.
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": {
    "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"
      }
    }
  }
}
      

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

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

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

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

4. Riavvia il codice Claude per applicare la nuova configurazione.