convez.ai
MCP Server
steveramos21

ai-dba

steveramos21/ai-dba

Ver no GitHub
InicialPluginScore · de 0 a 100

AI-DBA: Universal database copilot — diagnostics MCP server and CLI

Instalação

$npx convez-ai steveramos21/ai-dba

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
—
Issues abertas
2
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

AI-DBA

Universal database copilot — diagnostics, operations, and performance analysis via MCP and CLI.

Features

  • MCP Server — expose database diagnostics as tools for AI agents (Hermes, Claude Code, etc.)
  • CLI — one-off commands for scripting and automation
  • Interactive REPL — explore your databases interactively with standard DBA commands
  • Connection URLs — connect via mysql:// or postgresql:// URLs (no config file needed)
  • Database-agnostic commands — databases, tables, describe, indexes, processes work across engines
  • Multi-engine support — MySQL and PostgreSQL connectors, more engines coming
  • MySQL blocking chains — detect and report row-level blocking with full query details

Quick Start

1. Install dependencies

npm install

2. Build

npm run build

3. Connect and explore

Option A — Config file (for multiple engines):

cp config.yaml.example config.yaml
# Edit config.yaml with your database credentials
npm run repl

Option B — Connection URL (no config file needed):

node dist/index.js repl
# Then: connect mysql://root:password@127.0.0.1:3306/mydb

Option C — Connect via URL (drops into REPL):

# MySQL
npm run connect -- 'mysql://root:***@127.0.0.1:3306/mydb'

# PostgreSQL
npm run connect -- 'postgresql://postgres:***@127.0.0.1:5432/mydb'
# Connects and opens interactive REPL

Commands

CommandDescription
serveStart MCP server over stdio (for AI agents)
list-enginesList configured database engines
blocking-chains <engineId>Show current blocking chains
connect <url>Connect to a database via URL
replInteractive REPL for database diagnostics

Global Options

OptionDescriptionDefault
-c, --config <path>Path to config.yamlconfig.yaml
-V, --versionShow version—
-h, --helpShow help—

connect <url>

Connect to a database via URL and open an interactive REPL. No config file needed. Supports mysql://, postgresql://, and postgres:// URL schemes.

# MySQL
npm run connect -- 'mysql://root:***@127.0.0.1:3306/mydb'

# PostgreSQL
npm run connect -- 'postgresql://postgres:***@127.0.0.1:5432/mydb'

# With --type override
npm run connect -- 'postgresql://user:***@host:5432/db' --type postgres

This connects, verifies the connection, then drops you into the REPL where you can run databases, tables, describe, indexes, processes, etc.

blocking-chains

ai-dba blocking-chains <engineId>       # Table output
ai-dba blocking-chains <engineId> --json # JSON output

Detects row-level blocking chains using MySQL performance_schema.data_lock_waits. Returns:

FieldDescription
blocking_pidProcess ID holding the lock
blocked_pidProcess ID waiting for the lock
wait_duration_msHow long the blocked session has been waiting
wait_eventType of wait event
blocking_querySQL statement holding the lock
blocked_querySQL statement waiting for the lock
database_nameDatabase context
wait_typeLock type (e.g. "Sleep holding lock")
statusThread status
host_nameClient hostname
program_nameClient program name

Error cases:

  • Unknown engine ID → Unknown engine "x". Available: mysql-primary
  • Unsupported engine type → Engine "x" is type "postgres". Only MySQL blocking chains are currently supported.
  • performance_schema disabled → error message telling user to enable it

repl

ai-dba repl                # Uses config.yaml
ai-dba repl                # No config — start empty, use connect

Interactive commands:

CommandAliasDescription
helpShow available commands
connect <url>Connect to a database via URL
databasesdbList databases on the server
tablesdtList tables (with rows, size, engine)
describe <table>descShow column details (type, nullable, key, default)
indexes <table>idxList indexes on a table
processespsShow active connections/processes
engineslsList configured engines (current marked with *)
use <engineId>Switch to a different engine
statussShow connection details for current engine
blocking-chainsbcShow blocking chains on current engine
sql <statement>Run a raw SQL query (escape hatch)
quitq, exitExit the REPL

SQL keywords are auto-detected — just type SHOW DATABASES or SELECT * FROM users directly.

Example session:

AI-DBA REPL — type 'help' for commands
No engines configured. Use: connect <url>

ai-dba[no-engine]> connect mysql://root:password@127.0.0.1:13306/testdb
Connected to 127.0.0.1-testdb
  mysql://root:***@127.0.0.1:13306/testdb

ai-dba[127.0.0.1-testdb]> databases
┌────────────────────┐
│ Database           │
├────────────────────┤
│ information_schema │
│ testdb             │
└────────────────────┘
2 database(s)

ai-dba[127.0.0.1-testdb]> tables
┌────────────────┬──────┬─────────┬─────────┬─────────────────────┐
│ Table          │ Rows  │ Size    │ Engine  │ Collation           │
├────────────────┼──────┼─────────┼─────────┼─────────────────────┤
│ blocking_test  │ 3     │ 16.0 KB │ InnoDB  │ utf8mb4_0900_ai_ci  │
└────────────────┴──────┴─────────┴─────────┴─────────────────────┘
1 table(s)

ai-dba[127.0.0.1-testdb]> describe blocking_test
┌─────────┬──────────────┬──────┬─────┬─────────┬────────────────┐
│ Column  │ Type         │ Null │ Key │ Default  │ Extra          │
├─────────┼──────────────┼──────┼─────┼─────────┼────────────────┤
│ id      │ int          │ NO   │ PRI │ NULL     │ auto_increment │
│ name    │ varchar(100) │ YES  │     │ NULL     │                │
│ value   │ int          │ YES  │     │ NULL     │                │
└─────────┴──────────────┴──────┴─────┴─────────┴────────────────┘

ai-dba[127.0.0.1-testdb]> processes
┌──────┬──────┬──────────────────────┬─────────┬─────────┬──────┬─────────────┐
│ PID  │ User │ Host                 │ DB      │ Command │ Time │ State       │
├──────┼──────┼──────────────────────┼─────────┼─────────┼──────┼─────────────┤
│ 5    │ root │ 172.23.0.1:54312     │ testdb  │ Query   │ 0s   │ starting    │
└──────┴──────┴──────────────────────┴─────────┴─────────┴──────┴─────────────┘
1 process(es)

serve

Starts an MCP server over stdio. Used by AI agents to call database diagnostics tools.

MCP configuration (e.g., ~/.hermes/config.yaml):

{
  "mcpServers": {
    "ai-dba-diagnostics": {
      "command": "node",
      "args": ["/path/to/ai-dba/dist/index.js", "serve", "--config", "/path/to/ai-dba/config.yaml"]
    }
  }
}

The server exposes one tool:

  • blocking-chains — parameters: engineId (string, required)

Docker Test Environment

A Docker Compose file is included for local testing with MySQL 8.0 and PostgreSQL 16.

Start databases

docker compose up -d

Wait until healthy:

docker inspect --format='{{.State.Health.Status}}' ai-dba-mysql-test
docker inspect --format='{{.State.Health.Status}}' ai-dba-postgres-test
# Repeat until both show "healthy"

Seed MySQL test data

docker exec ai-dba-mysql-test mysql -uroot -ptestpassword testdb \
  -e "CREATE TABLE IF NOT EXISTS blocking_test (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100), value INT); INSERT IGNORE INTO blocking_test (name, value) VALUES ('alpha', 1), ('beta', 2), ('gamma', 3);"

Create a test config

cp config.yaml.example config.yaml

The example config points to both Docker MySQL on port 13306 and PostgreSQL on port 15432.

Test blocking detection

An automated test script creates a real blocking scenario and verifies detection:

node test/test-blocking.mjs

Stop databases

docker compose down

Add -v to also delete the data volume.

Configuration

config.yaml format:

Connection URL (recommended)

engines:
  mysql-prod:
    type: mysql
    url: mysql://readonly:***@prod-db.internal:3306/app_db?ssl=true

  postgres-prod:
    type: postgres
    url: postgresql://readonly:***@prod-db.internal:5432/app_db?sslmode=require

The url field takes priority over individual fields. MySQL supports additional URL params:

  • ssl=true — enable SSL with certificate verification
  • ssl={"rejectUnauthorized":false} — custom SSL options (JSON)
  • connectionLimit=10 — pool size (default: 5)

PostgreSQL URLs are passed directly to pg.Pool({ connectionString }), so any pg-supported parameter works (sslmode, connect_timeout, etc.).

Individual fields (legacy)

engines:
  <engine-id>:
    type: mysql          # or postgres, sqlserver, oracle, mongodb
    host: 127.0.0.1      # Hostname or IP (MySQL only)
    port: 3306            # Port (MySQL only)
    user: root            # Database user (MySQL only)
    password: secret      # Password (MySQL only)
    database: mydb        # Default database (MySQL only)

Note: Individual fields are only supported for MySQL. PostgreSQL requires a connection URL (url field).

Multiple engines are supported:

engines:
  mysql-prod:
    type: mysql
    url: mysql://readonly:***@prod-db.internal:3306/app_db?ssl=true
  mysql-staging:
    type: mysql
    host: staging-db.internal
    port: 3306
    user: readonly
    password: ${MYSQL_STAGING_PASSWORD}
    database: app_db
  postgres-analytics:
    type: postgres
    url: postgresql:***@analytics-db.internal:5432/warehouse?sslmode=require

Security: Add config.yaml to .gitignore (already included by default).

Architecture

src/
  index.ts              CLI entry point (commander, REPL)
  server.ts             MCP server setup
  config.ts             YAML config loader with URL parsing
  connector.ts          DatabaseConnector interface (engine-agnostic)
  types.ts              Shared TypeScript types
  connectors/
    mysql.ts            MySQLConnector (implements DatabaseConnector)
    postgres.ts          PostgreSQLConnector (implements DatabaseConnector)
  tools/
    blocking-chains.ts  MCP tool definition + handler
  • DatabaseConnector interface — standard commands (databases, tables, describe, indexes, processes, query) that work across engines. MySQL and PostgreSQL are implemented; SQL Server, Oracle, and MongoDB are planned.
  • Lazy imports — MCP SDK, mysql2, and pg are loaded dynamically only when needed. CLI commands like list-engines start instantly without loading database drivers.
  • Lazy connection pools — Database connections are created on first use, not at startup.
  • One tool per file — src/tools/blocking-chains.ts is self-contained (schema + handler). Adding a new tool means adding a new file and registering it in server.ts.

Requirements

  • Node.js 18+
  • MySQL 8.0+ (with performance_schema enabled, which is the default)
  • PostgreSQL 12+ (for PostgreSQL connector)

License

MIT

Ver o original no GitHub

Bom para

Relacionados