Multi Database MCP Server

Visão Geral

O DB MCP Server fornece uma forma padronizada para modelos de IA interagirem com múltiplos bancos de dados simultaneamente. Construído sobre o framework FreePeak/cortex, ele permite que assistentes de IA executem consultas SQL, gerenciem transações, explorem esquemas e analisem desempenho em diferentes sistemas de banco de dados através de uma interface unificada.

Conceitos Principais

Suporte Multi-Banco de Dados

Diferente dos conectores de banco de dados tradicionais, o DB MCP Server pode conectar-se e interagir com múltiplos bancos de dados simultaneamente:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "localhost",
      "port": 5432,
      "name": "db2",
      "user": "user2",
      "password": "password2"
    },
    {
      "id": "oracle1",
      "type": "oracle",
      "host": "localhost",
      "port": 1521,
      "service_name": "XEPDB1",
      "user": "user3",
      "password": "password3"
    }
  ]
}

Geração Dinâmica de Ferramentas

Para cada banco de dados conectado, o servidor gera automaticamente ferramentas especializadas:

// For a database with ID "mysql1", these tools are generated:
query_mysql1       // Execute SQL queries
execute_mysql1     // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1      // Explore database schema
performance_mysql1 // Analyze query performance

Arquitetura Limpa

O servidor segue os princípios de Arquitetura Limpa com as seguintes camadas:

1. Camada de Domínio: Entidades de negócio centrais e interfaces
2. Camada de Repositório: Implementações de acesso a dados
3. Camada de Casos de Uso: Lógica de negócio da aplicação
4. Camada de Entrega: Interfaces externas (ferramentas MCP)

Recursos

• Suporte Multi-Banco de Dados Simultâneo: Conecte-se a múltiplos bancos MySQL, PostgreSQL, SQLite e Oracle simultaneamente
• Modo de Carregamento Preguiçoso: Adie o estabelecimento da conexão até o primeiro uso — perfeito para configurações com 10+ bancos de dados (ative com a flag --lazy-loading)
• Geração de Ferramentas Específicas por Banco: Cria automaticamente ferramentas especializadas para cada banco de dados conectado
• Arquitetura Limpa: Design modular com clara separação de responsabilidades
• Compatibilidade com OpenAI Agents SDK: Compatibilidade total para integração perfeita com assistentes de IA
• Ferramentas Dinâmicas de Banco de Dados: Execute consultas, execute declarações, gerencie transações, explore esquemas, analise desempenho
• Interface Unificada: Padrões de interação consistentes entre diferentes tipos de banco de dados
• Gerenciamento de Conexões: Configuração simples para múltiplas conexões de banco de dados
• Verificação de Saúde: Validação automática da conectividade do banco de dados na inicialização
• Salvaguardas de Produção: Aplicação de read_only por banco de dados (bloqueia escritas através das ferramentas query_* e execute_*), truncamento de resultados max_rows com avisos explícitos e timeouts por consulta

Salvaguardas de Produção

Proteja sessões de agentes contra consultas descontroladas e escritas acidentais:

Configuração	Escopo	Efeito
"read_only": true	por banco de dados	Bloqueia declarações de escrita (INSERT, UPDATE, DELETE, DDL, CTEs que modificam dados, escritas empilhadas) através das ferramentas de consulta e execução, e aplica rejeição no próprio mecanismo do banco de dados em PostgreSQL/TimescaleDB (default_transaction_read_only=on) e MySQL (transaction_read_only=1); SQLite abre mode=ro. A classificação remove comentários e literais de string e assume negação por padrão para declarações não reconhecidas.
"max_rows": 1000	por banco de dados	Trunca conjuntos de resultados em N linhas e anexa um aviso explícito [Truncated] para que o modelo saiba refinar sua consulta em vez de perder contexto. 0 (padrão) significa ilimitado.
"masking_rules": [...]	por banco de dados	Mascara valores de colunas de resultado cujo nome corresponde à regex de uma regra antes de saírem do servidor — aplica-se a todas as formas de consulta, incluindo SELECT *. Estratégias: "fixed_string" (substituir por value), "null" e "partial" (keep_last caracteres finais visíveis; valores mais curtos totalmente mascarados). A primeira regra correspondente vence; padrões inválidos ou estratégias desconhecidas abortam o carregamento da configuração (falha fechada); contagens de células mascaradas são relatadas no rodapé do resultado. Renomear uma coluna com um alias contorna a correspondência de nome por design. Veja docs/design/column-masking-scoping.md.
"query_timeout": 30	por banco de dados	Cancela declarações que excedem o timeout em segundos; aplicado na camada de repositório para todas as ferramentas (consultas, declarações, transações, explain, inspeção de esquema). Não definido assume 30s; -1 desativa. Implantações somente com env podem definir QUERY_TIMEOUT_SECONDS para preencher conexões sem um valor explícito (JSON mantém precedência).

| DB_MCP_AUDIT_LOG=/path/audit.jsonl | processo | Anexa um registro JSONL por declaração executada — timestamp, op (query/execute/tx_*), banco de dados, declaração (limitada a 10k caracteres), duração, erro. Inclui tentativas rejeitadas contra bancos de dados somente leitura. Escritas de melhor esforço nunca falham uma consulta; o arquivo é criado com 0600. |

Defesa em profundidade: somente leitura é aplicada em três camadas — classificador da aplicação, padrões de sessão do mecanismo e (recomendado) usuários de banco de dados com privilégios mínimos. Oracle atualmente depende do classificador mais privilégios de usuário.

Bancos de Dados Suportados

Banco de Dados	Status	Recursos
MySQL	✅ Suporte Total	Consultas, Transações, Análise de Esquema, Insights de Desempenho
PostgreSQL	✅ Suporte Total (v9.6-17)	Consultas, Transações, Análise de Esquema, Insights de Desempenho
SQLite	✅ Suporte Total	Bancos de dados baseados em arquivo e em memória, suporte a criptografia SQLCipher
Oracle	✅ Suporte Total (10g-23c)	Consultas, Transações, Análise de Esquema, RAC, Cloud Wallet, TNS
TimescaleDB	✅ Suporte Total	Consultas de Séries Temporais, Descoberta de Hypertable (políticas de escrita via SQL)

Opções de Implantação

O DB MCP Server pode ser implantado de várias maneiras para atender diferentes ambientes e necessidades de integração:

Implantação com Docker

# Pull the latest image
docker pull freepeak/db-mcp-server:latest

# Run with mounted config file
docker run -p 9092:9092 \
  -v $(pwd)/config.json:/app/my-config.json \
  -e TRANSPORT_MODE=sse \
  -e CONFIG_PATH=/app/my-config.json \
  -e DB_MCP_API_KEY=replace-me-with-a-long-random-string \
  freepeak/db-mcp-server

Nota: Monte em /app/my-config.json pois o contêiner tem um arquivo padrão em /app/config.json.

Autenticação por Chave de API

Os transportes SSE e streamable-HTTP aceitam um cabeçalho Authorization: Bearer <key>. Defina DB_MCP_API_KEY (ou passe -api-key) ao iniciar o contêiner Docker; os clientes devem então enviar o token bearer correspondente em cada requisição:

curl -H "Authorization: Bearer replace-me-with-a-long-random-string" \
     http://localhost:9092/sse

Quando nenhuma chave de API está configurada, o transporte permanece aberto (uso de usuário único / desenvolvimento). O middleware reside em internal/delivery/mcp.APIKeyAuth e é exportado para que você possa compô-lo com seu próprio proxy reverso se você colocar o contêiner atrás de nginx, Caddy ou Traefik.

Modo STDIO (Integração com IDE)

# Run the server in STDIO mode
./bin/server -t stdio -c config.json

Para integração com o Cursor IDE, adicione em .cursor/mcp.json:

{
  "mcpServers": {
    "stdio-db-mcp-server": {
      "command": "/path/to/db-mcp-server/server",
      "args": ["-t", "stdio", "-c", "/path/to/config.json"]
    }
  }
}

Modo SSE (Server-Sent Events)

# Default configuration (localhost:9092)
./bin/server -t sse -c config.json

# Custom host and port
./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.json

Endpoint de conexão do cliente: http://localhost:9092/sse

Instalação a partir do Código Fonte

# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server

# Build the server
make build

# Run the server
./bin/server -t sse -c config.json

Configuração

Arquivo de Configuração de Banco de Dados

Crie um arquivo config.json com suas conexões de banco de dados:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "mysql1",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1",
      "query_timeout": 60,
      "max_open_conns": 20,
      "max_idle_conns": 5,
      "conn_max_lifetime_seconds": 300,
      "conn_max_idle_time_seconds": 60,
      "read_only": false,
      "max_rows": 1000,
      "masking_rules": [
        { "pattern": "(?i)email", "strategy": "fixed_string", "value": "***MASKED***" },
        { "pattern": "(?i)(ssn|tax_id)", "strategy": "null" }
      ]
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "postgres1",
      "port": 5432,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "sqlite_app",
      "type": "sqlite",
      "database_path": "./data/app.db",
      "journal_mode": "WAL",
      "cache_size": 2000,
      "read_only": false,
      "use_modernc_driver": true,
      "query_timeout": 30,
      "max_open_conns": 1,
      "max_idle_conns": 1
    },
    {
      "id": "sqlite_encrypted",
      "type": "sqlite",
      "database_path": "./data/secure.db",
      "encryption_key": "your-secret-key-here",
      "journal_mode": "WAL",
      "use_modernc_driver": false
    },
    {
      "id": "sqlite_memory",
      "type": "sqlite",
      "database_path": ":memory:",
      "cache_size": 1000,
      "use_modernc_driver": true
    }
  ]
}

Opções de Linha de Comando

# Basic syntax
./bin/server -t <transport> -c <config-file>

# SSE transport options
./bin/server -t sse -host <hostname> -port <port> -c <config-file>

# Lazy loading mode (recommended for 10+ databases)
./bin/server -t stdio -c <config-file> --lazy-loading

# Customize log directory (useful for multi-project setups)
./bin/server -t stdio -c <config-file> -log-dir /tmp/db-mcp-logs

# Inline database configuration
./bin/server -t stdio -db-config '{"connections":[...]}'

# Environment variable configuration
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdio

Flags Disponíveis:

• -t, -transport: Modo de transporte (stdio ou sse)
• -c, -config: Caminho para o arquivo de configuração de banco de dados
• -p, -port: Porta do servidor para modo SSE (padrão: 9092)
• -h, -host: Host do servidor para modo SSE (padrão: localhost)
• -log-level: Nível de log (debug, info, warn, error)
• -log-dir: Diretório para arquivos de log (padrão: ./logs no diretório atual)
• -db-config: Configuração de banco de dados JSON inline

Variáveis de Ambiente

Valores em um arquivo .env são carregados primeiro; variáveis de ambiente reais têm precedência. Um arquivo de configuração JSON (CONFIG_PATH/DB_CONFIG_FILE) substitui variáveis de ambiente por banco de dados.

Variável	Padrão	Finalidade
CONFIG_PATH / DB_CONFIG_FILE	config.json	Caminho para a configuração JSON multi-banco
DB_CONFIG	—	Configuração de banco de dados JSON inline (alternativa a um arquivo)
TRANSPORT_MODE	sse	Modo de transporte quando -t não é passado
SERVER_PORT	9090	Porta HTTP para modo SSE
LOG_LEVEL	info	Verbosidade do log (debug, info, warn, error)
DISABLE_LOGGING	false	true/1 silencia o log completamente
DB_TYPE, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME	padrões do mecanismo	Fallback de banco único quando não há configuração JSON
QUERY_TIMEOUT_SECONDS	não definido	Preenche conexões que não definem seu próprio query_timeout; negativo desativa o limite. Configurações JSON mantêm precedência.

Opções de Configuração do SQLite

Ao usar bancos de dados SQLite, você pode aproveitar estas opções de configuração adicionais:

Parâmetros de Conexão do SQLite

Parâmetro	Tipo	Padrão	Descrição
database_path	string	Obrigatório	Caminho para o arquivo de banco de dados SQLite ou :memory: para em memória
encryption_key	string	-	Chave para bancos de dados criptografados SQLCipher
read_only	boolean	false	Abrir banco de dados em modo somente leitura
max_rows	integer	ilimitado	Máximo de linhas retornadas por consulta; resultados maiores são truncados com um aviso explícito. Funciona em todos os tipos de banco de dados
cache_size	integer	2000	Tamanho do cache do SQLite em páginas
journal_mode	string	"WAL"	Modo de journal: DELETE, TRUNCATE, PERSIST, WAL, OFF
use_modernc_driver	boolean	true	Usar modernc.org/sqlite (sem CGO) ou mattn/go-sqlite3

Exemplos de SQLite

Banco de Dados Básico em Arquivo

{
  "id": "my_sqlite_db",
  "type": "sqlite",
  "database_path": "./data/myapp.db",
  "journal_mode": "WAL",
  "cache_size": 2000
}

Banco de Dados Criptografado (SQLCipher)

{
  "id": "encrypted_db",
  "type": "sqlite",
  "database_path": "./data/secure.db",
  "encryption_key": "your-secret-encryption-key",
  "use_modernc_driver": false
}

Banco de Dados em Memória

{
  "id": "memory_db",
  "type": "sqlite",
  "database_path": ":memory:",
  "cache_size": 1000
}

Banco de Dados Somente Leitura

{
  "id": "reference_data",
  "type": "sqlite",
  "database_path": "./data/reference.db",
  "read_only": true,
  "journal_mode": "DELETE"
}

Opções de Configuração do Oracle

Ao usar bancos de dados Oracle, você pode aproveitar estas opções de configuração adicionais:

Parâmetros de Conexão do Oracle

Parâmetro	Tipo	Padrão	Descrição
host	string	Obrigatório	Host do banco de dados Oracle
port	integer	1521	Porta do listener Oracle
service_name	string	-	Nome do serviço (recomendado para RAC)
sid	string	-	Identificador do sistema (legado, use service_name)
user	string	Obrigatório	Nome de usuário do banco de dados
password	string	Obrigatório	Senha do banco de dados
wallet_location	string	-	Caminho para o diretório do wallet Oracle Cloud
tns_admin	string	-	Caminho para o diretório contendo tnsnames.ora
tns_entry	string	-	Entrada nomeada de tnsnames.ora
edition	string	-	Nome da edição para Edition-Based Redefinition
pooling	boolean	false	Habilitar pool de conexões no nível do driver
standby_sessions	boolean	false	Permitir consultas em bancos de dados standby
nls_lang	string	AMERICAN_AMERICA.AL32UTF8	Configuração de conjunto de caracteres

Exemplos de Oracle

Conexão Básica Oracle (Desenvolvimento)

{
  "id": "oracle_dev",
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "service_name": "XEPDB1",
  "user": "testuser",
  "password": "testpass",
  "max_open_conns": 50,
  "max_idle_conns": 10,
  "conn_max_lifetime_seconds": 1800
}

Oracle com SID (Legado)

{
  "id": "oracle_legacy",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "sid": "ORCL",
  "user": "app_user",
  "password": "app_password"
}

Oracle Cloud Autonomous Database (com Wallet)

{
  "id": "oracle_cloud",
  "type": "oracle",
  "user": "ADMIN",
  "password": "your-cloud-password",
  "wallet_location": "/path/to/wallet_DBNAME",
  "service_name": "dbname_high"
}

Oracle RAC (Real Application Clusters)

{
  "id": "oracle_rac",
  "type": "oracle",
  "host": "scan.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "max_open_conns": 100,
  "max_idle_conns": 20
}

Oracle com Entrada TNS

{
  "id": "oracle_tns",
  "type": "oracle",
  "tns_admin": "/opt/oracle/network/admin",
  "tns_entry": "PROD_DB",
  "user": "app_user",
  "password": "app_password"
}

Oracle com Edition-Based Redefinition

{
  "id": "oracle_ebr",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "edition": "v2_0"
}

Prioridade da String de Conexão Oracle

Quando múltiplos métodos de conexão estão configurados, a seguinte prioridade é usada:

1. Entrada TNS (se tns_entry e tns_admin estiverem configurados)
2. Wallet (se wallet_location estiver configurado) - para Oracle Cloud
3. Padrão (host:porta/nome_do_serviço) - método padrão

Ferramentas Disponíveis

Para cada banco de dados conectado, o DB MCP Server gera automaticamente estas ferramentas especializadas:

Ferramentas de Consulta

Nome da Ferramenta	Descrição
query_<db_id>	Executa consultas SELECT e retorna resultados como um conjunto de dados tabular
execute_<db_id>	Executa declarações de manipulação de dados (INSERT, UPDATE, DELETE)
transaction_<db_id>	Inicia, confirma e reverte transações

Ferramentas de Esquema

Nome da Ferramenta	Descrição
schema_<db_id>	Obtém informações sobre tabelas, colunas, índices e chaves estrangeiras
generate_schema_<db_id>	Gera SQL ou código a partir do esquema do banco de dados

Ferramentas de Desempenho

Nome da Ferramenta	Descrição
performance_<db_id>	Analisa o desempenho de consultas por meio de ações: stats / slow_queries (rastreador em processo), engine_slow_queries (pg_stat_statements / tabelas de digest do MySQL / v$sqlarea do Oracle), suggest (lint estático de SQL), suggest_indexes (aconselhamento heurístico de CREATE INDEX para uma declaração, compostos com igualdade primeiro, verifique com EXPLAIN), validate_suggestions (PostgreSQL: instala as mesmas sugestões como índices hipotéticos sem custo por meio da extensão hypopg e relata se o planejador realmente escolhe cada uma — validação de verdade fundamental em vez de EXPLAIN manual), workload_suggestions (mesma análise nas declarações de workload caras top-N, ponderadas por execuções), index_health (índices duplicados/redundantes/não utilizados/inválidos e descobertas de bloat de tabela a partir de catálogos; evidência de uso onde existem estatísticas do mecanismo), db_health (tudo o que o index_health cobre, mais pressão de utilização de conexão vs max_connections), reset
explain_<db_id>	Mostra o plano de execução para uma declaração SQL sem executá-la; analyze: true executa com estatísticas de tempo/buffers (PostgreSQL/MySQL). Gravações permanecem bloqueadas em bancos de dados somente leitura
describe_<db_id>	Inspeciona as colunas, índices e estimativa de linhas de uma tabela por meio de consultas de catálogo do mecanismo
health_<db_id>	Relata conectividade, latência de ping, estado do pool de conexões e estatísticas do mecanismo (taxa de acerto do cache de buffer do PostgreSQL, eficiência do buffer InnoDB do MySQL)

Ferramentas TimescaleDB

Para bancos de dados PostgreSQL com a extensão timescaledb instalada, estas ferramentas especializadas adicionais são registradas automaticamente na inicialização (o registro é orientado por configuração, portanto também funciona sob --lazy-loading; cada manipulador verifica a extensão no momento da chamada e retorna um erro acionável quando ela está ausente):

Nome da Ferramenta	Descrição
timescaledb_timeseries_query_<db_id>	Executa consultas otimizadas de séries temporais com agrupamento de tempo (time_bucket), filtragem e funções de janela
timescaledb_analyze_timeseries_<db_id>	Analisa padrões de séries temporais (tendência, resumo de sazonalidade) para uma tabela/coluna
timescaledb_list_hypertables_<db_id>	Lista hypertables com sua coluna de tempo e contagem de dimensões (somente leitura)
timescaledb_compression_settings_<db_id>	Mostra a configuração de compressão para hypertables (somente leitura)
timescaledb_retention_policy_<db_id>	Mostra políticas de retenção configuradas (somente leitura)
timescaledb_list_continuous_aggregates_<db_id>	Lista agregações contínuas com intervalo de bucket e política de atualização (somente leitura)
timescaledb_continuous_aggregate_info_<db_id>	Inspeciona uma agregação contínua em detalhes (somente leitura)

No modo unificado, as mesmas sete ferramentas aparecem uma vez como timescaledb_timeseries_query, timescaledb_analyze_timeseries, timescaledb_list_hypertables, timescaledb_compression_settings, timescaledb_retention_policy, timescaledb_list_continuous_aggregates e timescaledb_continuous_aggregate_info, cada uma recebendo um parâmetro database obrigatório.

Nota de escopo: a descoberta somente leitura acima passa pelo pipeline de consulta e, portanto, permanece utilizável em bancos de dados read_only; cada manipulador verifica a extensão timescaledb primeiro. Operações de política de gravação (criação de hypertable, alternância de compressão, adicionar/remover políticas de retenção ou atualização) permanecem não expostas — use SQL simples por meio das ferramentas de consulta/execução enquanto isso. Para documentação detalhada, consulte TIMESCALEDB_TOOLS.md.

Modo de Ferramenta Unificada

Se você conectar muitos bancos de dados (5+), a nomenclatura de ferramentas por banco gera um grande número de ferramentas (5 × N). Alguns clientes MCP — Claude em particular — aplicam limites rigorosos no número total de ferramentas e no tamanho da descrição das ferramentas, o que pode fazer com que o agente falhe ao carregar o servidor, ignore ferramentas ou se recuse a chamá-las. A issue #18 documenta exatamente esse sintoma: "o db-mcp-server não funciona corretamente com Claude, mesmo funcionando bem com OpenAI".

Para esses clientes, inicie o servidor com o sinalizador --unified-tools para registrar seis ferramentas consolidadas (query, execute, transaction, performance, explain, describe, schema, filter_tables) em vez de ferramentas por banco de dados:

./bin/server -t stdio -c config.json --unified-tools

Custo de janela de contexto (medido, TestToolTokenBenchmark, re-verificado em 2026-08 via scripts/token-benchmark.sh): o modo unificado custa ~1,25–1,6k tokens independentemente de quantos bancos de dados estão conectados, enquanto o modo por banco custa ~800 tokens por banco de dados (7 ferramentas cada) — 10 bancos de dados conectados ≈ 8k tokens, uma economia de 80% no payload de rede com o modo unificado. Com apenas um banco de dados, a nomenclatura por banco é ligeiramente mais barata; o modo unificado vence a partir de dois bancos de dados e escala de forma plana a partir daí. Re-meça o payload real de rede você mesmo com scripts/token-benchmark.sh; metodologia e resultados em docs/benchmark-token-efficiency.md.

In unified mode, each tool accepts a required `database` parameter that names
which database the call should target. See the [Configuration](#configuration)
section for the full list of available databases. This dramatically reduces the
tool count and the cumulative description size, which resolves the Claude
compatibility issues.

For very large configurations, also enable `--lazy-loading` so that startup
doesn't open connections to databases that may never be queried during the
session.

## Examples

### Querying Multiple Databases

```sql
-- Query the MySQL database
query_mysql1("SELECT * FROM users LIMIT 10")

-- Query the PostgreSQL database in the same context
query_postgres1("SELECT * FROM products WHERE price > 100")

-- Query the SQLite database
query_sqlite_app("SELECT * FROM local_data WHERE created_at > datetime('now', '-1 day')")

-- Query the Oracle database
query_oracle_dev("SELECT * FROM employees WHERE hire_date > SYSDATE - 30")

Gerenciando Transações

A ferramenta transaction_<db_id> suporta as ações begin, execute, commit e rollback. Cada begin retorna um transactionId; passe-o de volta para encadear declarações e para confirmar ou reverter:

// 1. Start a transaction
{ "action": "begin" }
// → { "transactionId": "tx_mysql1_1730000000000000000" }

// 2. Execute statements within the transaction
{
  "action": "execute",
  "transactionId": "tx_mysql1_1730000000000000000",
  "statement": "INSERT INTO orders (customer_id, product_id) VALUES (1, 2)"
}

// 3a. Commit — persists all staged statements
{ "action": "commit", "transactionId": "tx_mysql1_1730000000000000000" }

// 3b. OR rollback — discards all staged statements
{ "action": "rollback", "transactionId": "tx_mysql1_1730000000000000000" }

IDs de transação desconhecidos ou já aposentados retornam um erro claro em vez de um sucesso silencioso, para que os agentes possam detectar e se recuperar de situações de transação perdida.

Explorando o Esquema do Banco de Dados

-- Get all tables in the database
schema_mysql1("tables")

-- Get columns for a specific table
schema_mysql1("columns", "users")

-- Get constraints
schema_mysql1("constraints", "orders")

Trabalhando com Recursos Específicos do SQLite

-- Create a table in SQLite
execute_sqlite_app("CREATE TABLE IF NOT EXISTS local_cache (key TEXT PRIMARY KEY, value TEXT, timestamp DATETIME)")

-- Use SQLite-specific date functions
query_sqlite_app("SELECT * FROM events WHERE date(created_at) = date('now')")

-- Query SQLite master table for schema information
query_sqlite_app("SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")

-- Performance optimization with WAL mode
execute_sqlite_app("PRAGMA journal_mode = WAL")
execute_sqlite_app("PRAGMA synchronous = NORMAL")

Trabalhando com Recursos Específicos do Oracle

-- Query user tables (excludes system schemas)
query_oracle_dev("SELECT table_name FROM user_tables ORDER BY table_name")

-- Use Oracle-specific date functions
query_oracle_dev("SELECT employee_id, hire_date FROM employees WHERE hire_date >= TRUNC(SYSDATE, 'YEAR')")

-- Oracle sequence operations
execute_oracle_dev("CREATE SEQUENCE emp_seq START WITH 1000 INCREMENT BY 1")
query_oracle_dev("SELECT emp_seq.NEXTVAL FROM DUAL")

-- Oracle-specific data types
query_oracle_dev("SELECT order_id, TO_CHAR(order_date, 'YYYY-MM-DD HH24:MI:SS') FROM orders")

-- Get schema metadata from Oracle data dictionary
query_oracle_dev("SELECT column_name, data_type, nullable FROM user_tab_columns WHERE table_name = 'EMPLOYEES'")

-- Use Oracle analytic functions
query_oracle_dev("SELECT employee_id, salary, RANK() OVER (ORDER BY salary DESC) as salary_rank FROM employees")

Solução de Problemas

Problemas Comuns

• Falhas de Conexão: Verifique a conectividade de rede e as credenciais do banco de dados
• Erros de Permissão: Garanta que o usuário do banco de dados tenha as permissões apropriadas
• Problemas de Tempo Limite: Verifique a configuração de query_timeout na sua configuração

Logs

Ative o registro detalhado para solução de problemas:

./bin/server -t sse -c config.json -v

Testes

Executando Testes

O projeto inclui testes unitários e de integração abrangentes para todos os bancos de dados suportados.

Testes Unitários

Execute testes unitários (nenhum banco de dados necessário):

make test
# or
go test -short ./...

Testes de Integração

Os testes de integração exigem instâncias de banco de dados em execução. Fornecemos configurações do Docker Compose para facilitar a configuração.

Testar Todos os Bancos de Dados:

# Start test databases
docker-compose -f docker-compose.test.yml up -d

# Run all integration tests
go test ./... -v

# Stop test databases
docker-compose -f docker-compose.test.yml down -v

Testar Banco de Dados Oracle:

# Start Oracle test environment
./oracle-test.sh start

# Run Oracle tests
./oracle-test.sh test
# or manually
ORACLE_TEST_HOST=localhost go test -v ./pkg/db -run TestOracle
ORACLE_TEST_HOST=localhost go test -v ./pkg/dbtools -run TestOracle

# Stop Oracle test environment
./oracle-test.sh stop

# Full cleanup (removes volumes)
./oracle-test.sh cleanup

Testar TimescaleDB:

# Start TimescaleDB test environment
./timescaledb-test.sh start

# Run TimescaleDB tests
TIMESCALEDB_TEST_HOST=localhost go test -v ./pkg/db/timescale ./internal/delivery/mcp

# Stop TimescaleDB test environment
./timescaledb-test.sh stop

Testes de Regressão

Execute testes de regressão abrangentes em todos os tipos de banco de dados:

# Ensure all test databases are running
docker-compose -f docker-compose.test.yml up -d
./oracle-test.sh start

# Run regression tests
MYSQL_TEST_HOST=localhost \
POSTGRES_TEST_HOST=localhost \
ORACLE_TEST_HOST=localhost \
go test -v ./pkg/db -run TestRegression

# Run connection pooling tests
go test -v ./pkg/db -run TestConnectionPooling

Integração Contínua

Todos os testes são executados automaticamente em cada pull request via GitHub Actions. O pipeline de CI inclui:

• Testes Unitários: Testes rápidos que não exigem conexões de banco de dados
• Testes de Integração: Testes contra bancos de dados MySQL, PostgreSQL, SQLite e Oracle
• Testes de Regressão: Testes abrangentes garantindo compatibilidade retroativa
• Linting: Verificações de qualidade de código com golangci-lint

Contribuindo

Aceitamos contribuições para o projeto DB MCP Server! Para contribuir:

1. Faça um fork do repositório
2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'feat: add amazing feature')
4. Envie para o branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

Consulte nosso arquivo CONTRIBUTING.md para diretrizes detalhadas.

Testando Suas Alterações

Antes de enviar um pull request, certifique-se de:

1. Todos os testes unitários passam: go test -short ./...
2. Os testes de integração passam para os bancos de dados afetados
3. O código segue as diretrizes de estilo do projeto: golangci-lint run ./...
4. Novos recursos incluem cobertura de teste apropriada

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.