Your friendly MySQL database agent powered by AI

Dolph is a single-file MySQL database agent using OpenAI Agents SDK and Bun.js. Talk to your database like you talk to a friend.

# 1. Install dependencies
bun install

# 2. Setup test database (requires Docker)
bun setup-db.ts

# 3. Test Dolph
bun test-agent.ts

# 4. Let Dolph do the work
bun dolph.ts --task list-tables

• Single-file design - All agent code in one file (dolph.ts)
• Dual-mode - CLI for terminal, exports for server integration
• Native MySQL - Uses Bun's built-in SQL driver (9x faster than mysql2)
• Type-safe - Full TypeScript with Zod validation
• Secure - Read-only by default, dual-gate write protection

# Test database connection
bun dolph.ts --task test-connection

# List all tables
bun dolph.ts --task list-tables

# List tables with exact row counts
bun dolph.ts --task list-tables --include-counts

# Get schema for a specific table
bun dolph.ts --task get-schema --table users

# Get all schemas
bun dolph.ts --task get-all-schemas

# Run SQL query
bun dolph.ts --task query --sql "SELECT * FROM users WHERE status = 'active'"

# Run with JSON output
bun dolph.ts --task list-tables --json

# Single question
bun dolph.ts --chat "What tables are in this database?"

# Interactive mode - just chat with Dolph
bun dolph.ts --interactive

Dolph is designed as a single-file module you can import directly into any Bun application.

import { runMySQLAgent, configureAgent, closeConnection } from "./dolph.ts";

// Configure once at app startup
await configureAgent({
  mysqlUrl: process.env.MYSQL_URL,
  openaiApiKey: process.env.OPENAI_API_KEY,
});

// Query with natural language
const result = await runMySQLAgent("Show me all active users");
console.log(result.data);

// Cleanup on shutdown
await closeConnection();

import { executeMySQLTask, MySQLAgentTasks } from "./dolph.ts";

// List all tables
const tables = await executeMySQLTask({
  task: MySQLAgentTasks.LIST_TABLES,
  params: { includeRowCounts: true },
});

// Get table schema
const schema = await executeMySQLTask({
  task: MySQLAgentTasks.GET_SCHEMA,
  params: { tableName: "users" },
});

// Run SQL query
const data = await executeMySQLTask({
  task: MySQLAgentTasks.QUERY,
  params: { sql: "SELECT * FROM users WHERE status = 'active'" },
});

import { runMySQLAgent } from "./dolph.ts";

const result = await runMySQLAgent("What tables contain user data?");

if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
}

import { executeQuery } from "./dolph.ts";

const result = await executeQuery("SELECT COUNT(*) FROM orders", {
  allowWrite: false,
});

*Either MYSQL_URL or individual MYSQL_* variables required.

The setup-db.ts script handles Docker MySQL container setup:

# Create container + seed data
bun setup-db.ts

# Check status
bun setup-db.ts --status

# Re-seed existing container
bun setup-db.ts --seed

# Remove container
bun setup-db.ts --teardown

The setup script creates these tables:

• users - 10 sample users with various statuses
• products - 13 products across categories
• orders - 8 orders with different statuses
• order_items - Order line items with product references

1. Read-only by default - Write operations blocked unless explicitly enabled
2. Dual-gate writes - Requires both --allow-write flag AND MYSQL_ALLOW_WRITE=true
3. Auto row limits - SELECT queries limited to prevent memory issues
4. No credential logging - Connection strings never appear in output

dolph/
├── dolph.ts         # Main agent (single file)
├── setup-db.ts      # Docker/seed script
├── test-agent.ts    # Test suite
├── package.json     # Dependencies
├── .env.sample      # Environment template
└── README.md        # This file

MySQL's logo is a dolphin. Dolph is your friendly dolphin that dives into your database and brings back exactly what you need. 🐬

MIT