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 dedicada ao 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 o 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 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 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 seu 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 de desenvolvedor para 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 o IDE e o 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 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
  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 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 podem ser usadas 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
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 verde ativo 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"
      }
    }
  }
}