Getting Started

This guide gets you through three things:

Install DBX or start the Docker version
Create and test your first database connection
Run DBX from source when you want to contribute or debug locally

Choose An Install Method

Install with Homebrew:

brew install --cask dbx

Update later with:

brew upgrade --cask dbx

You can also download a .dmg installer from GitHub Releases.

Install with Scoop:

scoop bucket add dbx https://github.com/t8y2/scoop-bucket
scoop install dbx

Update later with:

scoop update dbx

You can also download a .msi installer from GitHub Releases.

Install with Flatpak from FlatPark (works on any distribution):

flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark com.dbxio.dbx

Update later with:

flatpak update com.dbxio.dbx

You can also download a package from GitHub Releases:

Format	Use Case
`.deb`	Debian, Ubuntu, and compatible distributions
`.rpm`	Fedora, CentOS, SUSE and compatible distributions
`.AppImage`	Portable Linux desktop usage

For .AppImage, make the file executable before first run:

chmod +x DBX*.AppImage

Docker is for self-hosting DBX on a server and opening it from a browser:

docker run -d \
  --pull=always \
  --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  t8y2/dbx:latest

The latest tag pulls the current release. This uses the cross-platform dbx-data named volume. For faster pulls in China, use docker.cnb.cool/dbxio.com/dbx:latest instead.

Environment Variables

The Docker image supports the following startup variables. Set one with -e NAME=value; for example, production deployments should add -e DBX_PASSWORD=your-password:

Variable	Default	Purpose
`DBX_PASSWORD`	Not set	Web login password; recommended for production
`DBX_DISABLE_PASSWORD`	`false`	Set to `true` or `1` to disable login protection
`DBX_DATA_DIR`	`/app/data`	Persistent data directory
`DBX_PORT`	`4224`	Container listen port
`DBX_PUBLIC_BASE_PATH`	`/`	Deploy below a subpath, such as `/dbx`

Then open http://localhost:4224.

deploy/docker-compose.yml builds the current checkout. To deploy a published image, use deploy/docker-compose.release.yml:

docker compose -f deploy/docker-compose.release.yml up -d

services:
  dbx:
    image: t8y2/dbx:latest
    # For faster pulls in China, use the CNB image instead:
    # image: docker.cnb.cool/dbxio.com/dbx:latest
    pull_policy: always
    ports:
      - "4224:4224"
    volumes:
      - dbx-data:/app/data
    restart: unless-stopped

volumes:
  dbx-data:

Desktop Or Docker

Mode	Best For	Storage	Important Boundary
Desktop	Daily local work, local database files, the complete workbench	Local app data directory	Supports the local SQL file tree/library, desktop deep links, and OS file integration
Docker / Web	Self-hosting on a server and remote browser access	Docker volume or server data directory	Paths belong to the server; some local-file and desktop integrations are unavailable

Desktop and Web share most database workflows and the Rust core, but their local integrations are not identical. For SQLite, DuckDB, Access, external SQL files, or local directories, verify which machine owns the file; Docker normally requires mounting the directory into the container.

MCP tools that open a table or display results in the desktop UI require DBX Desktop to be running. Query-only MCP tools can read the local DBX data directory directly or connect to a DBX Web/Docker backend.

Create Your First Connection

Open New Connection

Click New Connection from the sidebar or toolbar.

Pick A Database Type

Choose a built-in profile such as MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, or one of the compatibility and Agent/JDBC profiles listed in Database Support.

Fill Connection Details

For network databases, enter host, port, username, password, and default database when needed. For SQLite, DuckDB, and Access, select a local database file instead of host and port.

Paste A URL When Available

DBX can parse common connection URLs for engines such as MySQL, PostgreSQL, Redis, MongoDB, ClickHouse, SQL Server, Oracle, Elasticsearch, Easysearch, Meilisearch, DM, GaussDB, openGauss, TDengine, and Access. Review the parsed fields before saving.

Add Network Options

Use Tunnel / Proxy for databases behind private networks, bastion hosts, web-only gateways, or SOCKS5/HTTP proxy environments.

Test And Save

Click Test to verify credentials, network access, and permissions. After the test passes, save the connection and open it from the sidebar.

Connection passwords, SSH passwords, SSH key passphrases, and connection strings are stored separately from the regular connection JSON in DBX's local storage. Use Config Export/Import when you need to migrate encrypted connection settings.

Reduce Production Mistakes

Give production connections a distinct name such as prod-orders, and use colors, groups, and notes to describe their purpose.
For query-only access, combine a database read-only account with DBX Read-only connection.
Enable Production protection for the whole connection or selected databases; DBX requires a fresh explicit confirmation for writes.
When one server contains many databases or schemas, show only the objects you currently need.
Review generated SQL before applying edits, imports, transfers, SQL files, or schema sync operations.
Put MCP connections behind an allowlist and prefer Read only or Data read/write instead of enabling Full access by default.

See Production and Write Safety for complete behavior and recommended configurations.

What To Try Next

Write SQL

Use completion, formatting, selected execution, cancellation, and history.

Browse Data

Inspect results, edit rows when safe, preview SQL, and export data.

Explore Schema

Browse databases, schemas, tables, columns, Redis keys, and MongoDB collections.

Common Connection Problems

Symptom	Check
Timeout	Host, port, firewall, security group, VPN, Docker host reachability, or private network access
Authentication failed	Username, password, auth mode, SSL requirement, remote login permission
Connected but no tables	Default database, schema, permissions, metadata read access, visible database filter
File database cannot open	File path, file permissions, mounted Docker volume, or unsupported file extension
Private database unreachable	Configure tunnel / proxy, VPN, or run Docker on a machine that can reach the database

Run From Source

Use source mode when contributing or debugging DBX locally.

First-time contributors should follow Build From Source and Contribute for complete platform setup, forking, issue claiming, testing, and pull request steps.

Requirements

Node.js >= 22.13.0
pnpm 10.27.0
Make (required on macOS and Linux; optional on Windows)
Rust >= 1.88

System Dependencies

bash brew install unixodbc

bash sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev

Install Strawberry Perl, required to build the bundled OpenSSL:

winget install StrawberryPerl.StrawberryPerl

DBX enables the sqlite-sqlcipher feature by default, which compiles SQLCipher and OpenSSL from source. Windows needs Perl to run the OpenSSL Configure script. Reopen your terminal after installing so perl is available on PATH.

Start Development

git clone https://github.com/t8y2/dbx.git
cd dbx
make

make installs root dependencies when needed and starts the local Tauri desktop development environment.

For the web version:

make dev-web
make dev-backend

Build Desktop Packages

make package

Desktop installers are written to target/release/bundle/.

Getting Started

Write SQL

Browse Data

Explore Schema

On this page