Modernize library: context support, connection pooling, compression, …

[peterborodatyy]

Summary

Modernize the library to align with the current ClickHouse HTTP API, follow Go style guidelines, and add CI/CD.

API Improvements

• context.Context support on all public methods (Exec, Iter, Ping, CheckCtx) for cancellation and timeouts
• Connection pooling — reuse http.Client with pooled connections instead of creating one per request
• Gzip compression via HTTPTransport{Compression: true}
• HTTP status code checking — non-200 responses return structured *DBError or descriptive errors
• Database selection via X-ClickHouse-Database header and ?database= URL param
• Query/Session ID support (Query.QueryID, Query.SessionID) for tracking, cancellation, and session persistence
• Per-query settings via Query.SetSetting() (e.g., max_rows_to_read, max_execution_time)
• NewConnWithOptions constructor accepting ConnOptions{Host, User, Password, Database}

Type System

• Uint unmarshal: uint, uint8, uint16, uint32, uint64
• Bool unmarshal: 1/0/true/false
• Nullable: \N handling with pointer types (*string, *int64, *float64)
• Date format: unmarshal tries DateTime first, then Date
• DateTime marshal: time.Time with non-zero time marshals as 2006-01-02 15:04:05

Bug Fixes

• Multiline error parsing — (?s) regex flag for errors spanning multiple lines
• Error regex compiled once at package level (regexp.MustCompile)

Go Style Refactoring

• Naming: HttpTransport → HTTPTransport, DbError → DBError, prepareHttp → prepareHTTP (Go initialisms must be all-caps)
• interface{} → any throughout (Go 1.18+)
• Doc comments on all exported types and functions
• doc.go with package-level documentation and usage example
• Compile-time interface check: var _ Transport = (*HTTPTransport)(nil)
• Error strings lowercased per Go convention
• Extracted helpers: normalizeHost(), buildMultipartPostRequest(), buildSimplePostRequest(), unmarshalIntSlice(), unmarshalStringSlice(), unmarshalArray() to reduce function complexity
• Eliminated unsafe intermediate type assertions in unmarshal — use direct two-value assignment
• http.MethodGet/http.MethodPost instead of string literals
• sync.Mutex → sync.RWMutex for Cluster read operations
• Table-driven tests, descriptive test names, assert.NoError/assert.ErrorAs/assert.Empty
• Proper import grouping (stdlib, then third-party)
• Preallocated slices where size is known

Build & CI

• Go modules: added go.mod (Go 1.21+), removed GOPATH dependency
• Removed .travis.yml (targeted Go 1.3–1.9)
• Replaced deprecated io/ioutil → io, strings.Replace → strings.ReplaceAll, strings.Index → strings.HasPrefix
• GitHub Actions — Unit Tests: runs on Go 1.21/1.22/1.23 with race detector and coverage
• GitHub Actions — Integration Tests: spins up clickhouse/clickhouse-server:latest and runs 26 integration tests
• GitHub Actions — Release: auto-creates a GitHub release with version bump on push to master

Integration Tests (26 tests against real ClickHouse)

• Ping, context cancellation, timeouts
• SELECT with all types (int, uint, float, string, bool, DateTime, Date, Nullable, arrays)
• CREATE TABLE → INSERT → SELECT round-trip
• Placeholder substitution (int and string)
• Database selection via ConnOptions
• Query ID tracking (verified via system.query_log)
• Session ID (SET + getSetting across same session)
• Per-query settings enforcement (max_rows_to_read)
• Gzip compression
• External data tables
• Cluster health checks
• Special character escaping
• Error handling (bad SQL, nonexistent tables)

Docs

• README updated with all new features, correct API names, current examples
• CONTRIBUTING.md with setup, testing, code style, and PR guidelines

Test plan

• 59 unit tests pass with -race flag
• 26 integration tests pass against real ClickHouse
• go vet clean
• gofmt clean
• Verify GitHub Actions workflows trigger on merge
• Smoke test against a production ClickHouse instance