Usar o Cloud SQL para PostgreSQL com o MCP, a CLI Gemini e outros agentes

MySQL   |  PostgreSQL   |  SQL Server

Nesta página, você vai aprender a conectar sua instância do Cloud SQL a várias ferramentas de assistência para desenvolvedores de IA, incluindo:

• Extensão da CLI do Gemini para o Cloud SQL para PostgreSQL
• Extensão da CLI do Gemini para PostgreSQL

• Gemini Code Assist
• Claude Code
• Claude para computador
• Codex
• Cline (extensão do VS Code)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (Codeium)
• Antigravity

Para uma experiência integrada, recomendamos usar a extensão da CLI do Gemini para Cloud SQL para PostgreSQL.

Como a interface de linha de comando de próxima geração do Google Cloud, a CLI do Gemini agrupa as habilidades subjacentes diretamente na extensão, o que simplifica a configuração. Você pode configurar o Gemini Code Assist para usar a CLI do Gemini, oferecendo benefícios de configuração semelhantes no seu ambiente de desenvolvimento integrado.

Para outras ferramentas de desenvolvedor que oferecem suporte ao Protocolo de Contexto de Modelo (MCP), é possível se conectar configurando manualmente a MCP Toolbox for Databases (Toolbox). A caixa de ferramentas é um servidor MCP de código aberto que conecta agentes de IA aos seus dados gerenciando tarefas como autenticação e agrupamento de conexões. Assim, você pode interagir com seus dados usando linguagem natural diretamente do IDE. Para essas ferramentas, esse método oferece recursos principais de interação com o banco de dados.

Para mais informações, consulte Ferramentas pré-criadas e MCP Toolbox para bancos de dados no GitHub.

Sobre a CLI do Gemini e as extensões

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. Ela oferece uma interface de agente para interagir com serviços de banco de dados e análise e bancos de dados de código aberto conhecidos.

Como as extensões funcionam

A CLI do Gemini é altamente extensível, permitindo a adição de novas ferramentas e recursos por extensões. É possível carregar as extensões de um URL do GitHub, um diretório local ou um registro configurável. Eles oferecem novas ferramentas, comandos de barra, habilidades e comandos para ajudar no seu fluxo de trabalho.

Usar as extensões da CLI do Gemini no Cloud SQL para PostgreSQL

A extensão da CLI do Gemini do Cloud SQL é baseada no MCP Toolbox para bancos de dados.

A integração com a CLI do Gemini é feita por uma extensão dedicada que oferece mais recursos em comparação com a conexão padrão da caixa de ferramentas. A extensão oferece um processo de instalação simplificado e um conjunto de habilidades com base nas ferramentas do MCP.

Para mais informações, consulte a documentação do GitHub sobre a extensão da CLI do Gemini para Cloud SQL para PostgreSQL.

Extensão da CLI do Gemini para bancos de dados do Cloud SQL para PostgreSQL

A extensão cloud-sql-postgresql inclui habilidades para consultar o banco de dados, gerenciar recursos do Cloud SQL e monitorar a integridade do banco de dados.

Para conferir todas as habilidades disponíveis, consulte as habilidades do Cloud SQL no GitHub.

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

Categoria	Ferramentas
Observabilidade	get_system_metrics: recupera métricas do sistema para uma instância do Cloud SQL. get_query_metrics: recupera métricas relacionadas a consultas de uma instância do Cloud SQL.

Extensão da CLI do Gemini para bancos de dados PostgreSQL

Para conferir uma lista dessas operações, consulte Caixa de ferramentas do MCP para bancos de dados e Extensão da CLI do Gemini para PostgreSQL.

Antes de começar

• No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .

• Verifique se o faturamento está ativado para o projeto do Google Cloud .

• Ative a API Cloud SQL Admin no Google Cloud projeto.

• Por padrão, o Cloud SQL atribui um endereço IP público a uma nova instância. Dependendo do seu caso de uso, verifique se um IP público ou um IP particular está configurado para suas instâncias do Cloud SQL. A caixa de ferramentas se conecta com segurança usando os conectores de linguagem do Cloud SQL.

• Conceda ao usuário que vai executar o servidor MCP os papéis necessários do Identity and Access Management (IAM). As ferramentas disponíveis dependem das funções concedidas:

  Tarefa	Nome do papel	Papel do IAM obrigatório
  Fornece acesso somente leitura a recursos, incluindo as seguintes operações: get_instance list_instances list_databases wait_for_operation	Leitor do Cloud SQL	roles/cloudsql.viewer
  Fornece acesso somente leitura a dados de monitoramento, como métricas de série temporal.	Leitor do Cloud Monitoring	roles/monitoring.viewer
  Concede permissões para gerenciar recursos atuais, incluindo: Todas as ferramentas de viewer create_database	Editor do Cloud SQL	roles/cloudsql.editor
  Concede controle total sobre todos os recursos, incluindo: Todas as ferramentas viewer e editor create_instance create_user	Administrador do Cloud SQL	roles/cloudsql.admin

• Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.

• Crie ou reutilize um usuário do banco de dados e tenha o nome de usuário e a senha prontos.

Conecte-se com o Antigravity

É possível conectar o Cloud SQL para PostgreSQL ao Antigravity das seguintes maneiras:

• Usar a loja do MCP
• 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 MCP

O método mais recomendado para se conectar ao Cloud SQL para PostgreSQL no Antigravity é usar a loja MCP integrada.

1. Abra o Antigravity e o painel do agente do editor.
2. Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
3. Localize Cloud SQL para PostgreSQL na lista de servidores disponíveis e clique em Instalar.
4. Siga as instruções na tela para vincular suas contas com segurança, quando aplicável.

Depois de instalar o Cloud SQL para PostgreSQL na loja do MCP, os recursos e as ferramentas do servidor ficam disponíveis automaticamente para o editor.

Configuração personalizada

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

1. Abra o Antigravity e o painel do agente do editor.
2. Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
3. Clique em Gerenciar servidores MCP > Ver configuração bruta para abrir o arquivo mcp_config.json.
4. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve.

{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
          "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
          "CLOUD_SQL_POSTGRES_REGION": "REGION",
          "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
          "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
          "CLOUD_SQL_POSTGRES_USER": "USER_ID",
          "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Depois de configurar o servidor MCP personalizado, os recursos e as ferramentas do servidor do Cloud SQL para PostgreSQL ficam disponíveis para o editor.

Instalar a MCP Toolbox

Observação: essa etapa não é necessária para extensões da CLI Gemini.

1. Baixe o binário que corresponde ao seu sistema operacional e arquitetura de CPU.

   linux/amd64

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

   darwin/arm64

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

   darwin/amd64

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

   windows/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/windows/amd64/toolbox

2. Torne o binário executável:

   chmod +x toolbox

3. Verifique a instalação usando o seguinte comando:

   ./toolbox --version

Configurar o cliente MCP

Nesta seção, descrevemos como configurar várias ferramentas para desenvolvedores e se conectar à instância do Cloud SQL usando a Toolbox. A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu IDE e seu banco de dados, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA. Selecione a guia da sua ferramenta específica para ver as instruções de configuração.

CLI do Gemini para Cloud SQL para PostgreSQL

1. Instale a CLI do Gemini.
2. Instale a extensão do Cloud SQL para PostgreSQL para a CLI do Gemini no repositório do GitHub usando o seguinte comando:

   gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
   

   Ao instalar a extensão, substitua o seguinte:
   • PROJECT_NAME: o ID do projeto do Google Cloud .
   • REGION: a região da instância do Cloud SQL.
   • INSTANCE_NAME: o ID da sua instância do Cloud SQL.
   • DATABASE_NAME: o nome do banco de dados a ser conectado.
   • DATABASE_USER_NAME: opcional: o nome de usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • PASSWORD: opcional. A senha do usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • IP_TYPE: opcional. O tipo de IP, como "Público" (padrão) ou "Privado".
3. Inicie a CLI do Gemini no modo interativo:

   gemini
   

   A CLI carrega automaticamente a extensão da CLI do Gemini para o Cloud SQL e as habilidades dela, que você pode usar para interagir com seu banco de dados.

   Na CLI do Gemini, use o comando /extensions para verificar se a extensão está instalada e o comando /mcp list para ver as ferramentas.

CLI do Gemini para PostgreSQL

1. Instale a CLI do Gemini.
2. Instale a extensão de software do PostgreSQL para a CLI do Gemini no repositório do GitHub usando o seguinte comando:

   gemini extensions install https://github.com/gemini-cli-extensions/postgres
   

   Ao instalar a extensão, substitua:

   export POSTGRES_HOST="HOST"
   export POSTGRES_PORT="PORT"
   export POSTGRES_DATABASE="DATABASE"
   export POSTGRES_USER="USER"
   export POSTGRES_PASSWORD="PASSWORD"
   export POSTGRES_QUERY_PARAMETERS="QUERY_PARAMETERS"
   

   Substitua:
   • HOST: o nome do host ou o endereço IP do servidor PostgreSQL.
   • PORT: o número da porta do servidor PostgreSQL.
   • DATABASE: o nome do banco de dados a ser conectado.
   • USER: o nome de usuário do banco de dados.
   • PASSWORD: a senha do usuário do banco de dados.
   • QUERY_PARAMETERS: opcional: a consulta bruta a ser adicionada à string de conexão db.
3. Inicie a CLI do Gemini no modo interativo:

   gemini

   A CLI carrega automaticamente a extensão da CLI do Gemini para PostgreSQL e as ferramentas dela, que podem ser usadas para interagir com seu banco de dados.

Gemini Code Assist

1. Instale a extensão Gemini Code Assist no Visual Studio Code.
2. Ative o Modo Agente no chat do Gemini Code Assist.
3. No diretório de trabalho, crie uma pasta chamada .gemini. Nele, crie um arquivo settings.json.
4. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

Código do Claude

1. Instale o Claude Code.
2. Defina variáveis de ambiente para se conectar à instância do Cloud SQL:

   export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
   export CLOUD_SQL_POSTGRES_REGION="REGION"
   export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
   export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
   export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
   export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
   export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
   

   Substitua:
   • PROJECT_NAME: o ID do projeto do Google Cloud .
   • REGION: a região da instância do Cloud SQL.
   • INSTANCE_NAME: o ID da sua instância do Cloud SQL.
   • DATABASE_NAME: o nome do banco de dados a ser conectado.
   • DATABASE_USER_NAME: opcional: o nome de usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • PASSWORD: opcional. A senha do usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • IP_TYPE: opcional. O tipo de IP, como "Público" (padrão) ou "Privado".
3. Inicie o agente:

   claude

4. Instalar o plug-in:

   /plugin install cloud-sql-postgresql@claude-plugins-official

Dica:execute /plugin list no Claude Code para verificar se o plug-in está ativo ou /reload-plugins se você acabou de instalar.

Claude para computador

1. Abra o Claude para computador e acesse Configurações.
2. Na guia Desenvolvedor, toque em Editar configuração para abrir o arquivo de configuração.
3. Adicione o seguinte para se conectar ao servidor MCP e definir as variáveis de ambiente:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
       }
     }
   }
   }
   
   

4. Reinicie o Claude para computador. A nova tela de chat mostra o ícone do MCP com o novo servidor disponível.

Cline

1. Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
2. Toque em Configurar servidores MCP para abrir o arquivo de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

   Um status ativo verde aparece depois que o servidor se conecta.

Codex

1. Instale o Data Agent Kit no Marketplace:

   codex plugin marketplace add GoogleCloudPlatform/data-agent-kit

2. Instalar o plug-in:

   codex plugin install cloud-sql-postgresql@data-agent-kit

3. Configure as variáveis de ambiente para se conectar à instância do Cloud SQL:

   export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
   export CLOUD_SQL_POSTGRES_REGION="REGION"
   export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
   export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
   export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
   export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
   export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
   

   Substitua:
   • PROJECT_NAME: o ID do projeto do Google Cloud .
   • REGION: a região da instância do Cloud SQL.
   • INSTANCE_NAME: o ID da sua instância do Cloud SQL.
   • DATABASE_NAME: o nome do banco de dados a ser conectado.
   • DATABASE_USER_NAME: opcional: o nome de usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • PASSWORD: opcional. A senha do usuário do banco de dados. O padrão é a autenticação do IAM se não for especificado.
   • IP_TYPE: opcional. O tipo de IP, como "Público" (padrão) ou "Privado".
4. Opcional. Atualize o marketplace:

   codex plugin marketplace upgrade data-agent-kit

5. Execute codex plugin list ou use o menu interativo plugins para verificar os plug-ins instalados.

Cline

1. Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
2. Toque em Configurar servidores MCP para abrir o arquivo de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

   Um status ativo verde aparece depois que o servidor se conecta.

Cursor

1. Crie o diretório .cursor na raiz do projeto, se ele não existir.
2. Crie o arquivo .cursor/mcp.json, se ele não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

4. Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Visual Studio Code (Copilot)

1. Abra o VS Code e crie o diretório .vscode na raiz do projeto, se ele não existir.
2. Crie o arquivo .vscode/mcp.json, se ele não existir, e abra-o.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "servers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

Windsurf

1. Abra o Windsurf e navegue até o Assistente de cascata.
2. Toque no ícone do MCP e em Configurar para abrir o arquivo de configuração.
3. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e salve:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }