Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/felixdotgo/querybox/llms.txt

Use this file to discover all available pages before exploring further.

QueryBox is currently under development and has not been officially released. These instructions are for building from source. Official releases with installers will be available soon.

​
Prerequisites

Before installing QueryBox, ensure you have the following tools installed on your system:

Go 1.26+

QueryBox is built with Go. Download and install from go.dev/dlVerify installation:
go version
# Should output: go version go1.26 or higher
Wails v3 is the desktop framework powering QueryBox. Install the CLI:
go install github.com/wailsapp/wails/v3/cmd/wails@latest
For detailed installation instructions, visit the Wails v3 installation guide.
Required for frontend build tooling. Download from nodejs.orgVerify installation:
node --version
# Should output: v18.0.0 or higher
Task is used for build automation. Install via:
go install github.com/go-task/task/v3/cmd/task@latest
See taskfile.dev/installation for more options.
Only required if you plan to modify .proto files. For most users, this is not needed.
1

Install protoc

Download from grpc.io/docs/protoc-installationRecommended version: libprotoc 29.6
2

Install Go protoc plugins

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.10
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.1

​
Platform-Specific Requirements

​
Windows Requirements

1

Install WebView2

Wails v3 requires Microsoft Edge WebView2 Runtime, which is pre-installed on Windows 11 and recent Windows 10 updates.If needed, download from Microsoft’s WebView2 page.
2

Install Build Tools

For building native modules, install:
  • Visual Studio 2019 or newer (Community Edition works)
  • Or, Windows SDK and Build Tools
Wails will guide you through this during your first build if anything is missing.
Windows Defender may flag the built executable. This is common for unsigned applications. You can add an exception or sign your builds.

​
Building from Source

1

Clone the Repository

git clone https://github.com/felixdotgo/querybox.git
cd querybox
2

Build the Plugins

QueryBox’s database drivers are standalone executables that need to be built separately:
task build:plugins
This builds all plugins (MySQL, PostgreSQL, SQLite, Redis, ArangoDB) and places them in bin/plugins/.
The build process automatically detects your OS and architecture. Binaries are placed in bin/plugins/ with .exe extension on Windows.
Override the target platform using standard Go environment variables:
# Build Windows plugins from macOS/Linux
GOOS=windows GOARCH=amd64 task build:plugins

# Build Linux plugins from Windows/macOS
GOOS=linux GOARCH=amd64 task build:plugins

# Build macOS plugins (Intel)
GOOS=darwin GOARCH=amd64 task build:plugins

# Build macOS plugins (Apple Silicon)
GOOS=darwin GOARCH=arm64 task build:plugins
3

Build QueryBox

Build the production executable:
wails3 build
The application will be built to the bin/ directory:
  • Windows: bin/querybox.exe
  • macOS: bin/QueryBox.app
  • Linux: bin/querybox
Wails supports various build flags:
# Build with debug symbols
wails3 build -debug

# Build for specific platform
wails3 build -platform windows/amd64

# Clean build (removes cache)
wails3 build -clean
See wails3 build --help for all options.
4

Run QueryBox

Launch the application:
.\bin\querybox.exe

​
Development Mode

For development with hot-reload: 
wails3 dev
This starts QueryBox in development mode where both frontend and backend changes are automatically reloaded.
In development mode, plugins are loaded from bin/plugins/. If you modify plugin code, rebuild with task build:plugins and the running app will detect the changes within 2 seconds (after clicking the Rescan button in the Plugins window).

​
Plugin Installation Directory

At runtime, QueryBox manages plugins in two locations:
1

Bundled Plugins

Plugins in bin/plugins/ are bundled with the application. These are the built-in database drivers.
2

User Plugins

On first launch, QueryBox copies bundled plugins to a user-writable directory:
  • Windows: %APPDATA%\querybox\plugins
  • macOS: ~/Library/Application Support/querybox/plugins
  • Linux: $XDG_CONFIG_HOME/querybox/plugins (or ~/.config/querybox/plugins)
This allows you to:
  • Add custom database drivers
  • Override built-in plugins
  • Keep plugins across application updates
3

Plugin Priority

When plugins with the same name exist in both locations, the user directory takes precedence. This lets you customize drivers while preserving the originals.
Changes to plugin files require restarting QueryBox or clicking Rescan in the Plugins window to take effect.

​
Verifying Installation

Once installed, verify QueryBox is working correctly:
1

Launch the Application

Open QueryBox using your platform’s method (see Step 4 above).
2

Check Plugin Discovery

  1. From the main window menu, open Plugins window
  2. You should see all built-in plugins listed:
    • MySQL
    • PostgreSQL
    • SQLite
    • Redis
    • ArangoDB
Each plugin should display its version and capabilities.
3

Create a Test Connection

  1. Open Connections window
  2. Click New Connection
  3. Select a database type (SQLite is easiest for testing)
  4. Click Test Connection to verify the plugin responds correctly
If all plugins are discovered and test connections work, your installation is complete!

​
Troubleshooting

Symptoms: Plugins window is empty or missing expected driversSolutions:
  1. Verify plugins were built: ls bin/plugins/ should show executables
  2. Check file permissions: plugins must be executable (chmod +x bin/plugins/* on Linux/macOS)
  3. Click Rescan button in Plugins window
  4. Check logs for plugin probe failures (View → Developer → Toggle Developer Tools)
Common causes:
  • Missing Visual Studio Build Tools
  • WebView2 Runtime not installed
  • Antivirus blocking build output
Solutions:
  1. Install Visual Studio 2019+ or Build Tools for Visual Studio
  2. Download WebView2 Runtime from Microsoft
  3. Add bin/ directory to antivirus exclusions
Symptoms: “QueryBox.app is damaged and can’t be opened”Solution:
# Remove quarantine attribute
xattr -cr bin/QueryBox.app
Or go to System Preferences → Security & Privacy and allow the app.
Symptoms: Application won’t start or crashes immediatelySolution: Ensure WebKitGTK 4.0 development libraries are installed:
# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.0-37

# Fedora
sudo dnf install webkit2gtk3

​
Next Steps

Quick Start Guide

Connect to your first database and run queries

Plugin Development

Learn to create custom database drivers

Build docs developers (and LLMs) love

Get started for freeTalk to us