Quick Start - QueryBox

Overview

This guide will walk you through:

Launching QueryBox for the first time
Creating your first database connection
Exploring database objects
Executing your first query
Understanding query results

This quickstart assumes you’ve already installed QueryBox. If not, complete the installation first.

Launch QueryBox

Start the application using your platform’s method:

Windows
macOS
Linux

Double-click querybox.exe or run from Command Prompt:

querybox.exe

Double-click QueryBox.app or run from Terminal:

open QueryBox.app

Run the executable:

./querybox

The main query workspace window will open, along with a connections management window.

Create Your First Connection

Let’s create a connection using SQLite, which doesn’t require a separate database server.

Open Connections Window

If the connections window isn’t visible:

Click the Connections menu item, or
Use the keyboard shortcut to open it

The connections window displays all saved database connections.

Click New Connection

Click the New Connection button to open the connection creation dialog.

Select Database Type

From the database type dropdown, select SQLite.You’ll see two authentication options:

Local File - For local SQLite database files
Turso Cloud - For Turso cloud-hosted SQLite databases

Select Local File for this quickstart.

Configure Connection

Fill in the connection details:

name

string

required

A friendly name for your connection (e.g., “My Test Database”)

path

string

required

Path to your SQLite database file. You can:

Browse to an existing .db or .sqlite file
Enter a path to create a new database
Use :memory: for an in-memory database (lost when connection closes)

Example:

Name: Test Database
Path: /Users/yourname/test.db

For a quick test, use :memory: as the path. This creates a temporary database perfect for experimentation.

Test the Connection

Before saving, click Test Connection to verify the SQLite plugin can access the database.You should see a green checkmark with “Connection successful” message.

If testing fails:

Verify the file path is correct and accessible
Check file permissions (read/write access required)
Ensure the directory exists for new databases

Save Connection

Click Save or Create Connection to store the connection.Your new connection appears in the connections list. QueryBox has:

Stored connection metadata in its internal SQLite database
Saved credentials securely using your OS keyring (or encrypted fallback)
Emitted a connection:created event to update the UI

Explore Database Objects

Now that you have a connection, let’s explore its structure using the connection tree.

Open Connection Tree

In the main query window, you’ll see a sidebar with a tree view. Select your newly created connection from the dropdown at the top.The plugin will execute the connection-tree command to fetch the database structure.

Browse Database Objects

For SQLite, the tree shows:

📁 Test Database
├── 📊 Tables
│   └── (any existing tables)
├── 🔍 Indexes
└── 👁️ Views

Click the arrows to expand and collapse sections.

If you used :memory: or a new database file, the tree will be empty initially. We’ll create tables in the next section.

Use Node Actions

Some tree nodes have action buttons. For example:

Clicking a table shows its columns
Right-clicking may show actions like “Show CREATE TABLE” or “Browse Data”

These actions send queries to the database automatically.

Execute Your First Query

Let’s create a sample table and run some queries.

Create a Table

In the query editor (main text area), enter:

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

Click the Execute button or press Ctrl+Enter (Windows/Linux) or Cmd+Enter (macOS).

What happens behind the scenes

When you execute a query:

QueryBox calls PluginManager.ExecPlugin()
The SQLite plugin process is spawned

Your query is sent via stdin as JSON:

{
  "connection": {"path": "/path/to/test.db"},
  "query": "CREATE TABLE users ...",
  "options": {}
}

The plugin executes the query and returns results via stdout
The plugin process exits
Results are displayed in the results pane

Expected result: “Query executed successfully” or similar message.

Insert Sample Data

Add some test data:

INSERT INTO users (name, email) VALUES
  ('Alice Smith', 'alice@example.com'),
  ('Bob Jones', 'bob@example.com'),
  ('Carol White', 'carol@example.com');

Execute the query. You should see “3 rows affected” or similar.

Query the Data

Now retrieve the data:

SELECT * FROM users ORDER BY created_at DESC;

Execute the query. The results pane displays a formatted table:

id	name	email	created_at
3	Carol White	carol@example.com	2026-03-01 10:30:15
2	Bob Jones	bob@example.com	2026-03-01 10:30:15
1	Alice Smith	alice@example.com	2026-03-01 10:30:15

Refresh Connection Tree

After creating tables, refresh the connection tree (click the refresh icon) to see your new users table appear under the Tables section.Expand the users table to see its columns:

📊 users
├── 🔑 id (INTEGER)
├── 📝 name (TEXT)
├── 📧 email (TEXT)
└── 📅 created_at (TEXT)

Congratulations! You’ve successfully created a connection, explored database objects, and executed queries.

Understanding Query Results

QueryBox displays results in different formats depending on the query type and database:

SQL Results
Document Results
Key-Value Results

SELECT queries return SqlResult with columns and rows:

{
  "columns": ["id", "name", "email"],
  "rows": [
    [1, "Alice Smith", "alice@example.com"],
    [2, "Bob Jones", "bob@example.com"]
  ]
}

Displayed as an interactive table with:

Column headers
Sortable columns (click header to sort)
Scrollable rows
Copy to clipboard functionality

Document databases (like ArangoDB) return DocumentResult:

{
  "documents": [
    {"_id": "users/123", "name": "Alice"},
    {"_id": "users/456", "name": "Bob"}
  ]
}

Displayed as formatted JSON with syntax highlighting.

Redis and other KV stores return KvResult:

{
  "entries": [
    {"key": "user:1:name", "value": "Alice"},
    {"key": "user:2:name", "value": "Bob"}
  ]
}

Displayed as key-value pairs.

Try Other Database Types

Now that you understand the basics, try connecting to other databases:

MySQL

Required info:

Host (e.g., localhost:3306)
Database name
Username and password
Optional: TLS/SSL settings

Sample query:

SHOW TABLES;

PostgreSQL

Required info:

Host (e.g., localhost:5432)
Database name
Username and password
Optional: SSL mode

Sample query:

SELECT * FROM information_schema.tables
WHERE table_schema = 'public';

Redis

Required info:

Host and port (e.g., localhost:6379)
Password (if configured)
Database number (0-15)

Sample commands:

SET mykey "Hello QueryBox"
GET mykey
KEYS *

ArangoDB

Required info:

URL (e.g., http://localhost:8529)
Database name
Username and password

Sample query (AQL):

FOR doc IN users
  RETURN doc

Advanced Features

EXPLAIN Queries

For databases that support it (MySQL, PostgreSQL, SQLite), use the Explain button to analyze query execution plans:

Write a Query

SELECT * FROM users WHERE email LIKE '%example.com';

Click Explain

Instead of Execute, click the Explain button.The plugin automatically adds EXPLAIN to your query and shows the execution plan.

Analyze Results

Review the query plan to identify:

Which indexes are used
Scan types (full table scan vs. index scan)
Estimated row counts
Optimization opportunities

The Explain button only appears for plugins that advertise the explain-query capability in their metadata.

Multiple Connections

QueryBox supports multiple concurrent connections:

Create connections to different databases (even different types)
Switch between them using the connection dropdown
Each connection maintains its own tree view and state
Credentials are managed securely and independently

Plugin Management

View and manage installed plugins:

Open Plugins Window

From the menu, select Plugins or use the keyboard shortcut.

View Plugin Information

Each plugin displays:

Name and version
Description and author
Capabilities (connection-tree, test-connection, explain-query)
License and documentation links

Rescan Plugins

If you add new plugin executables to bin/plugins/ or the user plugin directory, click Rescan to discover them without restarting.

Best Practices

Connection Naming

Use descriptive names that include:

Environment (dev, staging, production)
Database purpose
Server location

Examples:

“Production MySQL - Users DB”
“Dev PostgreSQL - Local”
“Analytics Redis - Cache”

Credential Security

QueryBox stores credentials in your OS keyring when available
Never commit the QueryBox data directory to version control
Use read-only credentials for production databases
Test connections before saving to catch authentication issues early

Query Organization

Save frequently used queries as snippets (feature coming soon)
Use comments to document complex queries
Test queries on development databases first
Use transactions for multi-statement operations

Performance

Use LIMIT clauses for large result sets
Each query spawns a new plugin process (intentional isolation)
Connection tree queries have 30s timeout
Test connections have 15s timeout for faster feedback

Troubleshooting

Connection test fails

Common causes:

Incorrect host, port, or credentials
Firewall blocking the connection
Database server not running
SSL/TLS configuration mismatch

Debug steps:

Verify credentials in a different client (e.g., mysql CLI)
Check network connectivity: ping <host> or telnet <host> <port>
Review error message from the plugin
Check database server logs

Query timeout

Symptoms: “context deadline exceeded” after 30 secondsSolutions:

Optimize the query (add WHERE clauses, indexes)
Use LIMIT to reduce result set size
For long-running queries, increase timeout (feature coming soon)
Consider running expensive queries directly on the database server

Connection tree empty

Possible reasons:

New/empty database (expected)
Plugin doesn’t implement connection-tree command
Insufficient permissions to query metadata tables

Solutions:

Create some tables and refresh the tree
Check if the plugin supports connection trees in Plugins window
Verify database user has metadata query permissions

Plugin not found

Symptoms: “Plugin not found” when creating connectionSolutions:

Open Plugins window and verify plugin is listed
Click Rescan to re-probe plugins
Check that plugin executable exists in bin/plugins/
Verify file is executable (Linux/macOS: chmod +x)
Rebuild plugins: task build:plugins

Next Steps

Connection Management

Learn advanced connection features and credential management

Plugin System

Understand how plugins work and create your own database drivers

Query Workspace

Master the query editor and result viewing features

Security Model

Deep dive into QueryBox’s security architecture

​Overview

​Launch QueryBox

​Create Your First Connection

​Explore Database Objects

​Execute Your First Query

​Understanding Query Results

​Try Other Database Types

MySQL

PostgreSQL

Redis

ArangoDB

​Advanced Features

​EXPLAIN Queries

​Multiple Connections

​Plugin Management

​Best Practices

​Troubleshooting

​Next Steps

Connection Management

Plugin System

Query Workspace

Security Model

Overview

Launch QueryBox

Create Your First Connection

Explore Database Objects

Execute Your First Query

Understanding Query Results

Try Other Database Types

Advanced Features

EXPLAIN Queries

Multiple Connections

Plugin Management

Best Practices

Troubleshooting

Next Steps