DBFlux

An extensible, keyboard-first data platform delivered as a Rust + GPUI desktop client.

Overview

DBFlux is an open-source desktop client with built-in drivers for relational and non-relational databases. Its core contracts are driver-neutral, and external drivers can integrate over RPC.

The client focuses on performance, a clean UX, and keyboard-first workflows. The long-term goal is to provide a fully open-source alternative to DBeaver.

Documentation

Choose the path that matches what you want to do.

Start here

Goal	Guide
Create a connection	Start with the Usage Guide. For SSH tunnels, proxies, AWS SSO, and value sources, use Connecting — Advanced Setup.
Run queries and follow common workflows	Follow the Usage Guide for querying, browsing results, charting, exporting, and keyboard navigation.
View audit events	Open the audit viewer with the Dashboards & Audit User Guide.
Use MCP	Follow the AI + MCP Integration Guide.
Check driver support and limitations	Use Drivers Overview, the canonical capability and limitations overview.

More user guides

• Settings & Hooks — settings, connection hooks, and access profiles
• Data & Privacy — data and secret storage, backup, and reset
• Lua Scripting — the embedded Lua runtime for hooks

Contributors

• Contributing — setup, checks, and contribution workflow
• Key Concepts — the short mental model for contracts and subsystem boundaries
• Driver Authoring — choose and implement a built-in Rust or external RPC driver
• Architecture — the canonical architecture and crate map, including crate boundaries and cross-crate flows

Reference

• Charts — chart types, column kinds, and axis auto-detection
• Dashboards — dashboards, saved charts, instance metrics, and inspectors
• Audit — audit event schema and redaction
• Driver RPC Protocol
• RPC Services Config
• Release Process
• Code Style
• Agent Instructions
• Claude Instructions

Installation

Linux

Tarball (recommended)

# Install to /usr/local (requires sudo)
curl -fsSL https://raw.githubusercontent.com/0xErwin1/dbflux/main/scripts/install.sh | sudo bash

# Install to ~/.local (no sudo required)
curl -fsSL https://raw.githubusercontent.com/0xErwin1/dbflux/main/scripts/install.sh | bash -s -- --prefix ~/.local

AppImage (portable)

# Download from releases (replace amd64 with arm64 for ARM)
wget https://github.com/0xErwin1/dbflux/releases/latest/download/dbflux-linux-amd64.AppImage
chmod +x dbflux-linux-amd64.AppImage
./dbflux-linux-amd64.AppImage

Arch Linux

Available in the AUR:

# Using an AUR helper
paru -S dbflux
# or
yay -S dbflux

Debian / Ubuntu

Download the .deb package from Releases:

# Replace amd64 with arm64 for ARM
wget https://github.com/0xErwin1/dbflux/releases/latest/download/dbflux-linux-amd64.deb
sudo dpkg -i dbflux-linux-amd64.deb

Fedora / RHEL / CentOS

Download the .rpm package from Releases:

# Replace amd64 with arm64 for ARM
sudo dnf install https://github.com/0xErwin1/dbflux/releases/latest/download/dbflux-linux-amd64.rpm

Nix

Using flakes (the default package is a prebuilt binary for Linux x86_64 / aarch64, no compilation):

# Run directly (prebuilt)
nix run github:0xErwin1/dbflux

# Install to profile (prebuilt)
nix profile install github:0xErwin1/dbflux

# Development shell
nix develop github:0xErwin1/dbflux

Build from source instead of using the prebuilt binary:

nix run    github:0xErwin1/dbflux#dbflux-source
nix build  github:0xErwin1/dbflux#dbflux-source

Nightly builds track main and install side by side with stable (distinct app id, icon, and dbflux-nightly.db database). Consume them from the nightly ref:

nix run github:0xErwin1/dbflux/nightly#dbflux-nightly
nix profile install github:0xErwin1/dbflux/nightly#dbflux-nightly

See docs/RELEASE.md for the channel model.

NixOS / nix-darwin via overlay:

{
  inputs.dbflux.url = "github:0xErwin1/dbflux";

  outputs = { nixpkgs, dbflux, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        ({ pkgs, ... }: {
          nixpkgs.overlays = [ dbflux.overlays.default ];
          environment.systemPackages = [
            pkgs.dbflux         # prebuilt binary, no local compile
            # pkgs.dbflux-source  # alternative: build from source
          ];
        })
      ];
    };
  };
}

macOS

DBFlux for macOS is not signed with an Apple developer certificate. When opening for the first time, you'll see a warning about an "unidentified developer".

Installation

1. Download the DMG for your architecture from Releases:
   • Intel Macs: dbflux-macos-amd64.dmg
   • Apple Silicon (M1/M2/M3/M4): dbflux-macos-arm64.dmg
2. Open the DMG and drag DBFlux to Applications
3. When you see the "unidentified developer" warning:
   • Go to System Settings → Privacy & Security
   • Click Open Anyway next to the security warning
   • Confirm you want to open the application

Bypass Gatekeeper from Terminal

# Remove quarantine attribute (allows opening without GUI confirmation)
xattr -cr /Applications/DBFlux.app

# Now you can open it normally
open /Applications/DBFlux.app

Requirements

• macOS 11.0 (Big Sur) or later

Windows

Installer

1. Download dbflux-windows-amd64-setup.exe from Releases
2. Run the installer and follow the wizard

Portable

1. Download dbflux-windows-amd64.zip from Releases
2. Extract to any folder
3. Run dbflux.exe

Note: The executable is not signed with a Windows code signing certificate. Windows SmartScreen may show a warning. Click "More info" → "Run anyway" to proceed.

Requirements

• Windows 10 or later
• x86_64 (ARM64 not yet supported)

Build from Source

# Via install script (Linux)
curl -fsSL https://raw.githubusercontent.com/0xErwin1/dbflux/main/scripts/install.sh | bash -s -- --build

# Or manually
git clone https://github.com/0xErwin1/dbflux.git
cd dbflux

# Recommended: build with the full default feature set
cargo build --release --features sqlite,postgres,mysql,mssql,mongodb,redis,dynamodb,cloudwatch,influxdb,lua,aws,mcp

# Minimal build (relational drivers only, no AI/MCP, no Lua)
cargo build --release --no-default-features --features sqlite,postgres,mysql

./target/release/dbflux

Uninstall (Linux)

# If installed with install.sh
curl -fsSL https://raw.githubusercontent.com/0xErwin1/dbflux/main/scripts/uninstall.sh | sudo bash

# From ~/.local
curl -fsSL https://raw.githubusercontent.com/0xErwin1/dbflux/main/scripts/uninstall.sh | bash -s -- --prefix ~/.local

# Remove user config and data too
./scripts/uninstall.sh --remove-config

Features

Database Support

• PostgreSQL with SSL/TLS modes (Disable, Prefer, Require)
• Amazon Redshift with read-only SQL over the PostgreSQL wire protocol, SSH tunneling, and TLS/client certificates
• MySQL / MariaDB
• SQLite for local database files
• Microsoft SQL Server (TDS) with TLS, SQL Browser named-instance routing, and multi-schema introspection
• MongoDB with collection browsing, document CRUD, and shell query generation
• Redis with key browsing for all types (String, Hash, List, Set, Sorted Set, Stream)
• DynamoDB with table browsing, item CRUD, and AWS authentication
• InfluxDB v1 and v2 (InfluxQL on v1, InfluxQL + Flux on v2)
• CloudWatch Logs with log group/stream browsing and event streaming
• Amazon S3 with bucket browsing, object preview/editing, full CRUD, and presigned URLs, including S3-compatible endpoints (Cloudflare R2, MinIO)
• External drivers over RPC (register out-of-process drivers via the Driver RPC Protocol)

See docs/DRIVERS.md for a full capability matrix and per-driver limitations.

User Interface

• Document-based workspace with multiple result tabs (like DBeaver/VS Code)
• Collapsible, resizable sidebar with ToggleSidebar command (Ctrl+B)
• Schema tree browser with lazy loading for large databases
• Schema-level metadata: indexes, foreign keys, constraints, custom types (PostgreSQL)
• Stored procedures / routines folder per schema (drivers that expose them)
• Multi-tab SQL editor with syntax highlighting and multi-statement execution (one result set per statement, where the driver supports it)
• Virtualized data table with column resizing, horizontal scrolling, and sorting
• Table browser with WHERE filters, custom LIMIT, and pagination
• Workspace inspector rail for row/document details
• "Copy as Query" context menu to copy INSERT/UPDATE/DELETE as SQL, MongoDB shell, or Redis commands
• Query preview modal with language-specific syntax highlighting
• Command palette with fuzzy search
• Custom toast notification system with auto-dismiss
• Background task panel
• Session restore: open tabs are restored on startup with conflict detection for externally modified files

Visual Query Builder

• Right-rail SELECT builder: projection, joins, a nested WHERE predicate tree, ORDER BY, and LIMIT/OFFSET, with a live parameterized SQL preview
• GROUP BY with aggregates (COUNT, SUM, AVG, MIN, MAX) and HAVING
• Visual UPDATE / DELETE builder with mutation policies (read-only / approval-required) and chunked, cancellable execution
• Schema-aware autocomplete on builder inputs and the results WHERE filter
• Relational filters in the results filter bar via dotted foreign-key paths (e.g. created_by.email LIKE '%@acme.com')
• Inline cell edit and row delete on builder-generated results when they map 1:1 to a single table
• Saved visual queries per connection
• SQL drivers only (SQLite, PostgreSQL, MySQL/MariaDB, SQL Server); driver-agnostic by construction

Charts & Visualization

• Chart any query or collection result: Line, Bar, Scatter, Area, Stacked Bar, and Pie
• Automatic axis detection from column kinds (timestamp X axis, numeric Y series) — no per-driver heuristics
• Saved charts that reopen as their own document tab
• Dashboards: arrange saved charts, dividers, and inspector panels on a 12-column grid with a shared time range
• Read-only Instance Overview per connection — live server metrics and tabular inspectors, with "Save as editable"; PostgreSQL, MySQL/MariaDB, MongoDB, Redis, and SQL Server ship instance catalogs
• Browse and import upstream provider dashboards (CloudWatch)
• See docs/CHARTS.md and docs/DASHBOARDS.md for details

Connectivity & Access

• SSH tunnels with key, password, and agent authentication; reusable SSH tunnel profiles
• SOCKS5 / HTTP CONNECT proxy tunnels with reusable proxy profiles
• Managed access providers (AWS SSM) for connecting without exposing ports
• Provider-driven auth profiles (e.g. AWS SSO/shared/static), with import from ~/.aws/config
• Connection hooks at PreConnect/PostConnect/PreDisconnect/PostDisconnect, runnable as a command, a script, or in-process Lua

AI & MCP Integration

• Built-in Model Context Protocol (MCP) server (dbflux mcp) for AI clients
• Governance layer: operation classification, role/policy engine, trusted clients, and human approval flow for write/destructive operations
• See docs/MCP_AI_INTEGRATION.md

Audit & Scripting

• SQLite-backed audit log for queries, connections, hooks, scripts, MCP, governance, and config events, with redaction and query fingerprinting — see docs/AUDIT.md
• Centralized user-facing error reporting: failures surface as a toast with a correlation id and a "View in Audit" action, drive a status-bar error badge, and are correlated with their audit row
• Lua, Python, and Bash scripts run as documents with live streamed output — see docs/LUA.md

Keyboard Navigation

• Vim-style navigation (j/k/h/l) throughout the app
• Context-aware keybindings (Document, Sidebar, BackgroundTasks)
• Document focus with internal editor/results navigation
• Results toolbar: f to focus, h/l to navigate, Enter to edit/execute, Esc to exit
• Toggle sidebar with Ctrl+B
• Tab switching (MRU order) with Ctrl+Tab / Ctrl+Shift+Tab

Query Management

• Query history with timestamps
• Saved queries with favorites
• Search across history and saved queries

Export

• Shape-based export: CSV, JSON (pretty/compact), Text, Binary (raw/hex/base64)
• Export format determined by result type (table, JSON, text, binary)

Development

Prerequisites

On Linux, the mold linker is required for local builds: the repo's .cargo/config.toml links the x86_64-unknown-linux-gnu target with -fuse-ld=mold to cut link time and memory across the 60+ workspace crates. The Nix dev shell provides it automatically; for non-Nix setups install it via your package manager (included below). Windows and macOS use their default linker and are unaffected.

Ubuntu/Debian:

sudo apt install pkg-config libssl-dev libdbus-1-dev libxkbcommon-dev mold

Fedora:

sudo dnf install pkg-config openssl-devel dbus-devel libxkbcommon-devel mold

Arch:

sudo pacman -S pkg-config openssl dbus libxkbcommon mold

macOS:

# Xcode Command Line Tools (required)
xcode-select --install

Windows:

# Visual Studio Build Tools with C++ workload (required)
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

Building

cargo build -p dbflux --release

Running

cargo run -p dbflux

Commands

cargo check --workspace                    # Type checking
cargo clippy --workspace -- -D warnings    # Lint
cargo fmt --all                            # Format
cargo test --workspace                     # Tests

Faster tests with nextest

cargo-nextest is the recommended test runner for this workspace: it runs each test in its own process across a global pool, which is noticeably faster than cargo test on a workspace this size. The Nix dev shell provides it; otherwise install it from https://nexte.st/docs/installation.

cargo nextest run --workspace              # unit + integration tests
cargo test --doc --workspace               # doctests (nextest does not run these)

Live integration tests (normally #[ignore]d) use a different flag under nextest:

cargo nextest run -p dbflux_driver_sqlite --run-ignored all

Nix Development Shell

If you use Nix, you can enter a development shell with all dependencies:

# With flakes
nix develop

# Traditional
nix-shell

License

MIT & Apache-2.0