DBHub

What is DBHub?

DBHub is a universal database gateway that implements the Model Context Protocol (MCP) server interface. It acts as a bridge, allowing MCP-compatible clients (like Claude Desktop, Claude Code, and Cursor) to connect to and interact with various databases, including PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.

How to use DBHub?

DBHub can be used in several ways:

Docker: Run DBHub as a Docker container, specifying the database connection string (DSN) and transport mode (HTTP or stdio).

docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

NPM: Install and run DBHub via npm, providing the DSN and transport mode.

npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

Demo Mode: A convenient demo mode is available with a pre-loaded SQLite sample employee database.
```
npx @bytebase/dbhub --transport http --port 8080 --demo
```
Integration with MCP Clients: Configure MCP clients like Claude Desktop, Claude Code, and Cursor to connect to DBHub using either stdio or http transport.

DBHub supports various DSN formats for different databases (MySQL, MariaDB, PostgreSQL, SQL Server, SQLite) and allows configuration via command-line arguments, environment variables, or environment files.

Key Features of DBHub

Universal Database Gateway: Connects to multiple database types (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite).
Model Context Protocol (MCP) Server: Implements the MCP interface for seamless integration with MCP-compatible clients.
Database Resource Exploration: Provides access to database schemas, tables, indexes, and procedures.
Database Tools: Offers an execute_sql tool to run single or multiple SQL statements.
Prompt Capabilities: Includes generate_sql for SQL generation and explain_db for explaining database elements.
SSL Connections: Supports various SSL modes (disable, require, default certificate verification) for secure connections.
Read-only Mode: Restricts SQL query execution to read-only operations for enhanced security.
Flexible Configuration: DSN can be configured via command line, environment variables, or .env files.
Multiple Transport Options: Supports stdio for direct integration with tools and http for browser and network clients.

Use Cases of DBHub

AI-powered Database Interaction: Enables AI models (like those in Claude Desktop and Cursor) to understand and interact with various databases.
Database Exploration and Management: Provides a unified interface for exploring database structures and executing SQL queries.
Secure Database Access: Read-only mode and SSL options enhance security when connecting to production databases.
Development and Testing: The demo mode and easy installation options make it suitable for rapid development and testing with sample data.
Integration with AI Development Tools: Seamlessly integrates with tools that leverage the Model Context Protocol for database-related tasks.

FAQ about DBHub

What databases does DBHub support? DBHub supports PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.
What is the Model Context Protocol (MCP)? MCP is a protocol that allows AI models and other clients to interact with various data sources, including databases, in a standardized way.
Can I run DBHub in a read-only mode? Yes, DBHub can be started with the --readonly flag to restrict SQL execution to read-only operations, enhancing security for production databases.
How do I connect to a database running on my host machine when using Docker? When running DBHub in Docker, use host.docker.internal instead of localhost in your DSN to connect to databases running on your host machine.
What is the demo mode? The demo mode starts DBHub with an in-memory SQLite database pre-loaded with a sample employee database, useful for testing and quick demonstrations.
How do I handle special characters in my user/password for the DSN? If your user/password contains special characters (e.g., #), you need to escape them (e.g., pass#word should be pass%23word).

[!NOTE]
Brought to you by Bytebase, open-source database DevSecOps platform.

DBHub is a universal database gateway implementing the Model Context Protocol (MCP) server interface. This gateway allows MCP-compatible clients to connect to and explore different databases.

 +------------------+    +--------------+    +------------------+
 |                  |    |              |    |                  |
 |                  |    |              |    |                  |
 |  Claude Desktop  +--->+              +--->+    PostgreSQL    |
 |                  |    |              |    |                  |
 |  Claude Code     +--->+              +--->+    SQL Server    |
 |                  |    |              |    |                  |
 |  Cursor          +--->+    DBHub     +--->+    SQLite        |
 |                  |    |              |    |                  |
 |  Other Clients   +--->+              +--->+    MySQL         |
 |                  |    |              |    |                  |
 |                  |    |              +--->+    MariaDB       |
 |                  |    |              |    |                  |
 |                  |    |              |    |                  |
 +------------------+    +--------------+    +------------------+
      MCP Clients           MCP Server             Databases

Demo HTTP Endpoint

https://demo.dbhub.ai/message connects a sample employee database. You can point Cursor or MCP Inspector to it to see it in action.

mcp-inspector

Supported Matrix

Database Resources

Resource Name	URI Format	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite
schemas	`db://schemas`	✅	✅	✅	✅	✅
tables_in_schema	`db://schemas/{schemaName}/tables`	✅	✅	✅	✅	✅
table_structure_in_schema	`db://schemas/{schemaName}/tables/{tableName}`	✅	✅	✅	✅	✅
indexes_in_table	`db://schemas/{schemaName}/tables/{tableName}/indexes`	✅	✅	✅	✅	✅
procedures_in_schema	`db://schemas/{schemaName}/procedures`	✅	✅	✅	✅	❌
procedure_details_in_schema	`db://schemas/{schemaName}/procedures/{procedureName}`	✅	✅	✅	✅	❌

Database Tools

Tool	Command Name	Description	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite
Execute SQL	`execute_sql`	Execute single or multiple SQL statements (separated by semicolons)	✅	✅	✅	✅	✅

Prompt Capabilities

Prompt	Command Name	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite
Generate SQL	`generate_sql`	✅	✅	✅	✅	✅
Explain DB Elements	`explain_db`	✅	✅	✅	✅	✅

Installation

Docker

# PostgreSQL example
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

# Demo mode with sqlite sample employee database
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --demo

NPM

# PostgreSQL example
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

# Demo mode with sqlite sample employee database
npx @bytebase/dbhub --transport http --port 8080 --demo

# Demo mode with sample employee database
npx @bytebase/dbhub --transport http --port 8080 --demo

Note: The demo mode includes a bundled SQLite sample "employee" database with tables for employees, departments, salaries, and more.

Claude Desktop

claude-desktop

Claude Desktop only supports stdio transport https://github.com/orgs/modelcontextprotocol/discussions/16

// claude_desktop_config.json
{
  "mcpServers": {
    "dbhub-postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        // Use host.docker.internal as the host if connecting to the local db
        "postgres://user:password@host.docker.internal:5432/dbname?sslmode=disable"
      ]
    },
    "dbhub-postgres-npx": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
      ]
    },
    "dbhub-demo": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio", "--demo"]
    }
  }
}

Claude Code

Check https://docs.anthropic.com/en/docs/claude-code/mcp

Cursor

cursor

Cursor supports both stdio and http.
Follow Cursor MCP guide and make sure to use Agent mode.

Usage

SSL Connections

You can specify the SSL mode using the sslmode parameter in your DSN string:

Database	`sslmode=disable`	`sslmode=require`	Default SSL Behavior
PostgreSQL	✅	✅	Certificate verification
MySQL	✅	✅	Certificate verification
MariaDB	✅	✅	Certificate verification
SQL Server	✅	✅	Certificate verification
SQLite	❌	❌	N/A (file-based)

SSL Mode Options:

sslmode=disable: All SSL/TLS encryption is turned off. Data is transmitted in plaintext.
sslmode=require: Connection is encrypted, but the server's certificate is not verified. This provides protection against packet sniffing but not against man-in-the-middle attacks. You may use this for trusted self-signed CA.

Without specifying sslmode, most databases default to certificate verification, which provides the highest level of security.

Example usage:

# Disable SSL
postgres://user:password@localhost:5432/dbname?sslmode=disable

# Require SSL without certificate verification
postgres://user:password@localhost:5432/dbname?sslmode=require

# Standard SSL with certificate verification (default)
postgres://user:password@localhost:5432/dbname

Read-only Mode

You can run DBHub in read-only mode, which restricts SQL query execution to read-only operations:

# Enable read-only mode
npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/dbname"

In read-only mode, only readonly SQL operations are allowed.

This provides an additional layer of security when connecting to production databases.

Configure your database connection

You can use DBHub in demo mode with a sample employee database for testing:

npx @bytebase/dbhub  --demo

[!WARNING] If your user/password contains special characters, you need to escape them first. (e.g. pass#word should be escaped as pass%23word)

For real databases, a Database Source Name (DSN) is required. You can provide this in several ways:

Command line argument (highest priority):

npx @bytebase/dbhub  --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

Environment variable (second priority):

export DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"
npx @bytebase/dbhub

Environment file (third priority):
- For development: Create .env.local with your DSN
- For production: Create .env with your DSN
```
DSN=postgres://user:password@localhost:5432/dbname?sslmode=disable
```

[!WARNING] When running in Docker, use host.docker.internal instead of localhost to connect to databases running on your host machine. For example: mysql://user:password@host.docker.internal:3306/dbname

DBHub supports the following database connection string formats:

Database	DSN Format	Example
MySQL	`mysql://[user]:[password]@[host]:[port]/[database]`	`mysql://user:password@localhost:3306/dbname?sslmode=disable`
MariaDB	`mariadb://[user]:[password]@[host]:[port]/[database]`	`mariadb://user:password@localhost:3306/dbname?sslmode=disable`
PostgreSQL	`postgres://[user]:[password]@[host]:[port]/[database]`	`postgres://user:password@localhost:5432/dbname?sslmode=disable`
SQL Server	`sqlserver://[user]:[password]@[host]:[port]/[database]`	`sqlserver://user:password@localhost:1433/dbname?sslmode=disable`
SQLite	`sqlite:///[path/to/file]` or `sqlite:///:memory:`	`sqlite:///path/to/database.db`, `sqlite:C:/Users/YourName/data/database.db (windows)` or `sqlite:///:memory:`

SQL Server

Extra query parameters:

authentication

authentication=azure-active-directory-access-token. Only applicable when running from Azure. See DefaultAzureCredential.

Transport

stdio (default) - for direct integration with tools like Claude Desktop:

npx @bytebase/dbhub --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

http - for browser and network clients:

npx @bytebase/dbhub --transport http --port 5678 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

Command line options

Option	Environment Variable	Description	Default
dsn	`DSN`	Database connection string	Required if not in demo mode
transport	`TRANSPORT`	Transport mode: `stdio` or `http`	`stdio`
port	`PORT`	HTTP server port (only applicable when using `--transport=http`)	`8080`
readonly	`READONLY`	Restrict SQL execution to read-only operations	`false`
demo	N/A	Run in demo mode with sample employee database	`false`

The demo mode uses an in-memory SQLite database loaded with the sample employee database that includes tables for employees, departments, titles, salaries, department employees, and department managers. The sample database includes SQL scripts for table creation, data loading, and testing.

Development

Install dependencies:
```
pnpm install
```
Run in development mode:
```
pnpm dev
```

Build for production:

pnpm build
pnpm start --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

Testing

The project uses Vitest for comprehensive unit and integration testing:

Run all tests: pnpm test
Run tests in watch mode: pnpm test:watch
Run integration tests: pnpm test:integration

Integration Tests

DBHub includes comprehensive integration tests for all supported database connectors using Testcontainers. These tests run against real database instances in Docker containers, ensuring full compatibility and feature coverage.

Prerequisites

Docker: Ensure Docker is installed and running on your machine
Docker Resources: Allocate sufficient memory (recommended: 4GB+) for multiple database containers
Network Access: Ability to pull Docker images from registries

Running Integration Tests

Note: This command runs all integration tests in parallel, which may take 5-15 minutes depending on your system resources and network speed.

# Run all database integration tests
pnpm test:integration

# Run only PostgreSQL integration tests
pnpm test src/connectors/__tests__/postgres.integration.test.ts
# Run only MySQL integration tests
pnpm test src/connectors/__tests__/mysql.integration.test.ts
# Run only MariaDB integration tests
pnpm test src/connectors/__tests__/mariadb.integration.test.ts
# Run only SQL Server integration tests
pnpm test src/connectors/__tests__/sqlserver.integration.test.ts
# Run only SQLite integration tests
pnpm test src/connectors/__tests__/sqlite.integration.test.ts
# Run JSON RPC integration tests
pnpm test src/__tests__/json-rpc-integration.test.ts

All integration tests follow these patterns:

Container Lifecycle: Start database container → Connect → Setup test data → Run tests → Cleanup
Shared Test Utilities: Common test patterns implemented in IntegrationTestBase class
Database-Specific Features: Each database includes tests for unique features and capabilities
Error Handling: Comprehensive testing of connection errors, invalid SQL, and edge cases

Troubleshooting Integration Tests

Container Startup Issues:

# Check Docker is running
docker ps

# Check available memory
docker system df

# Pull images manually if needed
docker pull postgres:15-alpine
docker pull mysql:8.0
docker pull mariadb:10.11
docker pull mcr.microsoft.com/mssql/server:2019-latest

SQL Server Timeout Issues:

SQL Server containers require significant startup time (3-5 minutes)
Ensure Docker has sufficient memory allocated (4GB+ recommended)
Consider running SQL Server tests separately if experiencing timeouts

Network/Resource Issues:

# Run tests with verbose output
pnpm test:integration --reporter=verbose

# Run single database test to isolate issues
pnpm test:integration -- --testNamePattern="PostgreSQL"

# Check Docker container logs if tests fail
docker logs <container_id>

Pre-commit Hooks (for Developers)

The project includes pre-commit hooks to run tests automatically before each commit:

After cloning the repository, set up the pre-commit hooks:
```
./scripts/setup-husky.sh
```
This ensures the test suite runs automatically whenever you create a commit, preventing commits that would break tests.

Debug with MCP Inspector

stdio

# PostgreSQL example
TRANSPORT=stdio DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js

HTTP

# Start DBHub with HTTP transport
pnpm dev --transport=http --port=8080

# Start the MCP Inspector in another terminal
npx @modelcontextprotocol/inspector

Connect to the DBHub server /message endpoint

DBHub Overview