{"_id":"@fastmcp-me/mcp-db-bridge","name":"@fastmcp-me/mcp-db-bridge","dist-tags":{"latest":"2.0.7"},"versions":{"2.0.7":{"name":"@fastmcp-me/mcp-db-bridge","version":"2.0.7","description":"MCP server for MySQL, PostgreSQL & SQLite with granular permissions, multi-DB support, and cloud-ready SSL/TLS. Built with adapter pattern for extensibility.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/fastmcp-me/mcp-db-bridge.git"},"bugs":{"url":"https://github.com/fastmcp-me/mcp-db-bridge/issues"},"homepage":"https://github.com/fastmcp-me/mcp-db-bridge#readme","type":"module","main":"dist/index.js","module":"index.ts","preferGlobal":true,"bin":{"mcp-server-mysql":"dist/index.js"},"scripts":{"start":"node dist/index.js","dev":"tsx index.ts","build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","watch":"tsc --watch","setup:test:db":"tsx scripts/setup-test-db.ts","pretest":"pnpm run setup:test:db","test":"pnpm run setup:test:db && vitest run","test:socket":"pnpm run setup:test:db && vitest run tests/integration/socket-connection.test.ts","test:watch":"pnpm run setup:test:db && vitest","test:coverage":"vitest run --coverage","test:unit":"vitest run --config vitest.unit.config.ts","test:integration":"vitest run --config vitest.integration.config.ts","test:e2e":"vitest run --config vitest.e2e.config.ts","stdio":"node dist/index.js --stdio","exec":" pnpm build && npx node --env-file=.env dist/index.js","lint":"eslint ."},"dependencies":{"@modelcontextprotocol/sdk":"1.15.1","better-sqlite3":"^9.4.0","dotenv":"^16.5.0","express":"^5.1.0","mysql2":"^3.14.1","node-sql-parser":"^5.3.9","pg":"^8.11.0","zod":"^3.25.67"},"devDependencies":{"@types/better-sqlite3":"^7.6.9","@types/express":"^5.0.3","@types/node":"^20.17.50","@types/pg":"^8.11.0","@typescript-eslint/eslint-plugin":"^8.35.0","@typescript-eslint/parser":"^8.35.0","eslint":"^9.27.0","shx":"^0.3.4","ts-node":"^10.9.2","tslib":"^2.8.1","tsx":"^4.19.4","typescript":"^5.8.3","vitest":"^1.6.1"},"keywords":["node","mcp","ai","cursor","mcp-server","modelcontextprotocol","smithery","mcp-get","mcp-put","mcp-post","mcp-delete","mcp-patch","mcp-head"],"_id":"@fastmcp-me/mcp-db-bridge@2.0.7","gitHead":"cac4236a1af693ee45d144fa817d22bef699cf62","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-ExQli+/kaR7TZyd5sAHqiWvuTd+VQ9ANn8K3G9YuAcBsSTu0sRoZWsOfgRfK0BG60mnWSXPL2ArxMdnE7/M07A==","shasum":"b53539c448146d6505f2f7ac8acfd1c8fff1d07c","tarball":"https://registry.npmjs.org/@fastmcp-me/mcp-db-bridge/-/mcp-db-bridge-2.0.7.tgz","fileCount":16,"unpackedSize":74992,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDeq+/WBv5mWHAMq3njkkhmUR6i2bnARHKAKNwmgqYT7gIgYSxGvPa7Gwsl8Xb+6cWNEPSygN2pz4Um+cQGjBhx08g="}]},"_npmUser":{"name":"sultanlive","email":"sultan.kadyrkesh@yandex.ru"},"directories":{},"maintainers":[{"name":"sultanlive","email":"sultan.kadyrkesh@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-db-bridge_2.0.7_1761605097687_0.7333658147165665"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-27T22:44:57.611Z","2.0.7":"2025-10-27T22:44:57.878Z","modified":"2025-10-27T22:44:58.220Z"},"maintainers":[{"name":"sultanlive","email":"sultan.kadyrkesh@yandex.ru"}],"description":"MCP server for MySQL, PostgreSQL & SQLite with granular permissions, multi-DB support, and cloud-ready SSL/TLS. Built with adapter pattern for extensibility.","homepage":"https://github.com/fastmcp-me/mcp-db-bridge#readme","keywords":["node","mcp","ai","cursor","mcp-server","modelcontextprotocol","smithery","mcp-get","mcp-put","mcp-post","mcp-delete","mcp-patch","mcp-head"],"repository":{"type":"git","url":"git+https://github.com/fastmcp-me/mcp-db-bridge.git"},"bugs":{"url":"https://github.com/fastmcp-me/mcp-db-bridge/issues"},"license":"MIT","readme":"[![Add to Cursor](https://fastmcp.me/badges/cursor_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n[![Add to VS Code](https://fastmcp.me/badges/vscode_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n[![Add to Claude](https://fastmcp.me/badges/claude_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n[![Add to ChatGPT](https://fastmcp.me/badges/chatgpt_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n[![Add to Codex](https://fastmcp.me/badges/codex_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n[![Add to Gemini](https://fastmcp.me/badges/gemini_dark.svg)](https://fastmcp.me/MCP/Details/1338/db-bridge)\n\n# mcp-db-bridge\n\n[English](#english) | [Português](#português)\n\n---\n\n## English\n\n[![Version](https://img.shields.io/npm/v/mcp-db-bridge)](https://www.npmjs.com/package/mcp-db-bridge)\n\n\nMCP (Model Context Protocol) server for MySQL, PostgreSQL & SQLite with granular permissions, multi-DB support, and cloud-ready SSL/TLS. Built with adapter pattern for extensibility.\n\n### Features\n\n- 🔌 **Multi-Database**: MySQL, PostgreSQL, SQLite\n- 🏗️ **Adapter Pattern**: Clean and extensible architecture\n- ☁️ **Cloud-Ready**: SSL/TLS for AWS RDS, Google Cloud SQL, Azure Database\n- 🔒 **Security First**: Read-only mode + granular schema permissions\n- 🌐 **Multi-DB Mode**: Simultaneous access to multiple schemas/databases\n- 🔄 **Transactions**: Automatic BEGIN/COMMIT/ROLLBACK\n- 🚀 **HTTP Mode**: Optional remote HTTP server (Express)\n\n### Installation\n\n```bash\nnpm install mcp-db-bridge\n# or\npnpm add mcp-db-bridge\n```\n\n### Quick Start\n\n#### MySQL (Local)\n\n```bash\n# .env\nDB_TYPE=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### PostgreSQL (Local)\n\n```bash\n# .env\nDB_TYPE=postgresql\nDB_HOST=127.0.0.1\nDB_PORT=5432\nDB_USER=postgres\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### SQLite (In-Memory)\n\n```bash\n# .env\nDB_TYPE=sqlite\nSQLITE_DB=:memory:\n```\n\n#### Run\n\n```bash\npnpm build\npnpm start\n# or\nnode dist/index.js\n```\n\n### Configuration\n\n#### Database Types\n\n```bash\nDB_TYPE=mysql          # MySQL\nDB_TYPE=postgresql     # PostgreSQL\nDB_TYPE=sqlite         # SQLite\n```\n\n#### Connection Settings\n\n**Generic (All Databases)**\n\n```bash\nDB_HOST=127.0.0.1\nDB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb           # Leave empty for multi-DB mode\nDB_CONNECTION_LIMIT=10\n```\n\n**MySQL-Specific (Backward Compatibility)**\n\n```bash\nMYSQL_HOST=127.0.0.1\nMYSQL_PORT=3306\nMYSQL_USER=root\nMYSQL_PASS=password\nMYSQL_DB=mydb\nMYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unix socket (priority over host/port)\n```\n\n**PostgreSQL-Specific**\n\n```bash\nPOSTGRESQL_HOST=127.0.0.1\nPOSTGRESQL_PORT=5432\nPOSTGRESQL_DB=mydb\n```\n\n**SQLite-Specific**\n\n```bash\nSQLITE_DB=:memory:              # In-memory database\nSQLITE_DB=/var/lib/app/data.db  # File-based database\n```\n\n### Security & Permissions\n\n#### Read-Only Mode\n\nBlocks **all** write operations at application level:\n\n```bash\nDB_READ_ONLY_MODE=true\n```\n\n#### Global Write Permissions\n\nFine-grained operation control by type (applied globally):\n\n```bash\nALLOW_INSERT_OPERATION=true   # Allow INSERT\nALLOW_UPDATE_OPERATION=true   # Allow UPDATE\nALLOW_DELETE_OPERATION=false  # Block DELETE\nALLOW_DDL_OPERATION=false     # Block CREATE/ALTER/DROP/TRUNCATE\n```\n\n#### Schema-Specific Permissions\n\nOverride global permissions for specific schemas:\n\n```bash\n# Format: \"schema1:true,schema2:false,schema3:true\"\nSCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true\nSCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true\nSCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false\nSCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false\n```\n\n**How it works:**\n- If schema has specific permission → use it\n- Otherwise → use global flag\n\n**Example:**\n```bash\n# Global: INSERT blocked\nALLOW_INSERT_OPERATION=false\n\n# test_db can insert, prod_db cannot\nSCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false\n\n# Result:\n# - INSERT on test_db: ✅ allowed (schema permission)\n# - INSERT on prod_db: ❌ blocked (schema permission)\n# - INSERT on other_db: ❌ blocked (global permission)\n```\n\n### Multi-DB Mode\n\nAccess multiple databases/schemas through a single connection.\n\n#### Activation\n\nLeave `DB_NAME` empty (MySQL/PostgreSQL only):\n\n```bash\nDB_TYPE=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_USER=root\nDB_PASS=password\nDB_NAME=                # Empty = multi-DB mode\n```\n\n#### Write Protection\n\nBy default, multi-DB mode is **read-only** for security. To allow writes:\n\n```bash\nMULTI_DB_WRITE_MODE=true  # ⚠️ Use with caution!\n```\n\n**Recommendation:** Use `SCHEMA_*_PERMISSIONS` for granular control instead of `MULTI_DB_WRITE_MODE=true`.\n\n#### Complete Example\n\n```bash\n# Multi-DB with granular permissions\nDB_TYPE=mysql\nDB_NAME=                                    # Multi-DB mode\nALLOW_INSERT_OPERATION=false                # Global: blocked\nSCHEMA_INSERT_PERMISSIONS=test_db:true      # Exception: test_db can insert\nSCHEMA_UPDATE_PERMISSIONS=test_db:true      # Exception: test_db can update\nSCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db: DELETE blocked\nSCHEMA_DDL_PERMISSIONS=test_db:true         # test_db: DDL allowed\n```\n\n### SSL/TLS for Cloud Databases\n\n#### AWS RDS (MySQL/PostgreSQL)\n\n```bash\nDB_TYPE=mysql\nDB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com\nDB_PORT=3306\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\n# Optional: DB_SSL_CA=/path/to/aws-rds-ca-cert.pem\n```\n\n#### Google Cloud SQL (PostgreSQL)\n\n```bash\nDB_TYPE=postgresql\nDB_HOST=34.123.45.67\nDB_PORT=5432\nDB_SSL=true\nDB_SSL_CA=/path/to/server-ca.pem\nDB_SSL_CERT=/path/to/client-cert.pem\nDB_SSL_KEY=/path/to/client-key.pem\n```\n\n#### Azure Database for MySQL\n\n```bash\nDB_TYPE=mysql\nDB_HOST=myserver.mysql.database.azure.com\nDB_PORT=3306\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\n```\n\n### Remote MCP (HTTP Server)\n\nRun MCP server via HTTP with authentication:\n\n```bash\n# .env\nIS_REMOTE_MCP=true\nREMOTE_SECRET_KEY=your-secret-key-here\nPORT=3000\n```\n\nEndpoint: `POST http://localhost:3000/mcp`\n\nHeader: `Authorization: Bearer your-secret-key-here`\n\n### Architecture\n\n```\nsrc/\n├── db/\n│   ├── adapters/\n│   │   ├── types.ts              # Interfaces and types\n│   │   ├── factory.ts            # Factory pattern\n│   │   ├── mysql.adapter.ts      # MySQL via mysql2\n│   │   ├── postgresql.adapter.ts # PostgreSQL via pg\n│   │   └── sqlite.adapter.ts     # SQLite via better-sqlite3\n│   ├── index.ts                  # Core query handlers\n│   ├── utils.ts                  # SQL parsing (node-sql-parser)\n│   └── permissions.ts            # Schema permission checks\n├── config/\n│   └── index.ts                  # Environment configuration\n├── utils/\n│   └── index.ts                  # Logging & utilities\n└── types/\n    └── index.ts                  # Type definitions\n```\n\n#### Adapter Pattern\n\nEach adapter implements the `DatabaseAdapter` interface:\n\n```typescript\nexport interface DatabaseAdapter {\n  readonly type: DatabaseType;\n  createPool(config: ConnectionConfig): Promise<DatabasePool>;\n  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;\n  setReadOnly(connection: DatabaseConnection): Promise<void>;\n  unsetReadOnly(connection: DatabaseConnection): Promise<void>;\n  normalizeResult(result: any): NormalizedResult;\n  supportsReadOnlyMode(): boolean;\n}\n```\n\n#### Transaction Flows\n\n**Read Operations:**\n```\nBEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE\n```\n\n**Write Operations:**\n```\nBEGIN → QUERY → COMMIT (or ROLLBACK on error)\n```\n\n### Examples\n\n#### MySQL with Unix Socket\n\n```bash\nDB_TYPE=mysql\nMYSQL_SOCKET_PATH=/tmp/mysql.sock\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### PostgreSQL Multi-DB with Permissions\n\n```bash\nDB_TYPE=postgresql\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=postgres\nDB_PASS=password\nDB_NAME=                                      # Multi-DB mode\nSCHEMA_INSERT_PERMISSIONS=app_db:true         # app_db can insert\nSCHEMA_UPDATE_PERMISSIONS=app_db:true         # app_db can update\nSCHEMA_DELETE_PERMISSIONS=app_db:false        # app_db: DELETE blocked\n```\n\n#### SQLite Read-Only\n\n```bash\nDB_TYPE=sqlite\nSQLITE_DB=/var/lib/data/production.db\nDB_READ_ONLY_MODE=true\n```\n\n#### AWS RDS MySQL with SSL\n\n```bash\nDB_TYPE=mysql\nDB_HOST=prod.abc123.us-east-1.rds.amazonaws.com\nDB_PORT=3306\nDB_USER=admin\nDB_PASS=secure_password\nDB_NAME=production\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\nALLOW_INSERT_OPERATION=false\nALLOW_UPDATE_OPERATION=false\nALLOW_DELETE_OPERATION=false\nALLOW_DDL_OPERATION=false\n```\n\n### Development\n\n```bash\npnpm dev              # Run in dev mode (tsx)\npnpm build            # Compile TypeScript\npnpm watch            # Watch mode\npnpm exec             # Build + run with .env\n```\n\n### Testing\n\n```bash\npnpm test              # Run all tests (setup + vitest run)\npnpm test:watch        # Watch mode\npnpm test:unit         # Unit tests only\npnpm test:integration  # Integration tests (MySQL, socket, permissions)\npnpm test:e2e          # End-to-end tests\npnpm test:coverage     # Coverage report\n```\n\n**Test Structure:**\n```\ntests/\n├── unit/           # Isolated functions (query parsing, utils)\n├── integration/    # Real database operations\n└── e2e/           # Complete MCP server workflows\n```\n\n### Performance Tuning\n\n#### Connection Pool\n\n```bash\nDB_CONNECTION_LIMIT=20  # Default: 10\n```\n\n#### Disable Read-Only Transactions (MySQL)\n\n⚠️ **Not recommended** - reduces security:\n\n```bash\nMYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true\n```\n\n### Environment Variables Reference\n\n#### Core Database Settings\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|---------|\n| `DB_TYPE` | Database type | `mysql` | `mysql`, `postgresql`, `sqlite` |\n| `DB_HOST` | Database host | `127.0.0.1` | `localhost`, `db.example.com` |\n| `DB_PORT` | Database port | `3306` | `3306` (MySQL), `5432` (PostgreSQL) |\n| `DB_USER` | Database user | `root` | `admin`, `postgres` |\n| `DB_PASS` | Database password | `\"\"` | `secure_password` |\n| `DB_NAME` | Database name | `undefined` | `mydb`, `\"\"` (multi-DB) |\n| `DB_CONNECTION_LIMIT` | Pool size | `10` | `20` |\n\n#### Security Settings\n\n| Variable | Description | Default | Values |\n|----------|-------------|---------|--------|\n| `DB_READ_ONLY_MODE` | Global read-only mode | `false` | `true`, `false` |\n| `ALLOW_INSERT_OPERATION` | Global INSERT permission | `false` | `true`, `false` |\n| `ALLOW_UPDATE_OPERATION` | Global UPDATE permission | `false` | `true`, `false` |\n| `ALLOW_DELETE_OPERATION` | Global DELETE permission | `false` | `true`, `false` |\n| `ALLOW_DDL_OPERATION` | Global DDL permission | `false` | `true`, `false` |\n| `MULTI_DB_WRITE_MODE` | Allow writes in multi-DB | `false` | `true`, `false` |\n\n#### Schema Permissions\n\n| Variable | Format | Example |\n|----------|--------|---------|\n| `SCHEMA_INSERT_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n| `SCHEMA_UPDATE_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n| `SCHEMA_DELETE_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:false,prod_db:false` |\n| `SCHEMA_DDL_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n\n#### SSL/TLS Settings\n\n| Variable | Description | Required | Example |\n|----------|-------------|----------|---------|\n| `DB_SSL` | Enable SSL/TLS | Cloud DBs | `true`, `false` |\n| `DB_SSL_REJECT_UNAUTHORIZED` | Strict SSL validation | Production | `true`, `false` |\n| `DB_SSL_CA` | CA certificate path | Cloud SQL | `/path/to/ca.pem` |\n| `DB_SSL_CERT` | Client certificate | Cloud SQL | `/path/to/cert.pem` |\n| `DB_SSL_KEY` | Client key | Cloud SQL | `/path/to/key.pem` |\n\n#### Remote MCP Settings\n\n| Variable | Description | Required | Example |\n|----------|-------------|----------|---------|\n| `IS_REMOTE_MCP` | Enable HTTP mode | No | `true`, `false` |\n| `REMOTE_SECRET_KEY` | Auth token | If remote | `your-secret-key` |\n| `PORT` | HTTP server port | No | `3000` |\n\n### Troubleshooting\n\n#### Connection Errors\n\n**MySQL socket not found:**\n```bash\n# Check socket path\nsudo mysql -u root -p -e \"SELECT @@socket;\"\n\n# Set in .env\nMYSQL_SOCKET_PATH=/var/run/mysqld/mysqld.sock\n```\n\n**PostgreSQL connection refused:**\n```bash\n# Check if PostgreSQL is running\nsudo systemctl status postgresql\n\n# Check port\nsudo netstat -tulpn | grep 5432\n```\n\n#### Permission Errors\n\n**\"Operation not allowed in read-only mode\":**\n```bash\n# Check global read-only mode\nDB_READ_ONLY_MODE=false\n\n# Check multi-DB mode\nMULTI_DB_WRITE_MODE=true  # If needed\n\n# Or use schema permissions\nSCHEMA_INSERT_PERMISSIONS=mydb:true\n```\n\n**\"INSERT not allowed for schema 'mydb'\":**\n```bash\n# Check global permission\nALLOW_INSERT_OPERATION=true\n\n# Or add schema exception\nSCHEMA_INSERT_PERMISSIONS=mydb:true\n```\n\n### License\n\nMIT\n\n### Credits\n\n- **mcp-server-mysql**: [@benborla](https://github.com/benborla/mcp-server-mysql)\n\n---\n\n## Português\n\n[![Version](https://img.shields.io/npm/v/mcp-db-bridge)](https://www.npmjs.com/package/mcp-db-bridge)\n\n\nServidor MCP (Model Context Protocol) para MySQL, PostgreSQL e SQLite com permissões granulares, suporte multi-DB e SSL/TLS pronto para nuvem. Construído com adapter pattern para extensibilidade.\n\n### Funcionalidades\n\n- 🔌 **Multi-Database**: MySQL, PostgreSQL, SQLite\n- 🏗️ **Adapter Pattern**: Arquitetura limpa e extensível\n- ☁️ **Cloud-Ready**: SSL/TLS para AWS RDS, Google Cloud SQL, Azure Database\n- 🔒 **Security First**: Modo read-only + permissões granulares por schema\n- 🌐 **Multi-DB Mode**: Acesso simultâneo a múltiplos schemas/databases\n- 🔄 **Transações**: BEGIN/COMMIT/ROLLBACK automático\n- 🚀 **Modo HTTP**: Servidor HTTP remoto opcional (Express)\n\n### Instalação\n\n```bash\nnpm install mcp-db-bridge\n# ou\npnpm add mcp-db-bridge\n```\n\n### Início Rápido\n\n#### MySQL (Local)\n\n```bash\n# .env\nDB_TYPE=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### PostgreSQL (Local)\n\n```bash\n# .env\nDB_TYPE=postgresql\nDB_HOST=127.0.0.1\nDB_PORT=5432\nDB_USER=postgres\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### SQLite (In-Memory)\n\n```bash\n# .env\nDB_TYPE=sqlite\nSQLITE_DB=:memory:\n```\n\n#### Executar\n\n```bash\npnpm build\npnpm start\n# ou\nnode dist/index.js\n```\n\n### Configuração\n\n#### Tipos de Banco de Dados\n\n```bash\nDB_TYPE=mysql          # MySQL\nDB_TYPE=postgresql     # PostgreSQL\nDB_TYPE=sqlite         # SQLite\n```\n\n#### Configurações de Conexão\n\n**Genéricas (Todos os Bancos)**\n\n```bash\nDB_HOST=127.0.0.1\nDB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb           # Deixe vazio para modo multi-DB\nDB_CONNECTION_LIMIT=10\n```\n\n**Específicas do MySQL (Compatibilidade)**\n\n```bash\nMYSQL_HOST=127.0.0.1\nMYSQL_PORT=3306\nMYSQL_USER=root\nMYSQL_PASS=password\nMYSQL_DB=mydb\nMYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unix socket (prioridade sobre host/port)\n```\n\n**Específicas do PostgreSQL**\n\n```bash\nPOSTGRESQL_HOST=127.0.0.1\nPOSTGRESQL_PORT=5432\nPOSTGRESQL_DB=mydb\n```\n\n**Específicas do SQLite**\n\n```bash\nSQLITE_DB=:memory:              # Database em memória\nSQLITE_DB=/var/lib/app/data.db  # Database em arquivo\n```\n\n### Segurança & Permissões\n\n#### Modo Read-Only\n\nBloqueia **todas** as operações de escrita em nível de aplicação:\n\n```bash\nDB_READ_ONLY_MODE=true\n```\n\n#### Permissões Globais de Escrita\n\nControle fino de operações por tipo (aplicado globalmente):\n\n```bash\nALLOW_INSERT_OPERATION=true   # Permite INSERT\nALLOW_UPDATE_OPERATION=true   # Permite UPDATE\nALLOW_DELETE_OPERATION=false  # Bloqueia DELETE\nALLOW_DDL_OPERATION=false     # Bloqueia CREATE/ALTER/DROP/TRUNCATE\n```\n\n#### Permissões Específicas por Schema\n\nSobrescreve permissões globais para schemas específicos:\n\n```bash\n# Formato: \"schema1:true,schema2:false,schema3:true\"\nSCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true\nSCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true\nSCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false\nSCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false\n```\n\n**Como funciona:**\n- Se schema tem permissão específica → usa ela\n- Caso contrário → usa flag global\n\n**Exemplo:**\n```bash\n# Global: INSERT bloqueado\nALLOW_INSERT_OPERATION=false\n\n# test_db pode inserir, prod_db não pode\nSCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false\n\n# Resultado:\n# - INSERT em test_db: ✅ permitido (permissão do schema)\n# - INSERT em prod_db: ❌ bloqueado (permissão do schema)\n# - INSERT em other_db: ❌ bloqueado (permissão global)\n```\n\n### Modo Multi-DB\n\nAcessa múltiplos databases/schemas através de uma única conexão.\n\n#### Ativação\n\nDeixe `DB_NAME` vazio (MySQL/PostgreSQL apenas):\n\n```bash\nDB_TYPE=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_USER=root\nDB_PASS=password\nDB_NAME=                # Vazio = modo multi-DB\n```\n\n#### Proteção de Escrita\n\nPor padrão, modo multi-DB é **read-only** por segurança. Para permitir escritas:\n\n```bash\nMULTI_DB_WRITE_MODE=true  # ⚠️ Use com cautela!\n```\n\n**Recomendação:** Use `SCHEMA_*_PERMISSIONS` para controle granular ao invés de `MULTI_DB_WRITE_MODE=true`.\n\n#### Exemplo Completo\n\n```bash\n# Multi-DB com permissões granulares\nDB_TYPE=mysql\nDB_NAME=                                    # Modo multi-DB\nALLOW_INSERT_OPERATION=false                # Global: bloqueado\nSCHEMA_INSERT_PERMISSIONS=test_db:true      # Exceção: test_db pode inserir\nSCHEMA_UPDATE_PERMISSIONS=test_db:true      # Exceção: test_db pode atualizar\nSCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db: DELETE bloqueado\nSCHEMA_DDL_PERMISSIONS=test_db:true         # test_db: DDL permitido\n```\n\n### SSL/TLS para Bancos na Nuvem\n\n#### AWS RDS (MySQL/PostgreSQL)\n\n```bash\nDB_TYPE=mysql\nDB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com\nDB_PORT=3306\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\n# Opcional: DB_SSL_CA=/path/to/aws-rds-ca-cert.pem\n```\n\n#### Google Cloud SQL (PostgreSQL)\n\n```bash\nDB_TYPE=postgresql\nDB_HOST=34.123.45.67\nDB_PORT=5432\nDB_SSL=true\nDB_SSL_CA=/path/to/server-ca.pem\nDB_SSL_CERT=/path/to/client-cert.pem\nDB_SSL_KEY=/path/to/client-key.pem\n```\n\n#### Azure Database for MySQL\n\n```bash\nDB_TYPE=mysql\nDB_HOST=myserver.mysql.database.azure.com\nDB_PORT=3306\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\n```\n\n### MCP Remoto (Servidor HTTP)\n\nExecute o servidor MCP via HTTP com autenticação:\n\n```bash\n# .env\nIS_REMOTE_MCP=true\nREMOTE_SECRET_KEY=your-secret-key-here\nPORT=3000\n```\n\nEndpoint: `POST http://localhost:3000/mcp`\n\nHeader: `Authorization: Bearer your-secret-key-here`\n\n### Arquitetura\n\n```\nsrc/\n├── db/\n│   ├── adapters/\n│   │   ├── types.ts              # Interfaces e tipos\n│   │   ├── factory.ts            # Factory pattern\n│   │   ├── mysql.adapter.ts      # MySQL via mysql2\n│   │   ├── postgresql.adapter.ts # PostgreSQL via pg\n│   │   └── sqlite.adapter.ts     # SQLite via better-sqlite3\n│   ├── index.ts                  # Core query handlers\n│   ├── utils.ts                  # SQL parsing (node-sql-parser)\n│   └── permissions.ts            # Schema permission checks\n├── config/\n│   └── index.ts                  # Configuração de ambiente\n├── utils/\n│   └── index.ts                  # Logging & utilitários\n└── types/\n    └── index.ts                  # Definições de tipos\n```\n\n#### Adapter Pattern\n\nCada adapter implementa a interface `DatabaseAdapter`:\n\n```typescript\nexport interface DatabaseAdapter {\n  readonly type: DatabaseType;\n  createPool(config: ConnectionConfig): Promise<DatabasePool>;\n  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;\n  setReadOnly(connection: DatabaseConnection): Promise<void>;\n  unsetReadOnly(connection: DatabaseConnection): Promise<void>;\n  normalizeResult(result: any): NormalizedResult;\n  supportsReadOnlyMode(): boolean;\n}\n```\n\n#### Fluxos de Transação\n\n**Operações de Leitura:**\n```\nBEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE\n```\n\n**Operações de Escrita:**\n```\nBEGIN → QUERY → COMMIT (ou ROLLBACK em caso de erro)\n```\n\n### Exemplos\n\n#### MySQL com Unix Socket\n\n```bash\nDB_TYPE=mysql\nMYSQL_SOCKET_PATH=/tmp/mysql.sock\nDB_USER=root\nDB_PASS=password\nDB_NAME=mydb\n```\n\n#### PostgreSQL Multi-DB com Permissões\n\n```bash\nDB_TYPE=postgresql\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=postgres\nDB_PASS=password\nDB_NAME=                                      # Modo multi-DB\nSCHEMA_INSERT_PERMISSIONS=app_db:true         # app_db pode inserir\nSCHEMA_UPDATE_PERMISSIONS=app_db:true         # app_db pode atualizar\nSCHEMA_DELETE_PERMISSIONS=app_db:false        # app_db: DELETE bloqueado\n```\n\n#### SQLite Read-Only\n\n```bash\nDB_TYPE=sqlite\nSQLITE_DB=/var/lib/data/production.db\nDB_READ_ONLY_MODE=true\n```\n\n#### AWS RDS MySQL com SSL\n\n```bash\nDB_TYPE=mysql\nDB_HOST=prod.abc123.us-east-1.rds.amazonaws.com\nDB_PORT=3306\nDB_USER=admin\nDB_PASS=secure_password\nDB_NAME=production\nDB_SSL=true\nDB_SSL_REJECT_UNAUTHORIZED=true\nALLOW_INSERT_OPERATION=false\nALLOW_UPDATE_OPERATION=false\nALLOW_DELETE_OPERATION=false\nALLOW_DDL_OPERATION=false\n```\n\n### Desenvolvimento\n\n```bash\npnpm dev              # Executar em modo dev (tsx)\npnpm build            # Compilar TypeScript\npnpm watch            # Modo watch\npnpm exec             # Build + executar com .env\n```\n\n### Testes\n\n```bash\npnpm test              # Executar todos os testes (setup + vitest run)\npnpm test:watch        # Modo watch\npnpm test:unit         # Apenas testes unitários\npnpm test:integration  # Testes de integração (MySQL, socket, permissões)\npnpm test:e2e          # Testes end-to-end\npnpm test:coverage     # Relatório de cobertura\n```\n\n**Estrutura de Testes:**\n```\ntests/\n├── unit/           # Funções isoladas (parsing de queries, utils)\n├── integration/    # Operações reais de banco de dados\n└── e2e/           # Fluxos completos do servidor MCP\n```\n\n### Ajustes de Performance\n\n#### Connection Pool\n\n```bash\nDB_CONNECTION_LIMIT=20  # Padrão: 10\n```\n\n#### Desabilitar Transações Read-Only (MySQL)\n\n⚠️ **Não recomendado** - reduz segurança:\n\n```bash\nMYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true\n```\n\n### Referência de Variáveis de Ambiente\n\n#### Configurações Principais do Banco\n\n| Variável | Descrição | Padrão | Exemplo |\n|----------|-----------|--------|---------|\n| `DB_TYPE` | Tipo de banco | `mysql` | `mysql`, `postgresql`, `sqlite` |\n| `DB_HOST` | Host do banco | `127.0.0.1` | `localhost`, `db.example.com` |\n| `DB_PORT` | Porta do banco | `3306` | `3306` (MySQL), `5432` (PostgreSQL) |\n| `DB_USER` | Usuário do banco | `root` | `admin`, `postgres` |\n| `DB_PASS` | Senha do banco | `\"\"` | `secure_password` |\n| `DB_NAME` | Nome do banco | `undefined` | `mydb`, `\"\"` (multi-DB) |\n| `DB_CONNECTION_LIMIT` | Tamanho do pool | `10` | `20` |\n\n#### Configurações de Segurança\n\n| Variável | Descrição | Padrão | Valores |\n|----------|-----------|--------|---------|\n| `DB_READ_ONLY_MODE` | Modo global read-only | `false` | `true`, `false` |\n| `ALLOW_INSERT_OPERATION` | Permissão global de INSERT | `false` | `true`, `false` |\n| `ALLOW_UPDATE_OPERATION` | Permissão global de UPDATE | `false` | `true`, `false` |\n| `ALLOW_DELETE_OPERATION` | Permissão global de DELETE | `false` | `true`, `false` |\n| `ALLOW_DDL_OPERATION` | Permissão global de DDL | `false` | `true`, `false` |\n| `MULTI_DB_WRITE_MODE` | Permitir escritas em multi-DB | `false` | `true`, `false` |\n\n#### Permissões por Schema\n\n| Variável | Formato | Exemplo |\n|----------|---------|---------|\n| `SCHEMA_INSERT_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n| `SCHEMA_UPDATE_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n| `SCHEMA_DELETE_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:false,prod_db:false` |\n| `SCHEMA_DDL_PERMISSIONS` | `schema:bool,schema:bool` | `test_db:true,prod_db:false` |\n\n#### Configurações SSL/TLS\n\n| Variável | Descrição | Necessária | Exemplo |\n|----------|-----------|------------|---------|\n| `DB_SSL` | Habilitar SSL/TLS | Bancos Cloud | `true`, `false` |\n| `DB_SSL_REJECT_UNAUTHORIZED` | Validação SSL estrita | Produção | `true`, `false` |\n| `DB_SSL_CA` | Caminho do certificado CA | Cloud SQL | `/path/to/ca.pem` |\n| `DB_SSL_CERT` | Certificado do cliente | Cloud SQL | `/path/to/cert.pem` |\n| `DB_SSL_KEY` | Chave do cliente | Cloud SQL | `/path/to/key.pem` |\n\n#### Configurações MCP Remoto\n\n| Variável | Descrição | Necessária | Exemplo |\n|----------|-----------|------------|---------|\n| `IS_REMOTE_MCP` | Habilitar modo HTTP | Não | `true`, `false` |\n| `REMOTE_SECRET_KEY` | Token de autenticação | Se remoto | `your-secret-key` |\n| `PORT` | Porta do servidor HTTP | Não | `3000` |\n\n### Solução de Problemas\n\n#### Erros de Conexão\n\n**Socket MySQL não encontrado:**\n```bash\n# Verificar caminho do socket\nsudo mysql -u root -p -e \"SELECT @@socket;\"\n\n# Configurar no .env\nMYSQL_SOCKET_PATH=/var/run/mysqld/mysqld.sock\n```\n\n**Conexão PostgreSQL recusada:**\n```bash\n# Verificar se PostgreSQL está rodando\nsudo systemctl status postgresql\n\n# Verificar porta\nsudo netstat -tulpn | grep 5432\n```\n\n#### Erros de Permissão\n\n**\"Operation not allowed in read-only mode\":**\n```bash\n# Verificar modo global read-only\nDB_READ_ONLY_MODE=false\n\n# Verificar modo multi-DB\nMULTI_DB_WRITE_MODE=true  # Se necessário\n\n# Ou usar permissões de schema\nSCHEMA_INSERT_PERMISSIONS=mydb:true\n```\n\n**\"INSERT not allowed for schema 'mydb'\":**\n```bash\n# Verificar permissão global\nALLOW_INSERT_OPERATION=true\n\n# Ou adicionar exceção de schema\nSCHEMA_INSERT_PERMISSIONS=mydb:true\n```\n\n### Licença\n\nMIT\n\n### Créditos\n\n- **mcp-server-mysql**: [@benborla](https://github.com/benborla/mcp-server-mysql)\n","readmeFilename":"README.md","_rev":"1-d9f15771c534b29c52016e387fe4f81d"}