Use o AlloyDB Omni com o MCP, a Gemini CLI e outros agentes

Este documento descreve como ligar a sua instância do AlloyDB Omni a vários agentes que suportam o protocolo Model Context Protocol (MCP).

Uma vez que o AlloyDB Omni é compatível com o PostgreSQL, pode usar ferramentas e extensões concebidas para o PostgreSQL.

Para a configuração mais simples, use a extensão PostgreSQL dedicada para a CLI Gemini. Esta integra o servidor MCP subjacente diretamente na extensão, pelo que não precisa de fazer uma configuração de servidor separada. Pode configurar o Gemini Code Assist para usar a Gemini CLI, o que oferece vantagens de configuração semelhantes no seu IDE.

Em alternativa, outros IDEs e agentes que suportem o MCP podem estabelecer ligação através da caixa de ferramentas do MCP para bases de dados. A caixa de ferramentas é um servidor MCP de código aberto concebido para ligar agentes de IA aos seus dados. Processa tarefas como a autenticação e a partilha de ligações, o que lhe permite interagir com os seus dados com linguagem natural diretamente a partir do IDE.

Antes de começar

Antes de se ligar à sua instância do AlloyDB Omni, certifique-se de que faz o seguinte:

  1. Instale o AlloyDB Omni para Kubernetes ou o AlloyDB Omni para contentores e tenha uma instância de base de dados em execução.
  2. Crie ou reutilize um utilizador da base de dados. Tenha o nome de utilizador e a palavra-passe prontos para introduzir.

Use a extensão Gemini CLI para PostgreSQL

O Gemini CLI é um agente de IA de código aberto concebido para ajudar nos fluxos de trabalho de desenvolvimento, auxiliando na programação, na depuração, na exploração de dados e na criação de conteúdo. A sua missão é fornecer uma interface de agente para interagir com os serviços do Data Cloud e as bases de dados de código aberto populares.

A integração com o Gemini CLI para o AlloyDB Omni é feita através da extensão PostgreSQL. Esta extensão oferece um conjunto de ferramentas para interagir com o PostgreSQL e o AlloyDB Omni, o que lhe permite gerir as suas bases de dados, executar consultas e explorar esquemas diretamente a partir da Gemini CLI através de comandos de linguagem natural.

Os exemplos seguintes usam uma base de dados de amostra ecommerce com as seguintes tabelas:

  • products: contém informações sobre o produto, incluindo product_id, product_name, category e price.
  • customers: armazena dados de clientes, como customer_id, first_name, last_name e email.
  • orders: contém informações sobre a encomenda, incluindo order_id, customer_id e order_date.

As seguintes ferramentas estão disponíveis na extensão do PostgreSQL:

Categoria Ferramenta Exemplo de comando de linguagem natural
Operações de base de dados execute_sql Mostra-me os 10 produtos mais caros na categoria "Portáteis".
get_query_plan Explique o plano de consulta para uma consulta que encontra todos os clientes que não fizeram uma encomenda nos últimos 6 meses.
list_active_queries Que consultas estão a ser executadas na base de dados?
database_overview Dá-me uma vista geral da base de dados atual.
list_tables Mostra-me todas as tabelas na base de dados atual.
list_views Que vistas estão disponíveis?
list_schemas Apresentar todos os esquemas.
list_triggers Mostra-me os acionadores na tabela de encomendas.
list_available_extensions Quais são as extensões disponíveis que posso instalar?
list_installed_extensions Liste todas as extensões instaladas.
list_indexes Apresentar todos os índices.
list_sequences Apresentar todas as sequências.
Manutenção e estado de funcionamento da base de dados list_autovacuum_configurations Mostra-me a configuração atual do autovacuum.
list_memory_configurations Quais são as configurações de memória atuais?
list_top_bloated_tables Apresentar as cinco tabelas mais sobrecarregadas.
list_replication_slots Apresenta todos os slots de replicação ativos.
list_invalid_indexes Verifique se existem índices inválidos na base de dados ecommerce.
long_running_transactions Mostra-me as transações de longa duração.
list_locks Apresentar todas as fechaduras.
replication_stats Mostra-me as estatísticas de replicação.

Pode usar a extensão Gemini CLI para PostgreSQL de duas formas:

  • Uma ferramenta de linhas de comandos autónoma
  • Integrado no seu IDE com o Gemini Code Assist

CLI do Gemini

  1. Instale a Gemini CLI (versão 0.6.0 ou posterior).
  2. Instale a extensão PostgreSQL para a Gemini CLI a partir do repositório do GitHub com o seguinte comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/postgres
  3. Defina variáveis de ambiente para estabelecer ligação à sua instância do 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"

    Também pode carregar estas variáveis a partir de um ficheiro .env no seu diretório de trabalho.

  4. Inicie a CLI do Gemini no modo interativo: 
    gemini
     A CLI carrega automaticamente a extensão PostgreSQL e as respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Gemini Code Assist

Para evitar a configuração manual de um servidor MCP, configure o Gemini Code Assist para usar o Gemini CLI.

  1. Instale e configure a Gemini CLI e a extensãopostgres, conforme descrito no separador Gemini CLI.
  2. Configure o Gemini Code Assist para usar a Gemini CLI.
  3. Comece a interagir com a sua instância do AlloyDB Omni através da linguagem natural diretamente no chat do Gemini Code Assist.

Estabeleça ligação a outros IDEs através da caixa de ferramentas MCP para bases de dados

Esta secção descreve como estabelecer ligação à sua instância do AlloyDB Omni a partir de vários agentes através da MCP Toolbox for Databases.

Instale a caixa de ferramentas do MCP para bases de dados

Para ligar o seu IDE ao AlloyDB Omni, tem de instalar o MCP Toolbox for Databases, um servidor de código aberto que liga os agentes de IA aos seus dados.

  1. Transfira a versão mais recente da caixa de ferramentas como um ficheiro binário. Selecione o binário correspondente ao seu sistema operativo (SO) e arquitetura da 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. Transformar o ficheiro binário num ficheiro executável.

    chmod +x toolbox

  3. Valide a instalação.

    ./toolbox --version

Configure o cliente

Selecione a ferramenta de agente a partir das seguintes opções:

Cursor

  1. Crie o diretório .cursor na raiz do projeto, se não existir.
  2. Crie o ficheiro .cursor/mcp.json, se não existir, e abra-o.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. Abra o Cursor e navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.

Windsurf

  1. Abra o Windsurf e navegue para o assistente Cascade.
  2. Clique no ícone do MCP e, de seguida, clique em Configurar para abrir o ficheiro de configuração.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se não existir.
  2. Crie o ficheiro .vscode/mcp.json, se não existir, e abra-o.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. Abra a extensão Cline no VS Code e clique no ícone Servidores MCP.
  2. Clique em Configurar servidores MCP para abrir o ficheiro de configuração.
  3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. É apresentado um estado ativo verde depois de o servidor se ligar com êxito.

Claude para computador

  1. Abra o Claude Desktop e navegue para Definições.
  2. No separador Programador, clique em Editar configuração para abrir o ficheiro de configuração.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. Reinicie o Claude Desktop.
  2. O novo ecrã de chat apresenta um ícone de martelo (MCP) com o novo servidor MCP.

Código do Claude

  1. Instale o Claude Code.
  2. Crie o ficheiro .mcp.json na raiz do projeto, se não existir.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde.
{
  "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. Reinicie o código do Claude para aplicar a nova configuração.