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.

​
Overview

The exec command executes a user query against a data source and returns structured results. Supports SQL databases, document stores, and key-value stores.

​
Command Invocation

<plugin-binary> exec
Stdin: JSON-encoded ExecRequest object Stdout: JSON-encoded ExecResponse object Timeout: 30 seconds Required: Yes - all driver plugins must implement this command

​
Request Parameters

​
Response Structure

​
result
ExecResult
Contains exactly one of: sql, document, or kv payload
​
error
string
Error message if execution failed. Empty string indicates success.

​
ExecResult Payloads

​
SqlResult (for relational databases)

​
result.sql.columns
Column[]
required
Array of column metadata objects:
  • name (string, required): Column name
  • type (string, optional): Database type (e.g., “varchar”, “int”)
​
result.sql.rows
Row[]
required
Array of row objects, each containing:
  • values (string[]): Array of string-formatted cell values

​
DocumentResult (for document stores)

​
result.document.documents
object[]
required
Array of JSON objects representing documents

​
KeyValueResult (for key-value stores)

​
result.kv.data
object
required
String-to-string map of key-value pairs

​
Example Implementation

From plugins/mysql/main.go: 
func (m *mysqlPlugin) Exec(ctx context.Context, req *plugin.ExecRequest) (*plugin.ExecResponse, error) {
    // Handle explain-query capability
    if req.Options != nil {
        if v, ok := req.Options["explain-query"]; ok && v == "yes" {
            req.Query = "EXPLAIN " + req.Query
        }
    }
    
    dsn, err := buildDSN(req.Connection)
    if err != nil {
        return &plugin.ExecResponse{Error: fmt.Sprintf("invalid connection: %v", err)}, nil
    }
    
    db, err := sql.Open("mysql", dsn)
    if err != nil {
        return &plugin.ExecResponse{Error: fmt.Sprintf("open error: %v", err)}, nil
    }
    defer db.Close()

    rows, err := db.Query(req.Query)
    if err != nil {
        return &plugin.ExecResponse{Error: fmt.Sprintf("query error: %v", err)}, nil
    }
    defer rows.Close()

    cols, err := rows.Columns()
    if err != nil {
        return &plugin.ExecResponse{Error: fmt.Sprintf("cols error: %v", err)}, nil
    }

    // Prepare column metadata
    colMeta := make([]*plugin.Column, len(cols))
    for i, c := range cols {
        colMeta[i] = &plugin.Column{Name: c}
    }

    var rowResults []*plugin.Row
    for rows.Next() {
        vals := make([]interface{}, len(cols))
        ptrs := make([]interface{}, len(cols))
        for i := range vals {
            ptrs[i] = &vals[i]
        }
        if err := rows.Scan(ptrs...); err != nil {
            return &plugin.ExecResponse{Error: fmt.Sprintf("scan error: %v", err)}, nil
        }
        strs := make([]string, len(cols))
        for i, v := range vals {
            strs[i] = plugin.FormatSQLValue(v)
        }
        rowResults = append(rowResults, &plugin.Row{Values: strs})
    }

    return &plugin.ExecResponse{
        Result: &plugin.ExecResult{
            Payload: &pluginpb.PluginV1_ExecResult_Sql{
                Sql: &plugin.SqlResult{
                    Columns: colMeta,
                    Rows:    rowResults,
                },
            },
        },
    }, nil
}

​
Request Format (stdin)

{
  "connection": {
    "credential_blob": "{\"form\":\"basic\",\"values\":{\"host\":\"127.0.0.1\",\"port\":\"3306\",\"user\":\"root\",\"password\":\"secret\",\"database\":\"mydb\"}}"
  },
  "query": "SELECT * FROM users LIMIT 10",
  "options": {}
}

​
Response Format (stdout)

​
SQL Result Example

{
  "result": {
    "sql": {
      "columns": [
        {"name": "id", "type": "int"},
        {"name": "email", "type": "varchar"}
      ],
      "rows": [
        {"values": ["1", "alice@example.com"]},
        {"values": ["2", "bob@example.com"]}
      ]
    }
  },
  "error": ""
}

​
Error Response Example

{
  "error": "query error: Unknown column 'invalid_field' in 'field list'"
}

​
Value Formatting

Use plugin.FormatSQLValue() helper to convert database/sql scan results:
  • nil values → empty string ""
  • []byte with valid UTF-8 → string conversion
  • []byte with binary data → hex format "0x...”
  • Other types → fmt.Sprintf("%v", value)

​
Error Handling

  • Return errors in the error field of the response, not via stderr or exit code
  • The host displays error messages directly to the user
  • Empty error field indicates success
  • The result field should be omitted or empty when an error occurs

​
Notes

  • All row values must be strings - the plugin is responsible for formatting
  • Binary data should be hex-encoded to avoid invalid JSON
  • The host does not parse or interpret query syntax - that’s plugin-specific

Build docs developers (and LLMs) love

Get started for freeTalk to us