Installation

DBHub can be installed and run in multiple ways depending on your environment and preferences.

Installation methods

Docker
npm
Build from source

The easiest way to run DBHub is using the official Docker image:

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.

With TOML configuration

For multi-database setups, mount your dbhub.toml configuration file:

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  --volume $(pwd)/dbhub.toml:/app/dbhub.toml \
  bytebase/dbhub \
  --transport http \
  --port 8080 \
  --config /app/dbhub.toml

Demo mode

Try DBHub with a bundled SQLite employee database:

docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  bytebase/dbhub \
  --transport http \
  --port 8080 \
  --demo

Install DBHub globally using npm:

npm install -g @bytebase/dbhub

Or run directly with 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 always running the most recent version. The current version is 0.17.0.

With environment variables

Create a .env file and run without command-line arguments:

.env

DSN=postgres://user:password@localhost:5432/dbname
TRANSPORT=http
PORT=8080

npx @bytebase/dbhub@latest

Demo mode

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

Clone the repository and build from source:

# Clone the repository
git clone https://github.com/bytebase/dbhub.git
cd dbhub

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run DBHub
pnpm start -- --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname"

Development mode

Run in development mode with hot reloading:

# Start both backend and frontend in dev mode
pnpm dev

This starts:

Backend MCP server on HTTP transport
Frontend development server with hot module replacement

Development mode automatically uses any dbhub.toml file in your project directory.

Configure MCP clients

Once DBHub is installed, configure your MCP client to connect to it.

Claude Desktop
Cursor
VS Code

Add DBHub to your Claude Desktop configuration file:

// ~/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 specify --transport http in the configuration.

With TOML configuration

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--config",
        "/path/to/dbhub.toml"
      ]
    }
  }
}

With demo mode

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

Add DBHub to your Cursor MCP settings:

Open Cursor Settings
Navigate to “MCP Servers”
Add a new server with the following configuration:

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

Cursor uses stdio transport. The DSN can also be provided via environment variables or TOML configuration.

Install the MCP extension for VS Code and configure DBHub:

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

DSN formats

DBHub supports standard connection string formats for all databases:

postgres://user:password@localhost:5432/dbname?sslmode=disable
postgres://user:password@localhost:5432/dbname?sslmode=require

If your password contains special characters like @, :, /, or #, use environment variables or TOML configuration with individual parameters instead of a DSN string.

SSL modes

sslmode=disable: No SSL encryption (default)
sslmode=require: SSL encryption without certificate verification

For production databases, always use sslmode=require to encrypt your connection.

Command-line options

DBHub accepts the following command-line arguments:

Option	Description	Default
`--dsn`	Database connection string	-
`--transport`	Transport protocol: `stdio` or `http`	`stdio`
`--port`	HTTP server port	`8080`
`--config`	Path to TOML configuration file	`./dbhub.toml`
`--demo`	Use bundled SQLite employee database	`false`
`--readonly`	Restrict to read-only operations (deprecated, use TOML)	`false`
`--max-rows`	Limit rows returned from SELECT (deprecated, use TOML)	unlimited
`--ssh-host`	SSH tunnel hostname	-
`--ssh-port`	SSH tunnel port	`22`
`--ssh-user`	SSH tunnel username	-
`--ssh-password`	SSH tunnel password	-
`--ssh-key`	Path to SSH private key	-
`--ssh-passphrase`	SSH key passphrase	-

Command-line arguments have the highest priority and will override environment variables and TOML configuration.

Environment variables

Alternatively, configure DBHub using environment variables:

.env

# Connection string
DSN=postgres://user:password@localhost:5432/dbname

# Or individual parameters
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=my@password:with/special#chars
DB_NAME=mydatabase

# Transport and port
TRANSPORT=stdio
PORT=8080

# SSH tunnel (optional)
SSH_HOST=bastion.example.com
SSH_PORT=22
SSH_USER=ubuntu
SSH_KEY=~/.ssh/id_rsa

Supported DB_TYPE values: postgres, mysql, mariadb, sqlserver, sqlite

Verify installation

After installation, verify DBHub is working:

Start DBHub in HTTP mode

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

Open the workbench

Navigate to http://localhost:8080 in your browser.

Test a query

Use the execute_sql tool to run a simple query:

SELECT * FROM employee LIMIT 5;

If you see query results, DBHub is installed correctly!

Troubleshooting

Connection refused errors

Verify your database is running and accessible
Check that the hostname, port, and credentials are correct
For remote databases, ensure firewall rules allow connections
Try connecting with a database client (psql, mysql, etc.) using the same credentials

SSL/TLS errors

For development, use ?sslmode=disable in your DSN
For production, ensure SSL certificates are properly configured
Some cloud providers (AWS RDS, Azure) require sslmode=require

Special characters in password

If your password contains @, :, /, or #, use environment variables with individual parameters:

DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=my@complex:password/123
DB_NAME=mydb

MCP client not detecting tools

Restart your MCP client after updating the configuration
Check that the DBHub process is running (look for the dbhub process)
Verify the configuration file path is correct
Check MCP client logs for connection errors

Permission denied on SQLite file

Ensure the SQLite file path is absolute, not relative
Check file permissions allow read/write access
For demo mode, no file path is needed (uses in-memory database)

Next steps

Quick start

Execute your first SQL query in minutes

Multi-database setup

Configure multiple database connections with TOML

SSH tunnels

Connect securely through bastion hosts

Command-line options

Full reference of all CLI arguments

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

Installation

Installation methods

With TOML configuration

Demo mode

With environment variables

Demo mode

Development mode

Configure MCP clients

With TOML configuration

With demo mode

DSN formats

SSL modes

Command-line options

Environment variables

Verify installation

Troubleshooting

Next steps

Quick start

Multi-database setup

SSH tunnels

Command-line options

Build docs developers (and LLMs) love

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

​Installation methods

​With TOML configuration

​Demo mode

​With environment variables

​Demo mode

​Development mode

​Configure MCP clients

​With TOML configuration

​With demo mode

​DSN formats

​SSL modes

​Command-line options

​Environment variables

​Verify installation

​Troubleshooting

​Next steps

Quick start

Multi-database setup

SSH tunnels

Command-line options

Build docs developers (and LLMs) love

Installation methods

With TOML configuration

Demo mode

With environment variables

Demo mode

Development mode

Configure MCP clients

With TOML configuration

With demo mode

DSN formats

SSL modes

Command-line options

Environment variables

Verify installation

Troubleshooting

Next steps