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

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:

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 o servidor MCP subjacente 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 para bancos de dados (Toolbox). A Toolbox é um servidor MCP de código aberto que conecta agentes de IA aos seus dados gerenciando tarefas como autenticação e pool 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 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 na MCP Toolbox para bancos de dados. A MCP Toolbox for Databases está atualmente na versão Beta (pré-v1.0) e pode ter mudanças incompatíveis até o primeiro lançamento estável (v1.0).

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

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 ferramentas para consultar o banco de dados, gerenciar recursos do Cloud SQL e monitorar a integridade do banco de dados.

Categoria Ferramentas
Operações de banco de dados
  • list_tables: lista todas as tabelas e as descrições correspondentes encontradas em um banco de dados.
  • execute_sql: executa qualquer instrução SQL.
  • list_active_queries: lista as consultas em execução em uma instância do Cloud SQL.
  • list_available_extensions: lista as extensões do PostgreSQL disponíveis para instalação em uma instância do Cloud SQL.
  • list_installed_extensions: lista as extensões do PostgreSQL instaladas em uma instância do Cloud SQL.
  • get_query_plan: recebe o plano de consulta de uma única instrução de uma instância do Cloud SQL.
Gerenciamento de recursos para instâncias e usuários
  • create_user: cria um novo usuário em uma instância do Cloud SQL.
  • list_databases: lista todos os bancos de dados de uma instância do Cloud SQL.
  • create_database: cria um banco de dados em uma instância do Cloud SQL.
  • list_instances: lista as instâncias do Cloud SQL em um determinado projeto.
  • get_instance: receba os detalhes sobre uma instância específica do Cloud SQL.
  • create_instance: cria uma nova instância do Cloud SQL.
  • wait_for_operation: faz uma pesquisa na API Operations até que uma operação seja concluída.
Integridade e manutenção do banco de dados
  • list_autovacuum_configurations: lista as configurações de autovacuum em uma instância do Cloud SQL. As operações de limpeza removem tuplas inativas para liberar espaço em disco, evitar o aumento da tabela e melhorar o desempenho de leitura e gravação.
  • list_memory_configurations: lista as configurações de memória no nível da instância em uma instância do Cloud SQL. Mostra parâmetros como shared_buffers e work_mem para ajudar você a avaliar e otimizar a alocação de recursos para execução de consultas e armazenamento em cache.
  • list_top_bloated_tables: lista as tabelas em uma instância do Cloud SQL com o maior espaço não utilizado (bloat). Essas informações podem ajudar você a programar a manutenção, incluindo limpeza com aspirador ou reindexação, para recuperar espaço em disco e melhorar a velocidade da consulta.
  • list_replication_slots: lista os detalhes do slot de replicação, como o registro de gravação antecipada (WAL, na sigla em inglês) em uma instância do Cloud SQL. Ajuda no gerenciamento de suporte e na solução de problemas relacionados à replicação.
  • list_invalid_indexes: lista os índices inválidos em uma instância do Cloud SQL. Você pode usar essas informações para recriar ou descartar índices inválidos e melhorar o desempenho da consulta.

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 MCP Toolbox 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 aos 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 do 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.

Instalar a MCP Toolbox

  1. Para instalar a caixa de ferramentas, faça o download do binário correspondente ao seu sistema operacional e à arquitetura da 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 ambiente de desenvolvimento integrado 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 conferir 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 na CLI do Gemini no repositório do GitHub usando o seguinte comando: 
      gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
  3. 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".
  4. 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 ferramentas dela, que você pode usar para interagir com seu banco de dados.

    Na CLI 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
3. Defina variáveis de ambiente para se conectar à instância do PostgreSQL: 
      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.
4. 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. Crie o arquivo .mcp.json na raiz do projeto, se ele não existir.
3. Adicione a 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"
      }
    }
  }
}

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 a 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"
    }
  }
}

5. Reinicie o Claude Desktop.
6. A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP 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"
      }
    }
  }
}

4. 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 do Cascade.
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"
      }
    }
  }
}