Skip to main content
Glama
steveramos21

AI-DBA

by steveramos21
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

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

  • MySQL blocking chains — detect and report row-level blocking with full query details

Related MCP server: Database MCP Server

Quick Start

1. Install dependencies

npm install

2. Build

npm run build

3. Configure

Copy the example config and edit with your database credentials:

cp config.yaml.example config.yaml
engines:
  # Connection URL (recommended — works with cloud providers)
  mysql-prod:
    type: mysql
    url: mysql://readonly:***@prod-db.internal:3306/app_db?ssl=true

  # Individual fields (legacy, for local/dev)
  mysql-dev:
    type: mysql
    host: 127.0.0.1
    port: 3306
    user: root
    password: yourpassword
    database: yourdb

  # SSL with custom options
  mysql-aws:
    type: mysql
    url: mysql://admin:***@my-cluster.cluster-abc123.us-east-1.rds.amazonaws.com:3306/mydb?ssl={"rejectUnauthorized":false}

4. Run

# List configured engines
node dist/index.js --config config.yaml list-engines

# Check blocking chains
node dist/index.js --config config.yaml blocking-chains mysql-primary

# Interactive REPL
node dist/index.js --config config.yaml repl

# MCP server (for AI agents)
node dist/index.js --config config.yaml serve

Commands

Command

Description

serve

Start MCP server over stdio (for AI agents)

list-engines

List configured database engines

blocking-chains <engineId>

Show current blocking chains

repl

Interactive REPL for database diagnostics

Global Options

Option

Description

Default

-c, --config <path>

Path to config.yaml

config.yaml

-V, --version

Show version

—

-h, --help

Show help

—

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:

Field

Description

blocking_pid

Process ID holding the lock

blocked_pid

Process ID waiting for the lock

wait_duration_ms

How long the blocked session has been waiting

wait_event

Type of wait event

blocking_query

SQL statement holding the lock

blocked_query

SQL statement waiting for the lock

database_name

Database context

wait_type

Lock type (e.g. "Sleep holding lock")

status

Thread status

host_name

Client hostname

program_name

Client program name

Error cases:

  • Unknown engine ID → Unknown engine "x". Available: mysql-primary

  • Unsupported engine type → Engine "x" is type "postgres". Only MySQL is currently supported.

  • performance_schema disabled → error message telling user to enable it

repl

ai-dba repl

Interactive commands:

Command

Alias

Description

help

Show available commands

engines

ls

List configured engines (current marked with *)

use <engineId>

Switch to a different engine

blocking-chains

bc

Show blocking chains on current engine

quit

q, exit

Exit the REPL

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.

Start MySQL

docker compose up -d

Wait until healthy:

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

Seed 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 already points to the Docker MySQL on port 13306.

Test blocking detection

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

node test/test-blocking.mjs

Expected output: a table showing the blocking chain, then JSON output, then cleanup.

Stop MySQL

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:password@prod-db.internal:3306/app_db?ssl=true

The url field takes priority over individual fields. Supported URL params:

  • ssl=true — enable SSL with certificate verification

  • ssl={"rejectUnauthorized":false} — custom SSL options (JSON)

  • connectionLimit=10 — pool size (default: 5)

Individual fields (legacy)

engines:
  <engine-id>:
    type: mysql          # Engine type (only mysql supported currently)
    host: 127.0.0.1      # Hostname or IP
    port: 3306            # Port
    user: root            # Database user
    password: secret      # Password
    database: mydb        # Default database

Multiple engines are supported:

engines:
  mysql-prod:
    type: mysql
    url: mysql://readonly:password@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

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

Architecture

src/
  index.ts              CLI entry point (commander)
  server.ts             MCP server setup
  config.ts             YAML config loader
  types.ts              Shared TypeScript types
  connectors/
    mysql.ts            MySQL connection pool + blocking-chains query
  tools/
    blocking-chains.ts  MCP tool definition + handler

  • Lazy imports — MCP SDK and mysql2 are loaded dynamically only when needed. CLI commands like list-engines start instantly without loading database drivers.

  • Lazy connection pools — MySQL 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)

License

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/steveramos21/ai-dba'

If you have feedback or need assistance with the MCP directory API, please join our Discord server