Contributing

Local setup

Docker is required. Start a local ClickHouse instance and run the full test suite:

make up      # start ClickHouse via Docker Compose
make test    # run all tests with -race
make down    # stop and remove containers

Make targets

Target	What it does
make up	Start ClickHouse (waits until healthy)
make down	Stop and remove containers
make test	Run the full test suite with -race and -count=1
make lint	Run golangci-lint
make staticcheck	Run staticcheck
make codegen	Regenerate column implementations and update license headers
make contributors	Rebuild contributors/list from git log

Running specific tests

# Run a single test
go test -race -count=1 -v ./tests/... -run TestBatchFlush

# Run against a specific ClickHouse version
CLICKHOUSE_VERSION=25.3 make test

# Run only the database/sql interface tests
go test -race -count=1 -v ./tests/std/...

# Run Go benchmark tests
go test -bench=. -benchmem ./benchmark/...

# Run a standalone benchmark program (most benchmarks are standalone executables)
go run benchmark/v2/read/main.go

Writing tests

• Integration tests live in tests/. They require a running ClickHouse (via make up) and use testcontainers-go for environment setup.
• Regression tests for bug fixes go in tests/issues/ named after the issue: issue_1234_test.go. Every bug fix should include one.
• New ClickHouse type support requires three things: a column implementation in lib/column/, a round-trip test in tests/, and an example in examples/clickhouse_api/.
• Do not mock driver.Conn or driver.Rows in tests — test against a real ClickHouse instance.

Code guidelines

See .claude/CLAUDE.md for Go idioms, API design principles, and workflow rules enforced in this repo.

Pull requests

• Open a PR against main. All changes require a PR — do not commit directly.
• Keep PRs focused. One logical change per PR.
• Ensure make lint and make test pass before requesting review.
• Reference the GitHub issue number in the PR description if one exists.
• Do not edit CHANGELOG.md — it is generated automatically during the release process.