Create Your First Plugin

mkdir -p plugins/mydriver
cd plugins/mydriver

package main

import (
	"context"
	"fmt"

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

// myDriverPlugin implements the protobuf PluginServiceServer interface.
type myDriverPlugin struct {
	pluginpb.UnimplementedPluginServiceServer
}

func main() {
	plugin.ServeCLI(&myDriverPlugin{})
}

func (m *myDriverPlugin) Info(ctx context.Context, _ *pluginpb.PluginV1_InfoRequest) (*plugin.InfoResponse, error) {
	return &plugin.InfoResponse{
		Type:        plugin.TypeDriver,
		Name:        "mydriver",
		Version:     "0.1.0",
		Description: "My custom database driver",
		Url:         "https://example.com/mydriver",
		Author:      "Your Name",
		Capabilities: []string{"query"},
		Tags:        []string{"sql", "custom"},
		License:     "MIT",
	}, nil
}

func (m *myDriverPlugin) AuthForms(ctx context.Context, _ *plugin.AuthFormsRequest) (*plugin.AuthFormsResponse, error) {
	basic := plugin.AuthForm{
		Key:  "basic",
		Name: "Basic",
		Fields: []*plugin.AuthField{
			{Type: plugin.AuthFieldText, Name: "host", Label: "Host", Required: true, Placeholder: "127.0.0.1"},
			{Type: plugin.AuthFieldNumber, Name: "port", Label: "Port", Placeholder: "5432", Value: "5432"},
			{Type: plugin.AuthFieldText, Name: "user", Label: "User", Value: "root"},
			{Type: plugin.AuthFieldPassword, Name: "password", Label: "Password"},
			{Type: plugin.AuthFieldText, Name: "database", Label: "Database name"},
		},
	}
	return &plugin.AuthFormsResponse{Forms: map[string]*plugin.AuthForm{"basic": &basic}}, nil
}

func (m *myDriverPlugin) Exec(ctx context.Context, req *plugin.ExecRequest) (*plugin.ExecResponse, error) {
	// Example: return query as key-value for demonstration
	data := map[string]string{
		"query": req.Query,
		"host":  req.Connection["host"],
	}

	return &plugin.ExecResponse{
		Result: &plugin.ExecResult{
			Payload: &pluginpb.PluginV1_ExecResult_Kv{
				Kv: &plugin.KeyValueResult{
					Data: data,
				},
			},
		},
	}, nil
}

func (m *myDriverPlugin) Exec(ctx context.Context, req *plugin.ExecRequest) (*plugin.ExecResponse, error) {
	// Connect to your database using req.Connection
	dsn := buildDSN(req.Connection)
	db, err := sql.Open("yourdriver", dsn)
	if err != nil {
		return &plugin.ExecResponse{Error: fmt.Sprintf("connection error: %v", err)}, nil
	}
	defer db.Close()

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

	// Get column names
	cols, _ := rows.Columns()
	colMeta := make([]*plugin.Column, len(cols))
	for i, c := range cols {
		colMeta[i] = &plugin.Column{Name: c}
	}

	// Scan rows
	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]
		}
		rows.Scan(ptrs...)

		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
}

func (m *myDriverPlugin) TestConnection(ctx context.Context, req *plugin.TestConnectionRequest) (*plugin.TestConnectionResponse, error) {
	dsn := buildDSN(req.Connection)
	db, err := sql.Open("yourdriver", dsn)
	if err != nil {
		return &plugin.TestConnectionResponse{Ok: false, Message: fmt.Sprintf("open error: %v", err)}, nil
	}
	defer db.Close()

	if err := db.Ping(); err != nil {
		return &plugin.TestConnectionResponse{Ok: false, Message: fmt.Sprintf("ping error: %v", err)}, nil
	}

	return &plugin.TestConnectionResponse{Ok: true, Message: "Connection successful"}, nil
}

# From project root
task build:plugins

# Or manually
go build -o bin/plugins/mydriver plugins/mydriver/main.go

# Test info command
./bin/plugins/mydriver info

# Test authforms command
./bin/plugins/mydriver authforms

# Test exec command (requires JSON on stdin)
echo '{"connection":{"host":"localhost"},"query":"SELECT 1"}' | ./bin/plugins/mydriver exec

# Test connection
echo '{"connection":{"host":"localhost","user":"root"}}' | ./bin/plugins/mydriver test-connection

cp bin/plugins/mydriver ~/.config/querybox/plugins/  # Linux
# Or let QueryBox discover it from bin/plugins/