O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o AlloyDB para PostgreSQL com o MCP, a CLI do Gemini e outros agentes

Para consultar seu banco de dados do AlloyDB para PostgreSQL, inspecionar esquemas e gerenciar recursos de banco de dados usando linguagem natural no seu ambiente de desenvolvimento integrado ou terminal, conecte sua instância a ferramentas de IA compatíveis com o Protocolo de Contexto de Modelo (MCP, na sigla em inglês).

Recomendamos usar a extensão dedicada do AlloyDB para a CLI do Gemini. A CLI do Gemini integra o servidor MCP diretamente à extensão, então não é necessário configurar um servidor separado. É possível configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo benefícios de configuração semelhantes no seu ambiente de desenvolvimento integrado.

Como alternativa, outros IDEs e agentes que oferecem suporte ao MCP podem se conectar usando o MCP Toolbox for Databases. O Toolbox é um servidor MCP de código aberto projetado para conectar agentes de IA aos seus dados. Ele lida com tarefas como autenticação e pool de conexões, permitindo que você interaja com seus dados usando linguagem natural diretamente do seu ambiente de desenvolvimento integrado.

Antes de começar

Para se conectar à instância do AlloyDB e usar as ferramentas disponíveis, você precisa ter um dos seguintes papéis do Identity and Access Management (IAM) ou um papel personalizado com permissões equivalentes:

Tarefa	Nome do papel	Papel do IAM obrigatório
Usar ferramentas somente leitura para listar e receber recursos do AlloyDB	Leitor do AlloyDB	`roles/alloydb.viewer`
Conectar-se a uma instância e executar consultas	Cliente do AlloyDB	`roles/alloydb.client`
Conectar-se a uma instância e executar consultas	Consumidor do Service Usage	`roles/serviceusage.serviceUsageConsumer`
Realizar tarefas administrativas (como criar ou gerenciar clusters, instâncias e usuários)	Administrador do AlloyDB	`roles/alloydb.admin`
Usar a extensão de observabilidade	Visualizador de monitoramento	`roles/monitoring.viewer`

Antes de se conectar à instância do AlloyDB, siga as etapas abaixo para configurar o projeto e o banco de dados.

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB.

Ativar as APIs
1. Na etapa Confirmar projeto, clique em Avançar para confirmar o nome do projeto em que você vai fazer alterações.
2. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:
  - API AlloyDB
  - API Compute Engine
  - API Cloud Resource Manager
  - API Service Networking
  A API Service Networking é necessária se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede de nuvem privada virtual (VPC) que reside no mesmo projeto do Google Cloud AlloyDB.
  
  As APIs Compute Engine e Cloud Resource Manager são necessárias se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside em um projeto do Google Cloud diferente.
Crie ou selecione um cluster e a instância primária dele.
Configure o Application Default Credentials (ADC) para seu ambiente.
Crie ou reutilize um usuário de banco de dados. Esteja pronto para inserir o nome de usuário e a senha.

Usar as extensões da CLI do Gemini para o AlloyDB

A CLI do Gemini é um agente de IA de código aberto projetado para ajudar nos fluxos de trabalho de desenvolvimento, auxiliando na programação, depuração, análise de dados e criação de conteúdo. A missão dele é fornecer uma interface interativa para interagir com os serviços do Data Cloud e bancos de dados de código aberto conhecidos.

A integração com a CLI do Gemini é feita por extensões dedicadas que oferecem recursos adicionais em comparação com uma conexão padrão do MCP Toolbox. As seções a seguir 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 instalação, configuração e exemplos de uso. Para mais informações, consulte Extensão da CLI do Gemini: AlloyDB para PostgreSQL.

Extensão do AlloyDB

A extensão alloydb inclui ferramentas para consultar o banco de dados, gerenciar recursos do AlloyDB e monitorar a integridade do banco de dados.

Os exemplos a seguir usam um banco de dados ecommerce de amostra com as seguintes tabelas:

products: contém informações do produto, incluindo product_id, product_name, category e price.
customers: armazena dados do cliente, como customer_id, first_name, last_name e email.
orders: contém informações do pedido, incluindo order_id, customer_id e order_date.

Categoria	Ferramentas	Exemplo de comando em linguagem natural
Operações de banco de dados	`database_overview`	Mostre uma visão geral do banco de dados atual.
	`list_tables`	Mostre todas as tabelas no banco de dados atual.
	`execute_sql`	Mostre os 10 produtos mais caros na categoria "Laptops".
	`list_active_queries`	Quais consultas estão sendo executadas no banco de dados?
	`get_query_plan`	Explique o plano de consulta para uma consulta que encontra todos os clientes que não fizeram um pedido nos últimos 6 meses.
	`list_available_extensions`	Quais são as extensões disponíveis para instalação?
	`list_installed_extensions`	Lista todas as extensões instaladas.
	`list_indexes`	Liste todos os índices na tabela `products`.
	`list_locks`	Mostra todos os bloqueios ativos no banco de dados.
	`list_schemas`	Lista todos os esquemas no banco de dados.
	`list_sequences`	Mostra todas as sequências no esquema atual.
	`list_triggers`	Liste todos os gatilhos da tabela `orders`.
	`list_views`	Mostre todas as visualizações no esquema `sales`.
Gerenciamento de recursos clusters, instâncias, usuários	`create_cluster`	Crie um cluster do AlloyDB chamado `sales-quarterly-db` na região `us-east1`.
	`get_cluster`	Receba os detalhes do cluster `sales-quarterly-db`.
	`list_clusters`	Listar todos os meus clusters do AlloyDB.
	`create_instance`	Crie uma nova instância de leitura no cluster `sales-quarterly-db`.
	`get_instance`	Mostre as informações da instância `sales-quarterly-db-rp`.
	`list_instances`	Liste todas as instâncias no cluster `sales-quarterly-db`.
	`create_user`	Observação:a ferramenta `create_user` pode criar dois tipos de usuários de banco de dados: Usuários do banco de dados com autenticação integrada: são gerenciados no banco de dados e autenticados com uma senha. Usuários do IAM: são gerenciados no IAM e autenticados usando as credenciais do IAM. Ao criar um usuário de banco de dados com autenticação integrada, é necessário fornecer uma senha. Ao criar um usuário do IAM, é preciso fornecer o principal do IAM. Crie um novo usuário de banco de dados chamado `reporting_user` com a senha `report_password`. Crie um novo usuário de banco de dados do IAM para `reporting_user@example.com`.
	`get_user`	Receba as informações do usuário `reporting_user`.
	`list_users`	Listar todos os usuários do banco de dados.
	`wait_for_operation`	Qual é o status da operação `operation-163562789`?
Integridade e manutenção do banco de dados	`list_autovacuum_configurations`	Mostre a configuração atual do autovacuum.
	`list_memory_configurations`	Quais são as configurações de memória atuais da instância principal?
	`list_top_bloated_tables`	Liste as cinco tabelas mais inchadas.
	`list_replication_slots`	Mostre todos os slots de replicação ativos.
	`replication_stats`	Mostra as estatísticas de replicação atuais.
	`list_invalid_indexes`	Verifique se há índices inválidos no banco de dados `ecommerce`.
	`long_running_transactions`	Há transações de longa duração?

Extensão de observabilidade do AlloyDB

A extensão alloydb-observability oferece uma interface unificada para gerenciar e monitorar o desempenho e a integridade do banco de dados diretamente da CLI do Gemini.

Categoria	Ferramentas	Exemplo de comando em linguagem natural
Observabilidade	`get_system_metrics`	Quais são as métricas do sistema, como uso da CPU, na última hora?
Observabilidade	`get_query_metrics`	Mostre as métricas de performance de consulta dos últimos 15 minutos.

Você pode usar a extensão da CLI do Gemini para o AlloyDB de duas maneiras:

Uma ferramenta de linha de comando independente
Integrado ao seu ambiente de desenvolvimento integrado com o Gemini Code Assist

CLI do Gemini

Instale a CLI do Gemini.
Instale a extensão do AlloyDB para a CLI do Gemini no repositório do GitHub usando o seguinte comando:
```
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
```
Defina variáveis de ambiente para se conectar à 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 da CLI do Gemini para o AlloyDB usa o Application Default Credentials (ADC) para autenticação por padrão. Se você quiser se conectar como um usuário do banco 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 se conectar usando um endereço IP particular, defina também a seguinte variável de ambiente:
```
export ALLOYDB_POSTGRES_IP_TYPE="private"
```
Inicie a CLI do Gemini no modo interativo:
```
gemini
```
A CLI carrega automaticamente a extensão do AlloyDB para a CLI do Gemini e as ferramentas dela, que podem ser usadas para interagir com o banco de dados.

Gemini Code Assist

Recomendamos configurar o Gemini Code Assist para usar a CLI do Gemini, porque essa abordagem elimina a necessidade de configurar manualmente um servidor MCP.

Verifique se você instalou e configurou a CLI do Gemini e a extensão alloydb.
Configure o Gemini Code Assist para usar a CLI do Gemini.
Comece a interagir com sua instância do AlloyDB usando linguagem natural diretamente no chat do Gemini Code Assist.

Conectar-se ao Antigravity

É possível conectar o AlloyDB ao Antigravity das seguintes maneiras:

Como usar a MCP Store
Como usar uma configuração personalizada

Observação:não é necessário fazer o download do binário da MCP Toolbox para usar esses métodos.

Loja do MCP

O método mais recomendado para se conectar ao AlloyDB no Antigravity é usar a MCP Store integrada.

Abra o Antigravity e o painel do agente do editor.
Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
Localize AlloyDB para PostgreSQL na lista de servidores disponíveis e clique em Instalar.
Siga as mensagens na tela para vincular suas contas com segurança (quando aplicável).

Depois de instalar o AlloyDB na MCP Store, os recursos e as ferramentas do servidor ficam automaticamente disponíveis para o editor.

Configuração personalizada

Para se conectar a um servidor MCP personalizado, siga estas etapas:

Abra o Antigravity e o painel do agente do editor.
Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
Clique em Gerenciar servidores MCP > Ver configuração bruta para abrir o arquivo mcp_config.json.
Adicione e salve a seguinte configuração no arquivo 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"
      }
    }
  }
}

Observação:para se conectar usando um endereço IP particular, adicione a propriedade "ALLOYDB_POSTGRES_IP_TYPE": "private" ao objeto env. Adicione uma vírgula à linha anterior para manter o JSON válido.

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
REGION: o nome da região do AlloyDB.
CLUSTER_NAME: o nome do cluster do AlloyDB.
INSTANCE_NAME: o nome da instância do AlloyDB.
DATABASE_NAME: o nome do banco de dados do AlloyDB.
USERNAME: seu nome de usuário do AlloyDB para a variável ALLOYDB_POSTGRES_USER.
PASSWORD: sua senha do AlloyDB para a variável ALLOYDB_POSTGRES_PASSWORD.

Conectar-se a outros ambientes de desenvolvimento integrado usando o MCP Toolbox for Databases

Nesta seção, descrevemos como se conectar à instância do AlloyDB de vários agentes usando o MCP Toolbox for Databases. O Toolbox funciona como um servidor de código aberto do Protocolo de Contexto de Modelo (MCP) que fica entre o ambiente de desenvolvimento integrado e o banco de dados, fornecendo um plano de controle para suas ferramentas de IA. Nesta seção, mostramos como se conectar a uma instância do AlloyDB usando um endereço IP público ou privado. Por padrão, o Toolbox usa um endereço IP público, mas é possível configurar uma conexão por IP particular definindo a variável de ambiente ALLOYDB_POSTGRES_IP_TYPE, conforme mostrado nos exemplos de configuração.

Instalar o MCP Toolbox for Databases

Para conectar seu ambiente de desenvolvimento integrado ao AlloyDB, instale o MCP Toolbox for Databases, um servidor de código aberto que conecta agentes de IA aos seus dados.

Faça o download da versão mais recente do Toolbox como um binário. Selecione o binário correspondente ao seu sistema operacional (SO) e à arquitetura de CPU. Use a versão v0.15.0 ou posterior do Toolbox.

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

Torne o binário um executável.
```
chmod +x toolbox
```
Verifique a instalação.
```
./toolbox --version
```

Configurar o cliente

Selecione sua ferramenta de agente entre as seguintes opções: