Plugin System

Plugins are single-shot executables that communicate via JSON over stdin/stdout. Any language can implement a plugin — no SDKs or bindings required. The host spawns a subprocess per request, sends input, reads output, and the plugin exits.

Overview

Host service: services/pluginmgr/pluginmgr.go
Plugin SDK: pkg/plugin (ServeCLI helper + protobuf aliases)
Proto contract: contracts/plugin/v1/plugin.proto → generated rpc/contracts/plugin/v1 (pluginpb)

Plugins run as isolated subprocesses with no persistent state. This keeps the system simple and provides strong fault isolation.

CLI Commands

Each plugin implements a command-line interface with these commands:

Command	Stdin	Stdout	Timeout	Required
`info`	—	`{name, version, description, type, ...}`	2s	✓
`exec`	`{connection, query, options?}`	`{result, error}`	30s	✓
`authforms`	—	Auth form definitions	30s	✓
`connection-tree`	`{connection}`	`{nodes: [...]}`	30s	optional
`test-connection`	`{connection}`	`{ok: bool, message: string}`	15s	optional

The `info` Command

Returns plugin metadata used for discovery and UI rendering:

{
  "name": "mysql",
  "version": "1.0.0",
  "description": "MySQL / MariaDB driver",
  "type": "DRIVER",
  "url": "https://...",
  "author": "...",
  "license": "MIT",
  "icon_url": "...",
  "capabilities": ["explain-query"],
  "tags": ["sql", "relational"],
  "contact": "...",
  "metadata": {},
  "settings": {}
}

Hosts ignore unknown fields for forward compatibility. Older plugins emitting a numeric type are also accepted.

The `exec` Command

Executes queries and returns structured results. The response contains exactly one result type:

Field	Type	Use
`sql`	`SqlResult{columns, rows}`	Query results with column names
`document`	`DocumentResult{documents}`	JSON document store results
`kv`	`KvResult{entries}`	Key-value results (also used as raw-text wrapper)

Plugins that return raw strings are automatically wrapped in kv format by the host.

Example exec request:

{
  "connection": {
    "host": "localhost",
    "port": 3306,
    "username": "root",
    "password": "...",
    "database": "mydb"
  },
  "query": "SELECT * FROM users LIMIT 10",
  "options": {
    "explain-query": "yes"
  }
}

Example exec response:

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

The `authforms` Command

Returns structured form definitions for connection authentication:

{
  "forms": [
    {
      "name": "basic",
      "label": "Standard Connection",
      "fields": [
        {
          "name": "host",
          "label": "Host",
          "type": "text",
          "required": true,
          "default": "localhost"
        },
        {
          "name": "password",
          "label": "Password",
          "type": "password",
          "required": false
        }
      ]
    }
  ]
}

Plugins that don’t implement authforms fall back to a single DSN/credential text input.

The frontend renders one tab per form. On submit, form values are serialized as JSON and passed to ConnectionService.CreateConnection.

The `connection-tree` Command

Returns hierarchical database structure for browsing:

{
  "nodes": [
    {
      "id": "db:mydb",
      "label": "mydb",
      "type": "database",
      "children": [
        {
          "id": "table:users",
          "label": "users",
          "type": "table",
          "actions": [
            { "label": "Browse Rows", "query": "SELECT * FROM users LIMIT 100" },
            { "label": "Show Schema", "query": "DESCRIBE users" }
          ]
        }
      ],
      "actions": [
        { "label": "Show Tables", "query": "SHOW TABLES" }
      ]
    }
  ]
}

When a user activates a node action, the frontend calls PluginManager.ExecTreeAction(name, conn, actionQuery, options), which delegates to ExecPlugin.

Show Connection tree structure

Each node represents a database object (database, schema, table, column, etc.) and can:

Have child nodes for hierarchical browsing
Provide actions that generate queries
Include metadata for icon rendering or custom UI

The tree structure is plugin-defined — NoSQL databases might use different hierarchies than relational databases.

The `test-connection` Command

Validates connection parameters without persistence:

{
  "connection": {
    "host": "localhost",
    "port": 3306,
    "username": "root",
    "password": "..."
  }
}

Response:

{
  "ok": true,
  "message": "Connected successfully"
}

Test connection uses a 15s timeout (shorter than the standard 30s) to provide faster feedback during connection setup.

Capabilities

Explain-Query Capability

Plugins can advertise "explain-query" in their capabilities array. When present:

The host renders an Explain button in the result workspace
Clicking it reruns the current query with options: {"explain-query": "yes"}
The plugin interprets the flag (e.g., prepending EXPLAIN to SQL)
Results are rendered in a separate Explain tab

{
  "name": "postgresql",
  "capabilities": ["explain-query"],
  ...
}

The plugin is responsible for implementing the explain logic. The host only passes the option flag.

Plugin Discovery

QueryBox discovers plugins from two locations:

Primary: User Directory

User-writable config directory for custom plugins:

Linux: $XDG_CONFIG_HOME/querybox/plugins
Windows: %APPDATA%\querybox\plugins
macOS: ~/Library/Application Support/querybox/plugins

On startup, QueryBox copies bundled plugins from bin/plugins to this directory, overwriting existing files. This keeps bundled drivers up-to-date while allowing custom plugins.

Fallback: Bundle Directory

Traditional bin/plugins next to the executable:

Inside .app bundles
Installers
wails3 dev working directory

Plugin discovery happens once at startup. Adding, removing, or replacing a plugin binary requires restarting the application to take effect.

Discovery Process

PluginManager.Rescan() triggers an immediate synchronous re-probe if a manual refresh is needed without a full restart. This is exposed as a button in the Plugins window.

Reference Plugins

QueryBox ships with these reference implementations:

Plugin	Commands	Capabilities	Notes
`mysql`	exec, authforms, connection-tree, test-connection	explain-query	TLS support
`postgresql`	exec, authforms, connection-tree, test-connection	explain-query
`sqlite`	exec, authforms, connection-tree, test-connection	explain-query	Two auth forms: local file (`modernc.org/sqlite`) + Turso Cloud (`go-libsql`)
`redis`	exec, authforms	—	Two auth forms: basic (host/port/password/db) + URL string
`arangodb`	exec, authforms	—	Multi-model (documents, graphs); basic auth form

Writing a Plugin

Quick Start

Create plugins/<name>/main.go (package main)
Import pkg/plugin and call plugin.ServeCLI() in main()
Implement handler functions for each command
Build: task build:plugins → binary lands in bin/plugins/<name> (.exe on Windows)
Drop binary into bin/plugins/ — the host discovers it automatically

Minimal Example

package main

import (
    "github.com/querybox/querybox/pkg/plugin"
    pluginpb "github.com/querybox/querybox/rpc/contracts/plugin/v1"
)

func main() {
    plugin.ServeCLI(plugin.Handlers{
        Info: func() (*pluginpb.InfoResponse, error) {
            return &pluginpb.InfoResponse{
                Name:        "mydb",
                Version:     "1.0.0",
                Description: "My Database Driver",
                Type:        pluginpb.PluginType_DRIVER,
            }, nil
        },
        Exec: func(req *pluginpb.ExecRequest) (*pluginpb.ExecResponse, error) {
            // Execute query and return results
            return &pluginpb.ExecResponse{
                Result: &pluginpb.ExecResponse_Kv{
                    Kv: &pluginpb.KvResult{
                        Entries: []*pluginpb.KvEntry{
                            {Key: "result", Value: "Hello from plugin"},
                        },
                    },
                },
            }, nil
        },
        AuthForms: func() (*pluginpb.AuthFormsResponse, error) {
            // Return form definitions
            return &pluginpb.AuthFormsResponse{Forms: []*pluginpb.AuthForm{...}}, nil
        },
    })
}

See plugins/template/main.go in the repository for a complete example with all optional fields.

Design Benefits

Language Agnostic

Any language can implement a plugin:

Go (reference implementations)
Python, Node.js, Rust, etc.
Just read JSON from stdin, write JSON to stdout

Crash Isolation

Plugin failures are isolated:

Host never crashes due to plugin bugs
Failed queries return error responses
Next execution spawns a fresh process

Simple Development Workflow

Edit plugin code
Rebuild binary
Restart QueryBox (or click Rescan)
Test immediately

No complex build system or hot-reload required.

No IPC Complexity

Stdin/stdout is the universal interface:

No sockets or named pipes
No serialization library dependencies
Standard JSON everywhere

Show Why not use persistent plugins?

Persistent plugins would require:

IPC protocol design and versioning
Connection pooling and lifecycle management
Crash detection and restart logic
State synchronization between host and plugin

For typical query workloads (1-30 seconds), subprocess spawn overhead (10-50ms) is negligible. The simplicity and isolation benefits far outweigh the marginal performance cost.

Get Started

Core Concepts

User Guide

Supported Databases

Overview

CLI Commands

The `info` Command

The `exec` Command

Example exec request:

Example exec response:

The `authforms` Command

The `connection-tree` Command

The `test-connection` Command

Capabilities

Explain-Query Capability

Plugin Discovery

Primary: User Directory

Fallback: Bundle Directory

Discovery Process

Reference Plugins

Writing a Plugin

Quick Start

Minimal Example

Design Benefits

Language Agnostic

Crash Isolation

Simple Development Workflow

No IPC Complexity

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guide

Supported Databases

Documentation Index

​Overview

​CLI Commands

​The info Command

​The exec Command

​Example exec request:

​Example exec response:

​The authforms Command

​The connection-tree Command

​The test-connection Command

​Capabilities

​Explain-Query Capability

​Plugin Discovery

​Primary: User Directory

​Fallback: Bundle Directory

​Discovery Process

​Reference Plugins

​Writing a Plugin

​Quick Start

​Minimal Example

​Design Benefits

​Language Agnostic

​Crash Isolation

​Simple Development Workflow

​No IPC Complexity

Build docs developers (and LLMs) love

Overview

CLI Commands

The `info` Command

The `exec` Command

Example exec request:

Example exec response:

The `authforms` Command

The `connection-tree` Command

The `test-connection` Command

Capabilities

Explain-Query Capability

Plugin Discovery

Primary: User Directory

Fallback: Bundle Directory

Discovery Process

Reference Plugins

Writing a Plugin

Quick Start

Minimal Example

Design Benefits

Language Agnostic

Crash Isolation

Simple Development Workflow

No IPC Complexity