Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Usar o Spanner com a caixa de ferramentas do MCP para bancos de dados, a CLI do Gemini e outros agentes

Este documento descreve como conectar sua instância do Spanner a várias ferramentas de desenvolvedor que oferecem suporte ao Protocolo de Contexto de Modelo (MCP).

Recomendamos usar a extensão dedicada do Spanner para a CLI do Gemini. Essa extensão abstrai a necessidade de configurar uma conexão de servidor separada. 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 mais informações, consulte Extensão da CLI do Gemini: Spanner.

Como alternativa, outros ambientes de desenvolvimento integrado e ferramentas de desenvolvedor que oferecem suporte ao MCP podem se conectar pelo MCP Toolbox for Databases. O MCP Toolbox é um servidor MCP de código aberto projetado para conectar agentes de IA aos seus dados. Ele processa 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.

Usar a extensão da CLI do Gemini no Spanner

A integração do Spanner com a CLI do Gemini é feita por uma extensão de código aberto que oferece recursos adicionais em comparação com a conexão padrão do MCP Toolbox. A extensão oferece um processo de instalação e um conjunto de ferramentas, além de fornecer informações detalhadas sobre instalação, configuração e exemplos de uso. Se você usar a extensão da CLI do Gemini, não precisará instalar o MCP Toolbox. Para mais informações, consulte Extensão da CLI do Gemini: Spanner.

A extensão spanner inclui ferramentas para listar tabelas e executar instruções SQL e SQL DQL.

Ferramentas	Exemplo de comando de linguagem natural
`list_tables`	Quais tabelas eu tenho na minha instância do Spanner?
`execute_sql`	Inserir dados de teste na tabela de produtos.
`execute_sql_dql`	Quais produtos da categoria de eletrônicos são vendidos na América?

Antes de começar

No Google Cloud console do, na página do seletor de projetos, selecione ou crie um Google Cloud projeto do.
Verifique se o faturamento está ativado para o projeto do Google Cloud .

Configurar a instância do Spanner

Ative a API Spanner no Google Cloud projeto.
Crie ou selecione uma instância e um banco de dados do Spanner.
Configure os papéis e permissões necessários para concluir essa tarefa. O usuário que invoca os agentes LLM precisa dos seguintes papéis no nível do banco de dados:
- Leitor de banco de dados do Cloud Spanner (roles/spanner.databaseReader) para executar consultas DQL e listar tabelas.
- Usuário do banco de dados do Cloud Spanner (roles/spanner.databaseUser) para executar consultas DML.
Configure o Application Default Credentials (ADC) para seu ambiente.

Instalar o MCP Toolbox

Faça o download da versão mais recente do MCP Toolbox como um binário. Selecione o binário correspondente ao seu sistema operacional (SO) e à arquitetura de CPU. É necessário usar a versão 0.15.0 ou mais recente do MCP Toolbox:

linux/amd64

curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/linux/amd64/toolbox

darwin/arm64

curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/arm64/toolbox

darwin/amd64

curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/darwin/amd64/toolbox

windows/amd64

curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/version/windows/amd64/toolbox

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

Configurar a ferramenta do agente

Esta seção descreve como configurar várias ferramentas de desenvolvedor para se conectar à sua instância do Spanner. Selecione a ferramenta do agente nas opções a seguir:

CLI do Gemini

Instale a CLI do Gemini.
Instale a extensão do Spanner para a CLI do Gemini no repositório do GitHub usando o comando a seguir:

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

Defina as variáveis de ambiente a seguir para se conectar à sua instância do Spanner:
```
    export SPANNER_PROJECT="PROJECT_ID"
    export SPANNER_INSTANCE="INSTANCE_NAME"
    export SPANNER_DATABASE="DATABASE_NAME"
    export SPANNER_DIALECT="DIALECT_NAME"
    
```
Substitua:
- PROJECT_ID: o ID do Google Cloud projeto.
- INSTANCE_NAME: o nome da instância do Spanner.
- DATABASE_NAME: o nome do banco de dados do Spanner.
- DIALECT_NAME: o dialeto SQL do Spanner. Aceita googlesql ou postgresql. O padrão é para googlesql se não estiver definido.
Inicie a CLI do Gemini no modo interativo:
```
    gemini
    
```
A CLI carrega automaticamente a extensão do Spanner 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 remove a necessidade de configurar manualmente um servidor MCP. No entanto, as instruções para configurar manualmente um servidor MCP ainda estão disponíveis na seção a seguir:

1. Instale a extensão do Gemini Code Assist no VS Code.
2. Ative o modo de agente e mude o modelo de agente para o Gemini.
3. No diretório raiz do projeto, crie uma pasta chamada .gemini e, dentro dela, um arquivo settings.json.
4. Adicione uma das configurações a seguir com base no dialeto do Spanner no arquivo settings.json.
5. Substitua as variáveis a seguir pelos seus valores:

PROJECT_ID: o ID do Google Cloud projeto.
INSTANCE_NAME: o nome da instância do Spanner.
DATABASE_NAME: o nome do banco de dados do Spanner.

6. Salve o arquivo.

Spanner com dialeto GoogleSQL:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}