Build From Source and Contribute

This tutorial is for first-time DBX contributors. By the end, you will have:

1. Installed Node.js, pnpm, Rust, and native build dependencies
2. Forked, cloned, and run DBX Desktop
3. Located the relevant code and completed a small change
4. Run checks and tests that match the change
5. Pushed a branch and opened a pull request

1. Choose and Claim an Issue

Open DBX Issues and choose an issue that has no assignee and no active contributor in its comments. Good first contributions have one of these properties:

• The reproduction steps and expected behavior are already clear
• The scope is a small documentation, translation, or UI change
• It affects a database you use and can verify against a real instance

Do not rely only on labels. Read the full issue, comments, screenshots, and previous discussion to confirm that the request is still valid and has not already been implemented elsewhere.

If nobody is working on the issue, post this as a standalone comment:

/claim

The claim workflow assigns the issue to you when it is available. If your proposed solution changes existing behavior, explain the approach briefly in the issue before making a large patch.

If you later cannot continue, post /unclaim as a standalone comment (/unclaimed is also accepted). The workflow removes only your own assignment so another contributor can claim the issue.

2. Install the Toolchain

DBX Desktop uses Tauri, Vue, and Rust. The repository currently requires:

Install Node.js and pnpm

Install Node.js 22 or a newer LTS release from the Node.js website, then enable the pnpm version used by the repository:

corepack enable
corepack prepare pnpm@10.27.0 --activate
node --version
pnpm --version

If your Node.js installation does not include Corepack, use:

npm install --global pnpm@10.27.0

Install Rust

Follow the official Rust installation guide to install rustup. Reopen the terminal and verify the installation:

rustc --version
cargo --version

Install Native Dependencies

See the official Tauri prerequisites for complete platform details. DBX also uses ODBC development libraries.

xcode-select --install
brew install unixodbc

sudo apt update
sudo apt install -y \
  build-essential curl wget file pkg-config \
  libwebkit2gtk-4.1-dev libgtk-3-dev libxdo-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf \
  libssl-dev unixodbc-dev

3. Fork and Clone the Repository

Open t8y2/dbx on GitHub and click Fork.

Replace <your-github-name> with your account name:

git clone https://github.com/<your-github-name>/dbx.git
cd dbx
git remote add upstream https://github.com/t8y2/dbx.git
git remote -v

Use a separate branch for each issue:

git switch -c fix/issue-1234-short-description

Before starting another task, synchronize your main branch:

git switch main
git fetch upstream
git rebase upstream/main
git push origin main

4. Run DBX for the First Time

macOS and Linux

From the repository root, run:

make

make installs dependencies from the lockfile and starts the Tauri desktop development environment. The first Rust build can take a while; later starts are much faster.

For a lightweight desktop build, disable the default Rust features and enable only the DuckDB sidecar and DynamoDB:

make dev-fast

Development builds can run alongside an installed DBX instance. Both use the same local DBX data, so connections and history are available in each window. Avoid changing the same connection, saved SQL, or global setting in both windows at once.

When testing the MCP bridge, the instance started last owns the shared mcp-bridge-port discovery file and receives MCP requests. Redis PubSub prefers port 4224 (or DBX_PORT when set) and automatically falls back to an available local port; the frontend uses the actual bound port.

Windows

Run in PowerShell:

pnpm install --frozen-lockfile
pnpm dev:tauri

For the same lightweight build:

pnpm tauri dev -- --no-default-features --features duckdb-sidecar

Confirm the Environment Works

A successful run opens the DBX desktop window without a compiler error in the terminal. Complete three quick checks:

1. Open Settings
2. Create or open a local test connection
3. Close and start the app again to confirm the setup is repeatable

If port 1420 is already in use, stop the previous DBX/Vite development process and restart.

Local database test environments

Changes to a database driver, connection flow, metadata query, or database-specific UI should be checked against a real instance when possible. The repository provides pinned local Docker Compose recipes for this purpose:

make db-list
make db DB=mysql@8.4
make db-verify DB=mysql@8.4
make db-down DB=mysql@8.4

The service ports listen on 127.0.0.1 by default. Set DB_BIND_ADDRESS=0.0.0.0, choose a strong DB_PASSWORD, and use firewall controls before exposing a host to a shared network. See the Database Test Lab for all supported recipes, overrides, and reset safety requirements.

5. Understand the Repository Layout

Search for a feature name, visible label, or error message when you do not know the file yet:

rg "text to find" apps/desktop/src crates src-tauri packages

6. Make Your First Change

Path A: Update the Website Docs

Documentation is the easiest first contribution. English and Chinese pages use the same base filename:

docs/content/docs/example.mdx
docs/content/docs/example.cn.mdx

Start the docs site:

make docs

On Windows:

cd docs
pnpm install --frozen-lockfile --ignore-workspace
pnpm dev

Open the local address printed in the terminal. When adding a page, also register it in:

docs/content/docs/meta.json
docs/content/docs/meta.cn.json

Run the fast content check and then the full documentation build before submitting:

pnpm --dir docs content:check
make docs-build

content:check verifies bilingual page pairs, navigation coverage and ordering, frontmatter, duplicate titles, and internal links. make docs-build runs the check again and validates the Next.js production build.

Path B: Change the Desktop Frontend

Frontend code lives in apps/desktop/src/. Run the full desktop app or start only the web frontend:

make dev-web

After the change, run at least:

pnpm typecheck
pnpm lint
pnpm test

For UI changes, check light and dark themes, narrow windows, empty data, loading, and failure states. Include screenshots or a recording in the pull request.

Path C: Change the Rust Backend

Shared Rust logic is mainly in crates/dbx-core/; desktop commands are in src-tauri/. When DuckDB is unrelated, start with the fast checks:

make cargo-check-fast
make cargo-test-fast

Database behavior changes should be verified against a real database, not only mocks. Include the database type and version, reproduction SQL, previous behavior, and fixed behavior in the pull request.

Path D: Change an Agent Driver

Agents are separate processes that communicate with DBX through stdin/stdout JSON-RPC. Java/JDBC agents normally use JDK 21; native agents use Go or Rust. Read these first:

• agents/README.md
• agents/docs/agent-authoring.md

Change an Existing Java/JDBC Agent

From the repository root, enter agents/ and build only the target module:

cd agents
java --version
./gradlew :<driver-module>:test :<driver-module>:shadowJar

The Shadow JAR is written under:

agents/drivers/<driver-module>/build/libs/

A successful build does not mean the local DBX app is using the new code. DBX runs .dbx/agents/drivers/<db_type>/agent.jar under the user home directory, so back up and replace the runtime JAR:

cp ~/.dbx/agents/drivers/<db_type>/agent.jar \
  ~/.dbx/agents/drivers/<db_type>/agent.jar.bak
cp drivers/<driver-module>/build/libs/*-all.jar \
  ~/.dbx/agents/drivers/<db_type>/agent.jar

Copy-Item "$HOME\.dbx\agents\drivers\<db_type>\agent.jar" `
  "$HOME\.dbx\agents\drivers\<db_type>\agent.jar.bak"
$jar = Get-ChildItem "drivers\<driver-module>\build\libs\*-all.jar" | Select-Object -First 1
Copy-Item $jar.FullName "$HOME\.dbx\agents\drivers\<db_type>\agent.jar" -Force

Restart DBX or disconnect and reconnect the database so the old agent process exits and the new JAR is loaded. Repeat the issue's reproduction flow against the real database version.

When to Change agents/versions.json

• A change under agents/drivers/<module>/ automatically bumps that module during release
• A change under agents/common/src/main/ or agents/common/build.gradle bumps every module that packages the shared common runtime
• A new driver module must add an initial entry such as "rabbitmq": "0.1.0" to agents/versions.json
• A new Java/JDBC driver must also update agents/settings.gradle, the supported-agent table, build configuration, and tests
• A new native driver must register its build and release artifacts according to the agent authoring/release checklist instead of assuming Gradle handles it
• Keys in versions.json must match published modules; infrastructure modules common and test-support do not have version entries

Normal bug-fix pull requests do not manually bump a version to make the change take effect. The agent release workflow owns version bumps and release artifacts.

Native Agents

Native agents such as oracle, kingbase, and xugu use an agent executable instead of agent.jar. Run the Go tests and build from the module, then follow its README to replace the local runtime executable:

cd agents/drivers/<native-module>
go test ./...
go build -o agent .

For a new database agent, prefer a mature, license-compatible Go or Rust driver. Use Java/JDBC when there is no reliable native driver.

Complete Agent Validation

From agents/, run:

python3 -m unittest discover -s scripts -p '*_test.py'
python3 scripts/validate_agents.py
./gradlew test shadowJar --continue
python3 scripts/validate_agent_jars.py

validate_agents.py checks module declarations, versions.json, Gradle configuration, Main-Class metadata, runtime classification, and forbidden residue. validate_agent_jars.py verifies that built JARs contain the expected entry classes.

7. Check the Change Before Committing

Review the patch and make sure it does not include build artifacts, database files, secrets, or unrelated formatting:

git status
git diff

Run checks that match the changed area:

Run the combined checks when a change crosses multiple areas. For a bug fix, repeat the original reproduction steps to prove the bug is gone and test adjacent normal behavior for regressions.

8. Commit and Push

Use a short conventional commit message:

git add <files-changed-for-this-task>
git commit -m "fix(scope): describe the change"
git push -u origin HEAD

Common prefixes:

• fix(scope): for a bug fix
• feat(scope): for a feature
• docs: for documentation
• test(scope): for tests

Do not combine unrelated problems in the same commit or pull request.

9. Open a Pull Request

Open your fork on GitHub and click Compare & pull request. Set the target repository to t8y2/dbx and the target branch to main.

The pull request description should include:

1. The related issue, for example Fixes #1234
2. What changed
3. Why this approach was used
4. Tests you ran
5. Screenshots or recordings for UI changes
6. Database name, version, and verification steps for database changes

If CI fails, open the failed job and inspect its logs. Push the fix to the same branch; you do not need to create another pull request.

When your linked PR has been merged into the default branch but the issue remains open, post /close as a standalone issue comment. The workflow only closes the issue when you are its current assignee and the author of a merged PR that cross-references the issue.

10. Update the Pull Request After Review

Continue working on the same branch after receiving review feedback:

git add <changed-files>
git commit -m "fix(scope): address review feedback"
git push

If main changed significantly during review, synchronize and push again:

git fetch upstream
git rebase upstream/main
git push --force-with-lease

Troubleshooting

The First Rust Build Is Slow

This is expected. Use make dev-fast for a lightweight desktop build with default Rust features disabled and only the DuckDB sidecar and DynamoDB enabled. make cargo-check-fast and make cargo-test-fast skip all optional default features, so they do not validate DuckDB-specific paths.

pnpm Reports the Wrong Version

Reactivate the repository version:

corepack prepare pnpm@10.27.0 --activate

The UI Does Not Reflect the Change

Confirm that you changed apps/desktop/src/, the Vite/Tauri process is still running, and the terminal or browser console has no compilation error. Rust command changes normally trigger a rebuild.

You Do Not Know Which Tests to Run

Start with the minimum check for the changed directory, then perform the issue's real reproduction flow. If coverage remains uncertain, list completed validation and known gaps in the pull request so maintainers can advise.

Get Help

• Describe the blocker in the original issue and include the complete error and operating system version
• Join Discord
• Read the repository CONTRIBUTING.md

Do not report only "the build failed." Include the command, the first meaningful error in the log, your operating system, and your Node.js, pnpm, and Rust versions.