clickhouse

README

ClickHouse

Golang SQL database client for ClickHouse.

Versions

There are two version of this client, v1 and v2, available as separate branches.

v1 is now in a state of a maintenance - we will only accept PRs for bug and security fixes.

Users should use v2 which is production ready and significantly faster than v1.

v2 has breaking changes for users migrating from v1. These were not properly tracked prior to this client being officially supported. We endeavour to track known differences here and resolve where possible.

Supported ClickHouse Versions

The client is tested against the currently supported versions of ClickHouse

Supported Golang Versions

Client Version	Golang Versions
=> 2.0 <= 2.2	1.17, 1.18
>= 2.3	1.18.4+, 1.19

Key features

• Uses ClickHouse native format for optimal performance. Utilises low level ch-go client for encoding/decoding and compression (versions >= 2.3.0).
• Supports native ClickHouse TCP client-server protocol
• Compatibility with database/sql (slower than native interface!)
• database/sql supports http protocol for transport. (Experimental)
• Marshal rows into structs (ScanStruct, Select)
• Unmarshal struct to row (AppendStruct)
• Connection pool
• Failover and load balancing
• Bulk write support (for database/sql use begin->prepare->(in loop exec)->commit)
• AsyncInsert
• Named and numeric placeholders support
• LZ4/ZSTD compression support
• External data

Support for the ClickHouse protocol advanced features using Context:

• Query ID
• Quota Key
• Settings
• OpenTelemetry
• Execution events:
  • Logs
  • Progress
  • Profile info
  • Profile events

database/sql interface

OpenDB

conn := clickhouse.OpenDB(&clickhouse.Options{
	Addr: []string{"127.0.0.1:9999"},
	Auth: clickhouse.Auth{
		Database: "default",
		Username: "default",
		Password: "",
	},
	TLS: &tls.Config{
		InsecureSkipVerify: true,
	},
	Settings: clickhouse.Settings{
		"max_execution_time": 60,
	},
	DialTimeout: 5 * time.Second,
	Compression: &clickhouse.Compression{
		clickhouse.CompressionLZ4,
	},
	Debug: true,
})
conn.SetMaxIdleConns(5)
conn.SetMaxOpenConns(10)
conn.SetConnMaxLifetime(time.Hour)

DSN

• hosts - comma-separated list of single address hosts for load-balancing and failover
• username/password - auth credentials
• database - select the current default database
• dial_timeout - a duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix such as "300ms", "1s". Valid time units are "ms", "s", "m".
• connection_open_strategy - round_robin/in_order (default in_order).
  • round_robin - choose a round-robin server from the set
  • in_order - first live server is chosen in specified order
• debug - enable debug output (boolean value)
• compress - enable lz4 compression (boolean value)

SSL/TLS parameters:

• secure - establish secure connection (default is false)
• skip_verify - skip certificate verification (default is false)

Example:

clickhouse://username:password@host1:9000,host2:9000/database?dial_timeout=200ms&max_execution_time=60

HTTP Support (Experimental)

The native format can be used over the HTTP protocol. This is useful in scenarios where users need to proxy traffic e.g. using ChProxy or via load balancers.

This can be achieved by modifying the DSN to specify the http protocol.

http://host1:9000,host2:9000/database?dial_timeout=200ms&max_execution_time=60

Alternatively, use OpenDB and specify the interface type.

conn := clickhouse.OpenDB(&clickhouse.Options{
	Addr: []string{"127.0.0.1:8123")},
	Auth: clickhouse.Auth{
		Database: "default",
		Username: "default",
		Password: "",
	},
	Settings: clickhouse.Settings{
		"max_execution_time": 60,
	},
	DialTimeout: 5 * time.Second,
	Compression: &clickhouse.Compression{
		Method: clickhouse.CompressionLZ4,
	},
	Interface: clickhouse.HttpInterface,
})

Compression

ZSTD/LZ4 compression is supported over native and http. This is performed at a block level and is only used for inserts.

If using Open via the std interface and specifying a DSN, compression can be enabled via the compress flag. Currently, this is a boolean flag which enables LZ4 compression.

Other compression methods will be added in future PRs.

TLS/SSL

At a low level all client connect methods (DSN/OpenDB/Open) will use the Go tls package to establish a secure connection. The client knows to use TLS if the Options struct contains a non-nil tls.Config pointer.

Setting secure in the DSN creates a minimal tls.Config struct with only the InsecureSkipVerify field set (either true or false). It is equivalent to this code:

conn := clickhouse.OpenDB(&clickhouse.Options{
	...
    TLS: &tls.Config{
            InsecureSkipVerify: false
	}
	...
    })

This minimal tls.Config is normally all that is necessary to connect to the secure native port (normally 9440) on a ClickHouse server. If the ClickHouse server does not have a valid certificate (expired, wrong host name, not signed by a publicly recognized root Certificate Authority), InsecureSkipVerify can be to true, but that is strongly discouraged.

If additional TLS parameters are necessary the application code should set the desired fields in the tls.Config struct. That can include specific cipher suites, forcing a particular TLS version (like 1.2 or 1.3), adding an internal CA certificate chain, adding a client certificate (and private key) if required by the ClickHouse server, and most of the other options that come with a more specialized security setup.

HTTPS (Experimental)

To connect using HTTPS either:

• Use https in your dsn string e.g.

  https://host1:9000,host2:9000/database?dial_timeout=200ms&max_execution_time=60
  

• Specify the interface type as HttpsInterface e.g.

conn := clickhouse.OpenDB(&clickhouse.Options{
	Addr: []string{"127.0.0.1:8443")},
	Auth: clickhouse.Auth{
		Database: "default",
		Username: "default",
		Password: "",
	},
	Interface: clickhouse.HttpsInterface,
})

Benchmark

V1 (READ)	V2 (READ) std	V2 (READ) native
1.218s	924.390ms	675.721ms

V1 (WRITE)	V2 (WRITE) std	V2 (WRITE) native	V2 (WRITE) by column
1.899s	1.177s	699.203ms	661.973ms

Install

go get -u github.com/ClickHouse/clickhouse-go/v2

Examples

native interface

• batch
• async insert
• batch struct
• columnar
• scan struct
• bind params

std database/sql interface

• batch
• async insert
• open db
• bind params

ClickHouse alternatives - ch-go

Versions of this client >=2.3.x utilise ch-go for their low level encoding/decoding. This low lever client provides a high performance columnar interface and should be used in performance critical use cases. This client provides more familar row orientated and database/sql semantics at the cost of some performance.

Both clients are supported by ClickHouse.

Third-party alternatives

• Database client/clients:

  • mailru/go-clickhouse (uses the HTTP protocol)
  • uptrace/go-clickhouse (uses the native TCP protocol with database/sql-like API)
  • Drivers with columnar interface:
    • vahid-sohrabloo/chconn

• Insert collectors:

  • KittenHouse
  • nikepan/clickhouse-bulk

Documentation

Index

• Constants
• Variables
• func Connector(opt *Options) driver.Connector
• func Context(parent context.Context, options ...QueryOption) context.Context
• func DateNamed(name string, value time.Time, scale TimeUnit) driver.NamedDateValue
• func Named(name string, value interface{}) driver.NamedValue
• func Open(opt *Options) (driver.Conn, error)
• func OpenDB(opt *Options) *sql.DB
• type ArraySet
• type Auth
• type Compression
• type CompressionMethod
  • func (c CompressionMethod) String() string
• type Conn
• type ConnOpenStrategy
• type Exception
• type GroupSet
• type HTTPReaderWriter
• type Log
• type OpError
  • func (e *OpError) Error() string
• type Options
  • func ParseDSN(dsn string) (*Options, error)
• type Pool
  • func NewPool[T any](fn func() T) Pool[T]
  • func (p *Pool[T]) Get() T
  • func (p *Pool[T]) Put(x T)
• type ProfileEvent
• type ProfileInfo
• type Progress
• type Protocol
  • func (p Protocol) String() string
• type QueryOption
  • func WithExternalTable(t ...*ext.Table) QueryOption
  • func WithLogs(fn func(*Log)) QueryOption
  • func WithProfileEvents(fn func([]ProfileEvent)) QueryOption
  • func WithProfileInfo(fn func(*ProfileInfo)) QueryOption
  • func WithProgress(fn func(*Progress)) QueryOption
  • func WithQueryID(queryID string) QueryOption
  • func WithQuotaKey(quotaKey string) QueryOption
  • func WithSettings(settings Settings) QueryOption
  • func WithSpan(span trace.SpanContext) QueryOption
  • func WithStdAsync(wait bool) QueryOption
• type QueryOptions
• type ServerVersion
• type Settings
• type TimeUnit

Constants

const (
	CompressionNone    = CompressionMethod(compress.None)
	CompressionLZ4     = CompressionMethod(compress.LZ4)
	CompressionZSTD    = CompressionMethod(compress.ZSTD)
	CompressionGZIP    = CompressionMethod(0x95)
	CompressionDeflate = CompressionMethod(0x96)
	CompressionBrotli  = CompressionMethod(0x97)
)

Variables

var (
	ErrBatchAlreadySent          = errors.New("clickhouse: batch has already been sent")
	ErrAcquireConnTimeout        = errors.New("clickhouse: acquire conn timeout. you can increase the number of max open conn or the dial timeout")
	ErrUnsupportedServerRevision = errors.New("clickhouse: unsupported server revision")
	ErrBindMixedParamsFormats    = errors.New("clickhouse [bind]: mixed named, numeric or positional parameters")
	ErrAcquireConnNoAddress      = errors.New("clickhouse: no valid address supplied")
)

Functions

func Connector

func Connector(opt *Options) driver.Connector

func Context

func Context(parent context.Context, options ...QueryOption) context.Context

func DateNamed

func DateNamed(name string, value time.Time, scale TimeUnit) driver.NamedDateValue

func Named

func Named(name string, value interface{}) driver.NamedValue

func Open

func Open(opt *Options) (driver.Conn, error)

func OpenDB

func OpenDB(opt *Options) *sql.DB

Types

type ArraySet

type ArraySet []interface{}

type Auth

type Auth struct {
	Database string
	Username string
	Password string
}

type Compression

type Compression struct {
	Method CompressionMethod
	// this only applies to zlib and brotli compression algorithms
	Level int
}

type CompressionMethod

type CompressionMethod byte

func (CompressionMethod) String

func (c CompressionMethod) String() string

type Conn

type Conn = driver.Conn

type ConnOpenStrategy

type ConnOpenStrategy uint8

const (
	ConnOpenInOrder ConnOpenStrategy = iota
	ConnOpenRoundRobin
)

type Exception

type Exception = proto.Exception

type GroupSet

type GroupSet struct {
	Value []interface{}
}

type HTTPReaderWriter

type HTTPReaderWriter struct {
	// contains filtered or unexported fields
}

type Log

type Log struct {
	Time      time.Time
	TimeMicro uint32
	Hostname  string
	QueryID   string
	ThreadID  uint64
	Priority  int8
	Source    string
	Text      string
}

type OpError

type OpError struct {
	Op         string
	ColumnName string
	Err        error
}

func (*OpError) Error

func (e *OpError) Error() string

type Options

type Options struct {
	Protocol Protocol

	TLS              *tls.Config
	Addr             []string
	Auth             Auth
	DialContext      func(ctx context.Context, addr string) (net.Conn, error)
	Debug            bool
	Debugf           func(format string, v ...interface{}) // only works when Debug is true
	Settings         Settings
	Compression      *Compression
	DialTimeout      time.Duration // default 1 second
	MaxOpenConns     int           // default MaxIdleConns + 5
	MaxIdleConns     int           // default 5
	ConnMaxLifetime  time.Duration // default 1 hour
	ConnOpenStrategy ConnOpenStrategy

	ReadTimeout time.Duration
	// contains filtered or unexported fields
}

func ParseDSN

func ParseDSN(dsn string) (*Options, error)

type Pool

type Pool[T any] struct {
	// contains filtered or unexported fields
}

func NewPool

func NewPool[T any](fn func() T) Pool[T]

func (*Pool[T]) Get

func (p *Pool[T]) Get() T

func (*Pool[T]) Put

func (p *Pool[T]) Put(x T)

type ProfileEvent

type ProfileEvent struct {
	Hostname    string
	CurrentTime time.Time
	ThreadID    uint64
	Type        string
	Name        string
	Value       int64
}

type ProfileInfo

type ProfileInfo = proto.ProfileInfo

type Progress

type Progress = proto.Progress

type Protocol

type Protocol int

const (
	Native Protocol = iota
	HTTP
)

func (Protocol) String

func (p Protocol) String() string

type QueryOption

type QueryOption func(*QueryOptions) error

func WithExternalTable

func WithExternalTable(t ...*ext.Table) QueryOption

func WithLogs

func WithLogs(fn func(*Log)) QueryOption

func WithProfileEvents

func WithProfileEvents(fn func([]ProfileEvent)) QueryOption

func WithProfileInfo

func WithProfileInfo(fn func(*ProfileInfo)) QueryOption

func WithProgress

func WithProgress(fn func(*Progress)) QueryOption

func WithQueryID

func WithQueryID(queryID string) QueryOption

func WithQuotaKey

func WithQuotaKey(quotaKey string) QueryOption

func WithSettings

func WithSettings(settings Settings) QueryOption

func WithSpan

func WithSpan(span trace.SpanContext) QueryOption

func WithStdAsync

func WithStdAsync(wait bool) QueryOption

type QueryOptions

type QueryOptions struct {
	// contains filtered or unexported fields
}

type ServerVersion

type ServerVersion = proto.ServerHandshake

type Settings

type Settings map[string]interface{}

type TimeUnit

type TimeUnit uint8

const (
	Seconds TimeUnit = iota
	MilliSeconds
	MicroSeconds
	NanoSeconds
)