Skip to main content
Environment variables provide a convenient way to configure DBHub without command-line flags. This method is ideal for containerized deployments, CI/CD pipelines, and when you want to keep credentials separate from your code.

​
Configuration Methods

DBHub supports two ways to provide database connection parameters via environment variables:
  1. DSN string (recommended) - Single connection string
  2. Individual parameters - Separate variables for each connection detail
Use individual parameters when your password contains special characters (@, :, /, #) that would break URL parsing in a DSN string.

​
.env File Loading

DBHub automatically loads environment variables from .env files: Development mode (using tsx or NODE_ENV=development):
  1. Looks for .env.local first
  2. Falls back to .env
Production mode (compiled build):
  1. Only loads .env
Use .env.local for local development settings and add it to .gitignore. Commit .env as a template with empty/example values.

​
Database Connection

​
Method 1: DSN Connection String

The simplest approach - provide a single connection string:
​
DSN
string
Complete database connection string in URL format.Format: protocol://[user[:password]@]host[:port]/database[?options]

​
DSN Examples by Database Type

# .env
DSN=postgres://postgres:password@localhost:5432/myapp

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

​
Method 2: Individual Connection Parameters

When your password contains special characters, use individual parameters:
​
DB_TYPE
string
required
Database type.Options: postgres, mysql, mariadb, sqlserver, sqlite
​
DB_HOST
string
required
Database server hostname or IP address.Not required for SQLite.
​
DB_PORT
number
Database server port number.Defaults:
  • PostgreSQL: 5432
  • MySQL/MariaDB: 3306
  • SQL Server: 1433
  • SQLite: Not applicable
​
DB_USER
string
required
Database username.Not required for SQLite.
​
DB_PASSWORD
string
required
Database password. Can contain any special characters.Not required for SQLite or Azure AD authentication.
​
DB_NAME
string
required
Database name.For SQLite, this is the file path to the database.

​
Individual Parameters Examples

# .env
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=my@password:with/special#chars
DB_NAME=myapp
When using individual parameters, you cannot specify SSL mode, named instances, or authentication methods. For these advanced options, use a TOML configuration file instead.

​
Transport Configuration

​
TRANSPORT
string
default:"stdio"
MCP server transport protocol.Options:
  • stdio - Standard input/output (for Claude Desktop, Claude Code, Cursor)
  • http - HTTP transport with JSON responses (for network clients)
​
PORT
number
default:"8080"
HTTP server port. Only used when TRANSPORT=http.
# .env
TRANSPORT=http
PORT=3000

​
SSH Tunnel Configuration

Securely connect to databases through SSH bastion hosts:
​
SSH_HOST
string
SSH server hostname or IP address. Can be an alias from ~/.ssh/config.
​
SSH_PORT
number
default:"22"
SSH server port number.
​
SSH_USER
string
required
SSH username for authentication.
​
SSH_PASSWORD
string
SSH password authentication. Use either this or SSH_KEY.
​
SSH_KEY
string
Path to SSH private key file. Use either this or SSH_PASSWORD.Supports ~/ expansion.
​
SSH_PASSPHRASE
string
Passphrase for encrypted SSH private key.
​
SSH_PROXY_JUMP
string
Comma-separated list of jump hosts for multi-hop SSH connections.Format: [user@]host[:port],[user@]host[:port],...
​
SSH_KEEPALIVE_INTERVAL
number
default:"0"
Seconds between SSH keepalive packets. Set to 0 to disable.
​
SSH_KEEPALIVE_COUNT_MAX
number
default:"3"
Maximum number of missed keepalive responses before disconnecting.

​
SSH Examples

# .env
DSN=postgres://user:[email protected]:5432/prod

SSH_HOST=bastion.company.com
SSH_PORT=22
SSH_USER=deploy
SSH_PASSWORD=secret

​
Complete .env Example

A typical production setup: 
# .env

# Database connection
DSN=postgres://app_user:[email protected]:5432/myapp_prod?sslmode=require

# SSH tunnel
SSH_HOST=bastion.company.com
SSH_USER=deploy
SSH_KEY=~/.ssh/id_ed25519
SSH_KEEPALIVE_INTERVAL=60

# Server transport
TRANSPORT=http
PORT=8080

​
.env Template

Create a .env.example file in your repository as a template: 
# .env.example

# Database Connection
# Method 1: Connection String (DSN)
DSN=

# Method 2: Individual Parameters (use when password has special characters)
# DB_TYPE=postgres
# DB_HOST=localhost
# DB_PORT=5432
# DB_USER=postgres
# DB_PASSWORD=
# DB_NAME=mydatabase

# Transport Configuration
TRANSPORT=stdio
PORT=8080

# SSH Tunnel (optional)
# SSH_HOST=
# SSH_PORT=22
# SSH_USER=
# SSH_PASSWORD=
# SSH_KEY=~/.ssh/id_rsa
# SSH_PASSPHRASE=
Developers copy this to .env and fill in their values: 
cp .env.example .env
Add .env and .env.local to your .gitignore to prevent committing secrets.

​
When to Use Environment Variables

Use environment variables when:
  • Deploying in containers (Docker, Kubernetes)
  • Running in CI/CD pipelines
  • Managing a single database connection
  • Passwords contain special characters
  • You want environment-specific configs (dev/staging/prod)
Use TOML configuration when:
  • Managing multiple databases
  • Need per-tool settings (readonly, max_rows)
  • Defining custom SQL tools
  • Advanced SSH tunnel configurations
  • Per-database timeouts or connection pooling
See TOML Configuration for multi-database setups.

​
Configuration Priority

Remember that environment variables have lower priority than command-line arguments:
  1. Command-line arguments (highest)
  2. TOML config file
  3. Environment variables ← You are here
  4. .env files (lowest)
Command-line flags will override environment variables. This is useful for temporary testing without modifying your .env file.

​
Deprecated Variables

The following environment variables are no longer supported:
Removed in current version:
  • READONLY - Use TOML [[tools]] configuration instead
  • MAX_ROWS - Use TOML [[tools]] configuration instead
See execute_sql tool configuration for migration guidance.

​
Next Steps

Command-Line Flags

Override settings with command-line arguments

TOML Configuration

Set up multiple databases with advanced options

Build docs developers (and LLMs) love

Get started for freeTalk to us