Quickstart

Get DBHub connected to a database and execute your first query in minutes. This guide walks you through the fastest ways to start exploring databases with AI assistants.

Choose from three quick start paths: Docker for containerized environments, npm for local development, or demo mode to try DBHub without a database.

Quick start paths

Choose your setup method

Docker
npm
Demo mode

Perfect for containerized environments and production deployments.

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

The --init flag ensures proper signal handling for graceful shutdowns.

Quick setup using npx (no installation required).

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

Using @latest ensures you’re running version 0.17.0 or newer.

Try DBHub instantly with a bundled SQLite employee database. No database setup required!

npx @bytebase/dbhub@latest --transport http --port 8080 --demo

The demo database includes sample tables with employee data:

employee - Employee records with names and hire dates
department - Department information
salary - Salary history
dept_manager - Department manager assignments
dept_emp - Employee department assignments

Demo mode is perfect for learning DBHub features and testing MCP tool integrations.

Access the workbench

Once DBHub is running, open the built-in workbench in your browser:

http://localhost:8080

The workbench provides a visual interface for:

Testing SQL queries with the execute_sql tool
Exploring database schemas with the search_objects tool
Running custom tools
Viewing request traces and performance metrics

The workbench runs on HTTP transport (port 8080) regardless of your MCP transport setting.

Execute your first query

Use the execute_sql tool to run your first SQL query.

Demo database
Your database

Try these queries on the demo employee database:

List all employees

SELECT emp_no, first_name, last_name, hire_date 
FROM employee 
LIMIT 10;

Find high earners

SELECT e.first_name, e.last_name, s.amount as salary
FROM employee e
JOIN salary s ON e.emp_no = s.emp_no
WHERE s.amount > 80000
ORDER BY s.amount DESC
LIMIT 5;

Current department managers

SELECT e.first_name, e.last_name, d.dept_name, dm.from_date
FROM dept_manager dm
JOIN employee e ON dm.emp_no = e.emp_no
JOIN department d ON dm.dept_no = d.dept_no
ORDER BY d.dept_name;

Start with simple queries to explore your schema:

List tables (PostgreSQL)

SELECT tablename 
FROM pg_tables 
WHERE schemaname = 'public';

List tables (MySQL/MariaDB)

SHOW TABLES;

List tables (SQL Server)

SELECT TABLE_NAME 
FROM INFORMATION_SCHEMA.TABLES 
WHERE TABLE_TYPE = 'BASE TABLE';

List tables (SQLite)

SELECT name 
FROM sqlite_master 
WHERE type='table';

The execute_sql tool supports multiple statements separated by semicolons and includes transaction support.

Explore your schema

Use the search_objects tool to discover database structure without writing SQL.

{
  "object_type": "table",
  "detail_level": "names"
}

Use detail_level: "names" to minimize token usage and progressively request more details when needed.

Search patterns

The search_objects tool supports SQL LIKE patterns:

% matches any number of characters
_ matches exactly one character
Omit pattern to list all objects (defaults to %)

Object types

Search these database objects:

schema - Database schemas
table - Tables and views
column - Table columns
index - Table indexes
procedure - Stored procedures
function - Database functions

Connect to a real database

Ready to connect DBHub to your own database? Here are DSN examples for each database type:

postgres://user:password@localhost:5432/dbname?sslmode=disable
postgres://user:[email protected]:5432/prod?sslmode=require

If your password contains special characters like @, :, /, or #, use environment variables or TOML configuration instead of DSN strings. See configuration options for details.

SSL/TLS connections

For production databases, enable SSL encryption:

# PostgreSQL with SSL
postgres://user:[email protected]:5432/prod?sslmode=require

# MySQL with SSL
mysql://user:[email protected]:3306/prod?sslmode=require

Available SSL modes:

sslmode=disable - No SSL encryption (default, for development only)
sslmode=require - SSL encryption without certificate verification

Always use sslmode=require for production databases to encrypt your connection.

Configure for MCP clients

DBHub works with any MCP-compatible client. Here’s how to configure popular clients:

Claude Desktop
Cursor
VS Code

Add DBHub to your Claude Desktop configuration:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
      ]
    }
  }
}

Claude Desktop uses stdio transport by default. Do not add --transport http to the args.

With demo mode

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["@bytebase/dbhub@latest", "--demo"]
    }
  }
}

Configure Cursor to use DBHub:

{
  "dbhub": {
    "command": "npx",
    "args": [
      "@bytebase/dbhub@latest",
      "--dsn",
      "postgres://user:password@localhost:5432/dbname?sslmode=disable"
    ]
  }
}

Add this to your Cursor MCP settings (Settings > MCP Servers).

Install an MCP extension for VS Code and add DBHub:

// .vscode/settings.json
{
  "mcp.servers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
      ]
    }
  }
}

Next steps

Multi-database setup

Connect to multiple databases simultaneously with TOML configuration

SSH tunnels

Securely connect through bastion hosts with SSH tunneling

Custom tools

Define reusable SQL operations as parameterized MCP tools

Workbench

Learn about the built-in web interface and request tracing

execute_sql tool

Deep dive into SQL execution with transaction support

search_objects tool

Master progressive schema discovery with minimal tokens

Command-line options

Full reference of CLI arguments and configuration

Security best practices

Learn about read-only mode, row limits, and secure connections

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

Quick start paths

Search patterns

Object types

Connect to a real database

SSL/TLS connections

Configure for MCP clients

With demo mode

Next steps

Multi-database setup

SSH tunnels

Custom tools

Workbench

execute_sql tool

search_objects tool

Command-line options

Security best practices

Build docs developers (and LLMs) love

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

​Quick start paths

​Search patterns

​Object types

​Connect to a real database

​SSL/TLS connections

​Configure for MCP clients

​With demo mode

​Next steps

Multi-database setup

SSH tunnels

Custom tools

Workbench

execute_sql tool

search_objects tool

Command-line options

Security best practices

Build docs developers (and LLMs) love

Quick start paths

Search patterns

Object types

Connect to a real database

SSL/TLS connections

Configure for MCP clients

With demo mode

Next steps