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

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

Recomendamos que use a extensão AlloyDB dedicada para a Gemini CLI. A CLI Gemini integra o servidor MCP subjacente diretamente na extensão, pelo que não tem 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 MCP Toolbox for Databases. O Toolbox é 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

Para se ligar à sua instância do AlloyDB e usar as ferramentas disponíveis, tem de ter uma das seguintes funções de gestão de identidade e acesso (IAM) ou uma função personalizada com autorizações equivalentes:

Tarefa Nome da função Função de gestão de identidade e de acesso (IAM) necessária
Use ferramentas só de leitura para listar e obter recursos do AlloyDB Leitor do AlloyDB roles/alloydb.viewer
Associe-se a uma instância e execute consultas Cliente do AlloyDB no Cloud roles/alloydb.client
Consumidor da utilização do serviço roles/serviceusage.serviceUsageConsumer
Realizar tarefas administrativas (como criar ou gerir clusters, instâncias e utilizadores) Administrador do AlloyDB roles/alloydb.admin
Use a extensão de observabilidade Visualizador de monitorização roles/monitoring.viewer

Antes de se poder ligar à sua instância do AlloyDB, conclua os passos seguintes para configurar o projeto e a base de dados.

  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 (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 (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. Ative as APIs Google Cloud necessárias para criar e estabelecer ligação ao AlloyDB.

    Ative as APIs

    1. No passo Confirmar projeto, clique em Seguinte para confirmar o nome do projeto ao qual vai fazer alterações.

    2. No passo Ativar APIs, clique em Ativar para ativar o seguinte:

      • API AlloyDB
      • API Compute Engine
      • Cloud Resource Manager API
      • API de rede de serviços

      A API Service Networking é necessária se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que resida no mesmo Google Cloud projeto que o AlloyDB.

      A API Compute Engine e a API Cloud Resource Manager são necessárias se planear configurar a conetividade de rede ao AlloyDB através de uma rede VPC que reside num projeto Google Cloud diferente.

  7. Crie ou selecione um cluster e a respetiva instância principal.
  8. Configure as credenciais padrão da aplicação (ADC) para o seu ambiente.
  9. Crie ou reutilize um utilizador da base de dados. Tenha o nome de utilizador e a palavra-passe prontos para introduzir.

    10. Use as extensões da Gemini CLI para o AlloyDB

    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 bases de dados de código aberto populares.

    A integração com a CLI do Gemini é feita através de extensões dedicadas que oferecem capacidades adicionais em comparação com uma ligação padrão da caixa de ferramentas do MCP. As secções seguintes descrevem as extensões alloydb e alloydb-observability, que oferecem um processo de instalação e um conjunto de ferramentas. As extensões de código aberto contêm informações detalhadas sobre a instalação, a configuração e exemplos de utilização. Para mais informações, consulte o artigo Extensão da CLI Gemini – AlloyDB para PostgreSQL.

    A extensão alloydb inclui ferramentas para consultar a base de dados, gerir recursos do AlloyDB e monitorizar o estado da base de dados.

    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.
    Categoria Ferramentas Exemplo de comando de linguagem natural
    Operações de base de dados list_tables Mostra-me todas as tabelas na base de dados atual.
    execute_sql Mostra-me os 10 produtos mais caros na categoria "Portáteis".
    list_active_queries Que consultas estão a ser executadas na base de dados?
    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_available_extensions Quais são as extensões disponíveis que posso instalar?
    list_installed_extensions Liste todas as extensões instaladas.
    Gestão de recursos
    clusters, instâncias, utilizadores    		 create_cluster Crie um cluster do AlloyDB denominado sales-quarterly-db na região us-east1.
    get_cluster Obtenha os detalhes do cluster sales-quarterly-db.
    list_clusters Lista todos os meus clusters do AlloyDB.
    create_instance Crie uma nova instância de leitura no cluster sales-quarterly-db.
    get_instance Mostra-me as informações da instância sales-quarterly-db-rp.
    list_instances Liste todas as instâncias no cluster sales-quarterly-db.
    create_user Crie um novo utilizador da base de dados com o nome reporting_user e a palavra-passe report_password.
    Crie um novo utilizador da base de dados de IAM para reporting_user@example.com.
    get_user Obtenha as informações do utilizador reporting_user.
    list_users Liste todos os utilizadores da base de dados.
    wait_for_operation Qual é o estado da operação operation-163562789?
    Estado de funcionamento e manutenção 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 para a instância principal?
    list_top_bloated_tables Apresentar as cinco tabelas mais sobrecarregadas.
    list_replication_slots Apresenta todos os espaços de replicação ativos.
    list_invalid_indexes Verifique se existem índices inválidos na base de dados ecommerce.

    A extensão alloydb-observability oferece uma interface unificada para gerir e monitorizar o desempenho e o estado da base de dados diretamente a partir da Gemini CLI.

    Categoria Ferramentas Exemplo de comando de linguagem natural
    Observabilidade get_system_metrics Quais são as métricas do sistema, como a utilização da CPU, para a última hora?
    get_query_metrics Mostra-me as métricas de desempenho das consultas dos últimos 15 minutos.

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

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

    CLI do Gemini

    1. Instale a CLI do Gemini.
    2. Instale a extensão AlloyDB para a Gemini CLI a partir do repositório do GitHub com o seguinte comando: 
      gemini extensions install https://github.com/gemini-cli-extensions/alloydb
    3. Defina variáveis de ambiente para se ligar à sua instância do 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"

      A extensão Gemini CLI para o AlloyDB usa as suas [Credenciais padrão da aplicação (ADC)](/authentication/application-default-credentials) para autenticação por predefinição. Se quiser estabelecer ligação como utilizador da base de dados, defina as seguintes variáveis de ambiente opcionais:

      #Optional: Set for database user authentication
export ALLOYDB_POSTGRES_USER="USERNAME"
export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"

      Para estabelecer ligação através de um endereço IP privado, também tem de definir a seguinte variável de ambiente:

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

    Gemini Code Assist

    Recomendamos que configure o Gemini Code Assist para usar o Gemini CLI. Esta abordagem elimina a necessidade de configurar manualmente um servidor MCP.

    1. Certifique-se de que instalou e configurou a CLI do Gemini e a extensão alloydb.
    2. Configure o Gemini Code Assist para usar a Gemini CLI.
    3. Comece a interagir com a sua instância do AlloyDB usando 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 a partir de vários agentes através da MCP Toolbox for Databases. A caixa de ferramentas funciona como um servidor de protocolo de contexto do modelo (MCP) de código aberto que se encontra entre o seu IDE e a sua base de dados, fornecendo um plano de controlo para as suas ferramentas de IA. Esta secção fornece instruções para estabelecer ligação a uma instância do AlloyDB através de um endereço IP público ou privado. Por predefinição, a caixa de ferramentas usa um endereço IP público, mas pode configurar uma ligação IP privada definindo a variável de ambiente ALLOYDB_POSTGRES_IP_TYPE, conforme mostrado nos exemplos de configuração.

    Instale a caixa de ferramentas do MCP para bases de dados

    Para associar o seu IDE ao AlloyDB, tem de instalar o MCP Toolbox for Databases, um servidor de código aberto que associa 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. Tem de usar a versão v0.15.0 ou posterior da caixa de ferramentas.

      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. Tornar o ficheiro binário 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:

    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": {
    "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 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": {
    "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. Reinicie o Claude Desktop.
    2. O novo ecrã de chat apresenta um ícone de martelo (MCP) com o novo servidor MCP.

    Cline

    1. Abra a extensão Cline no VS Code e toque 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": {
    "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"
      }
    }
  }
}

    É apresentado um estado ativo verde depois de o servidor se ligar com êxito.

    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": {
    "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. Abra o Cursor e navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.

    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": {
    "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. Abra o Windsurf e navegue para o assistente Cascade.
    2. Clique no ícone do MCP e, de seguida, 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": {
    "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"
      }
    }
  }
}