255 lines
9.0 KiB
Plaintext
255 lines
9.0 KiB
Plaintext
---
|
|
title: Getting Started
|
|
description: Install DBX, create your first connection, and understand the desktop, Docker, and source workflows.
|
|
---
|
|
|
|
This guide gets you through three things:
|
|
|
|
1. Install DBX or start the Docker version
|
|
2. Create and test your first database connection
|
|
3. Run DBX from source when you want to contribute or debug locally
|
|
|
|
## Choose An Install Method
|
|
|
|
<Tabs groupId="platform" items={['macOS', 'Windows', 'Linux', 'Docker']}>
|
|
<Tab value="macOS">
|
|
Install with Homebrew:
|
|
|
|
```bash
|
|
brew install --cask dbx
|
|
```
|
|
|
|
Update later with:
|
|
|
|
```bash
|
|
brew upgrade --cask dbx
|
|
```
|
|
|
|
You can also download a `.dmg` installer from [GitHub Releases](https://github.com/t8y2/dbx/releases).
|
|
|
|
</Tab>
|
|
<Tab value="Windows">
|
|
Install with Scoop:
|
|
|
|
```bash
|
|
scoop bucket add dbx https://github.com/t8y2/scoop-bucket
|
|
scoop install dbx
|
|
```
|
|
|
|
Update later with:
|
|
|
|
```bash
|
|
scoop update dbx
|
|
```
|
|
|
|
You can also download a `.msi` installer from [GitHub Releases](https://github.com/t8y2/dbx/releases).
|
|
|
|
</Tab>
|
|
<Tab value="Linux">
|
|
Install with Flatpak from [FlatPark](https://flatpark.org/apps/com.dbxio.dbx/) (works on any distribution):
|
|
|
|
```bash
|
|
flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
|
|
flatpak install flatpark com.dbxio.dbx
|
|
```
|
|
|
|
Update later with:
|
|
|
|
```bash
|
|
flatpak update com.dbxio.dbx
|
|
```
|
|
|
|
You can also download a package from [GitHub Releases](https://github.com/t8y2/dbx/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:
|
|
|
|
```bash
|
|
chmod +x DBX*.AppImage
|
|
```
|
|
|
|
</Tab>
|
|
<Tab value="Docker">
|
|
Docker is for self-hosting DBX on a server and opening it from a browser:
|
|
|
|
```bash
|
|
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.
|
|
|
|
Then open `http://localhost:4224`.
|
|
|
|
`deploy/docker-compose.yml` builds the current checkout. To deploy a published image, use `deploy/docker-compose.release.yml`:
|
|
|
|
```bash
|
|
docker compose -f deploy/docker-compose.release.yml up -d
|
|
```
|
|
|
|
```yaml
|
|
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:
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## 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.
|
|
|
|
<Callout type="info">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.</Callout>
|
|
|
|
## Create Your First Connection
|
|
|
|
<Steps>
|
|
<Step>
|
|
### Open New Connection
|
|
|
|
Click **New Connection** from the sidebar or toolbar.
|
|
|
|
</Step>
|
|
<Step>
|
|
### 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](/en/docs/databases).
|
|
|
|
</Step>
|
|
<Step>
|
|
### 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.
|
|
|
|
</Step>
|
|
<Step>
|
|
### 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, DM, GaussDB, openGauss, TDengine, and Access. Review the parsed fields before saving.
|
|
|
|
</Step>
|
|
<Step>
|
|
### Add Network Options
|
|
|
|
Use [Tunnel / Proxy](/en/docs/ssh-tunnel) for databases behind private networks, bastion hosts, web-only gateways, or SOCKS5/HTTP proxy environments.
|
|
|
|
</Step>
|
|
<Step>
|
|
### 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.
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
<Callout type="info">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](/en/docs/config-export) when you need to migrate encrypted connection settings.</Callout>
|
|
|
|
## 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](/en/docs/production-safety) for complete behavior and recommended configurations.
|
|
|
|
## What To Try Next
|
|
|
|
<Cards>
|
|
<Card title="Write SQL" href="/en/docs/query-editor">
|
|
Use completion, formatting, selected execution, cancellation, and history.
|
|
</Card>
|
|
<Card title="Browse Data" href="/en/docs/data-grid">
|
|
Inspect results, edit rows when safe, preview SQL, and export data.
|
|
</Card>
|
|
<Card title="Explore Schema" href="/en/docs/schema-browser">
|
|
Browse databases, schemas, tables, columns, Redis keys, and MongoDB collections.
|
|
</Card>
|
|
</Cards>
|
|
|
|
## 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.
|
|
|
|
<Callout type="info">
|
|
First-time contributors should follow [Build From Source and Contribute](/en/docs/contributing) for complete platform setup, forking, issue claiming, testing, and pull request steps.
|
|
</Callout>
|
|
|
|
### Requirements
|
|
|
|
- [Node.js](https://nodejs.org/) >= 22.13.0
|
|
- [pnpm](https://pnpm.io/) 10.27.0
|
|
- Make
|
|
- [Rust](https://www.rust-lang.org/tools/install) >= 1.88
|
|
|
|
### System Dependencies
|
|
|
|
<Tabs groupId="dev-platform" items={["macOS", "Linux", "Windows"]}>
|
|
<Tab value="macOS">```bash brew install unixodbc ```</Tab>
|
|
<Tab value="Linux">```bash sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev ```</Tab>
|
|
<Tab value="Windows">Windows usually needs no extra system dependency for local DBX development.</Tab>
|
|
</Tabs>
|
|
|
|
### Start Development
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make dev-web
|
|
make dev-backend
|
|
```
|
|
|
|
### Build Desktop Packages
|
|
|
|
```bash
|
|
make package
|
|
```
|
|
|
|
Desktop installers are written to `src-tauri/target/release/bundle/`.
|