dbx/docs/content/docs/getting-started.mdx

---
title: Getting Started
description: Install DBX, create your first connection, and understand the desktop, Docker, and source-based workflows.
---

This guide gets you through three steps:

1. Install DBX or start the Docker version
2. Create your first database connection
3. Run the project 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 t8y2/tap/dbx
    ```

    Upgrade to the latest version:

    ```bash
    brew upgrade --cask t8y2/tap/dbx
    ```

    You can also download the `.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
    ```

    Upgrade to the latest version:

    ```bash
    scoop update dbx
    ```

    You can also download the `.msi` installer from [GitHub Releases](https://github.com/t8y2/dbx/releases).
  </Tab>
  <Tab value="Linux">
    Download the right package from [GitHub Releases](https://github.com/t8y2/dbx/releases):

    | Format | Best For |
    |---|---|
    | `.deb` | Debian, Ubuntu, and related distributions |
    | `.AppImage` | General Linux desktop environments |

    For `.AppImage`, you may need to make the file executable first:

    ```bash
    chmod +x DBX*.AppImage
    ```
  </Tab>
  <Tab value="Docker">
    Use Docker when you want to host DBX on a server and access it from a browser:

    ```bash
    docker run -d \
      --name dbx \
      -p 4224:4224 \
      -v dbx-data:/app/data \
      t8y2/dbx
    ```

    Open `http://localhost:4224` after the container starts.

    Docker Compose:

    ```yaml
    services:
      dbx:
        image: t8y2/dbx
        ports:
          - "4224:4224"
        volumes:
          - dbx-data:/app/data
        restart: unless-stopped

    volumes:
      dbx-data:
    ```
  </Tab>
</Tabs>

<Callout type="info">
Use the desktop app for personal local work. Use Docker for server-hosted or browser-based access. The core product is the same, but deployment and data storage differ.
</Callout>

## Create Your First Connection

<Steps>
  <Step>
    ### Open New Connection

    Click **New Connection** from the sidebar or toolbar.
  </Step>
  <Step>
    ### Choose a Database Type

    Select MySQL, PostgreSQL, SQLite, Redis, MongoDB, or another supported engine.
  </Step>
  <Step>
    ### Enter Connection Details

    Fill in host, port, username, and password. For engines such as PostgreSQL and MySQL, you can set a default database so DBX opens it automatically after connecting.
  </Step>
  <Step>
    ### Test the Connection

    Click **Test** to verify network access, credentials, and permissions. If the database is behind a private network or bastion host, configure an [SSH Tunnel](/en/docs/ssh-tunnel).
  </Step>
  <Step>
    ### Save and Connect

    When the test succeeds, click **Save & Connect**. The connection appears in the sidebar for future use.
  </Step>
</Steps>

<Callout type="info">
Connection configuration is stored in a local SQLite database under the app data directory. Passwords, SSH passwords, SSH key passphrases, and connection strings are removed from the normal connection JSON and stored separately in the `connection_secrets` table.
</Callout>

## What to Try Next

<Cards>
  <Card title="Write SQL" href="/en/docs/query-editor">
    Open the query editor and use completion, formatting, selected execution, and query history.
  </Card>
  <Card title="Browse Data" href="/en/docs/data-grid">
    Open table data and use filtering, sorting, inline editing, and SQL preview.
  </Card>
  <Card title="Explore Schema" href="/en/docs/schema-browser">
    Browse databases, schemas, tables, columns, indexes, and foreign keys from the sidebar.
  </Card>
</Cards>

## Common Connection Issues

| Symptom | Check |
|---|---|
| Connection timeout | Host, port, firewall, security group, VPN, or private network access |
| Authentication failed | Username, password, auth method, and whether the account allows remote login |
| Connected but no tables are visible | Default database, schema permissions, and metadata read permissions |
| Private database is unreachable | Configure an SSH tunnel, or make sure the Docker host can reach the database |

## Run From Source

Use the source workflow when you want to contribute or debug DBX locally.

### Prerequisites

- [Node.js](https://nodejs.org/) >= 18
- [pnpm](https://pnpm.io/)
- [Rust](https://www.rust-lang.org/tools/install) >= 1.77

### 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 includes ODBC support, so additional system dependencies are usually not required.
  </Tab>
</Tabs>

### Start the Development App

```bash
git clone https://github.com/t8y2/dbx.git
cd dbx
pnpm install
pnpm dev:tauri
```

### Build the Desktop App

```bash
pnpm tauri build
```

Build artifacts are written to `src-tauri/target/release/bundle/`.