Development Guide

Prerequisites

• Go 1.24+
• Qdrant (local Docker or Cloud)
• buf (optional, for proto regeneration)

Setup

Clone and Setup

git clone https://github.com/srimon12/qql-go.git cd qql-go go mod download

Build

Build Binary

go build -o qql-go ./cmd/qql-go

Debug build with source info:

Debug Build

go build -ldflags "-X main.Version=dev" -o qql-go ./cmd/qql-go

Test

Run Tests

All testsSection titled “All tests”
go test ./...
Specific packageSection titled “Specific package”
go test ./internal/parser/... go test ./internal/filters/... go test ./pkg/qql/...
VerboseSection titled “Verbose”
go test -v ./internal/parser/...
With coverageSection titled “With coverage”
go test -cover ./... go test -coverprofile=coverage.out ./... go tool cover -html=coverage.out

Lint

Lint

gofmt -l . go vet ./...

Protobuf Regeneration

Regenerate Protobuf

buf generate

Requires buf and the Go protobuf plugins. Generated files go to gen/.

Run

Run qql-go

After buildSection titled “After build”
./qql-go version
Go run (no build step)Section titled “Go run (no build step)”
go run ./cmd/qql-go version go run ./cmd/qql-go connect --url http://localhost:6334 go run ./cmd/qql-go exec "SHOW COLLECTIONS"

Dev Workflow

1. Edit code
2. go build -o qql-go ./cmd/qql-go
3. ./qql-go exec "<statement>"
4. go test ./...

Integration Tests

Some tests require a running Qdrant instance. Start one:

Start Qdrant

docker run -p 6334:6334 qdrant/qdrant

The test suite expects Qdrant on localhost:6334 unless overridden by QDRANT_URL.

Release Validation

Before tagging a release:

Release Validation

go run docs/dev_tasks.go release-validate --version <version>

This checks:

1. Version sync (VERSION file, commands.go, CHANGELOG)
2. Quality checks (gofmt, go vet, go test, go build)
3. Binary build
4. Binary version output

VS Code Setup

Recommended extensions:

• Go (golang.go) — language server, test runner
• Error Lens — inline error display
• proto3 — syntax highlighting for proto/qql.proto

.vscode/settings.json:

{
  "go.formatTool": "gofmt",
  "go.lintTool": "golangci-lint",
  "go.testOnSave": false
}