Development

Development

Everything you need to build, test, and contribute to propq.

Requirements

• Go 1.24+
• make
• golangci-lint (for make lint)

Common commands

make build          # binary in build/propq
make build-all      # cross-compile all 7 platforms
make install        # install to $GOPATH/bin
make test           # go test ./...
make lint           # golangci-lint run ./...
make run ARGS="--sql \"SELECT 1\" -s local"   # build + run with args
make tidy           # go mod tidy
make update-deps    # go get -u ./... && go mod tidy

Project layout

cmd/propq/          entrypoint (main.go → app.Execute())
internal/app/       subcommands and glue (flags, run, skill, servers)
pkg/config/         TOML parsing, Connection struct, search logic
pkg/scanner/        SQL source: flag / file / pipe / editor
pkg/runner/         async executor: goroutine pool, semaphores, spinner, retry
pkg/display/        formatting: table, JSON, CSV, pager, summary
pkg/history/        query history store

The public API lives in pkg/ — anything there is importable by other projects, so keep it deliberate.

Data flow

SQL → Scanner → Config → Runner → Display → stdout
                    ↓
               Filter (regex + tags)
                    ↓
               Async executor (goroutines + per-server semaphore)
                    ↓
               Result collection (with optional streaming)

Code style

• gofmt clean, standard library first, existing patterns followed
• Comments in English, matching the codebase
• Add or update tests for behavior changes (see pkg/runner/spinner_test.go)
• Commit with Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore: — imperative mood, lowercase scope when useful (feat(display): ...)

Safety checklist (before submitting)

• Destructive SQL (DELETE/DROP/TRUNCATE/ALTER) covered by --force — never silently allowed
• No real credentials committed — config goes in propq.toml.example only, with placeholders
• Defaults stay fail-closed: new risky behavior must default to off
• --dry-run, --json, and quiet modes documented if behavior changed
• README updated if flags, config keys, or output changed

CI

The test workflow runs go test ./... against a real MySQL 8.0 service container.

Contributing

See CONTRIBUTING.md for the full guidelines: bug report format, feature request process, PR workflow, and the safety checklist. Bugs and feature requests go to issues; security issues go through the Security Policy. All contributors follow the Code of Conduct.