v2 – github.com/ClickHouse/clickhouse-go/v2 Index | Files | Directories

package clickhouse

import "github.com/ClickHouse/clickhouse-go/v2"

Index

Constants

const (
	CompressionNone    = CompressionMethod(compress.None)
	CompressionLZ4     = CompressionMethod(compress.LZ4)
	CompressionLZ4HC   = CompressionMethod(compress.LZ4HC)
	CompressionZSTD    = CompressionMethod(compress.ZSTD)
	CompressionGZIP    = CompressionMethod(0x95)
	CompressionDeflate = CompressionMethod(0x96)
	CompressionBrotli  = CompressionMethod(0x97)
)
const (
	ClientVersionMajor       = 2
	ClientVersionMinor       = 34
	ClientVersionPatch       = 0
	ClientTCPProtocolVersion = proto.DBMS_TCP_PROTOCOL_VERSION
)
const ClientName = "clickhouse-go"

Variables

var (
	ErrBatchInvalid              = errors.New("clickhouse: batch is invalid. check appended data is correct")
	ErrBatchAlreadySent          = errors.New("clickhouse: batch has already been sent")
	ErrBatchNotSent              = errors.New("clickhouse: invalid retry, batch not sent yet")
	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")
	ErrServerUnexpectedData      = errors.New("code: 101, message: Unexpected packet Data received from client")
)
var (
	ErrExpectedStringValueInNamedValueForQueryParameter = errors.New("expected string value in NamedValue for query parameter")
)

Functions

func Connector

func Connector(opt *Options) driver.Connector

func Context

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

Context returns a derived context with the given ClickHouse QueryOptions. Existing QueryOptions will be overwritten per option if present. The QueryOptions Settings map will be initialized if nil.

func DateNamed

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

func ExtractJSONPathAs

func ExtractJSONPathAs[T any](o *JSON, path string) (valueAs T, ok bool)

ExtractJSONPathAs is a convenience function for asserting a path to a specific type. The underlying value is also extracted from its Dynamic wrapper if present.

func Named

func Named(name string, value any) driver.NamedValue

func Open

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

func OpenDB

func OpenDB(opt *Options) *sql.DB

Types

type ArraySet

type ArraySet []any

type AsyncOptions

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

type Auth

type Auth struct {
	Database string
	Username string
	Password string
}

type ClientInfo

type ClientInfo struct {
	Products []struct {
		Name    string
		Version string
	}
	// contains filtered or unexported fields
}

func (ClientInfo) String

func (o ClientInfo) String() string

type Compression

type Compression struct {
	Method CompressionMethod
	// this only applies to lz4, lz4hc, 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
	ConnOpenRandom
)

type CustomSetting

type CustomSetting struct {
	Value string
}

CustomSetting is a helper struct to distinguish custom settings from important ones. For native protocol, is_important flag is set to value 0x02 (see https://github.com/ClickHouse/ClickHouse/blob/c873560fe7185f45eed56520ec7d033a7beb1551/src/Core/BaseSettings.h#L516-L521) Only string value is supported until formatting logic that exists in ClickHouse is implemented in clickhouse-go. (https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Field.cpp#L312 and https://github.com/ClickHouse/clickhouse-go/issues/992)

type Dial

type Dial func(ctx context.Context, addr string, opt *Options) (DialResult, error)

type DialResult

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

func DefaultDialStrategy

func DefaultDialStrategy(ctx context.Context, connID int, opt *Options, dial Dial) (r DialResult, err error)

type Dynamic

type Dynamic = chcol.Dynamic

Dynamic is an alias for the Variant type

func NewDynamic

func NewDynamic(v any) Dynamic

NewDynamic creates a new Dynamic with the given value

func NewDynamicWithType

func NewDynamicWithType(v any, chType string) Dynamic

NewDynamicWithType creates a new Dynamic with the given value and ClickHouse type

type Exception

type Exception = proto.Exception

type GroupSet

type GroupSet struct {
	Value []any
}

type HTTPProxy

type HTTPProxy func(*http.Request) (*url.URL, error)

type HTTPReaderWriter

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

func (*HTTPReaderWriter) NewReader

func (rw *HTTPReaderWriter) NewReader(res *http.Response) (io.Reader, error)

NewReader will return a reader that will decompress data if needed.

type JSON

type JSON = chcol.JSON

JSON represents a ClickHouse JSON type that can hold multiple possible types

func NewJSON

func NewJSON() *JSON

NewJSON creates a new empty JSON value

type JSONDeserializer

type JSONDeserializer = chcol.JSONDeserializer

JSONDeserializer interface allows a struct to load its data from an optimized JSON structure instead of relying on recursive reflection to set its fields.

type JSONSerializer

type JSONSerializer = chcol.JSONSerializer

JSONSerializer interface allows a struct to be manually converted to an optimized JSON structure instead of relying on recursive reflection. Note that the struct must be a pointer in order for the interface to be matched, reflection will be used otherwise.

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
	ClientInfo ClientInfo

	TLS                  *tls.Config
	Addr                 []string
	Auth                 Auth
	DialContext          func(ctx context.Context, addr string) (net.Conn, error)
	DialStrategy         func(ctx context.Context, connID int, options *Options, dial Dial) (DialResult, error)
	Debug                bool
	Debugf               func(format string, v ...any) // only works when Debug is true
	Settings             Settings
	Compression          *Compression
	DialTimeout          time.Duration // default 30 second
	MaxOpenConns         int           // default MaxIdleConns + 5
	MaxIdleConns         int           // default 5
	ConnMaxLifetime      time.Duration // default 1 hour
	ConnOpenStrategy     ConnOpenStrategy
	FreeBufOnConnRelease bool              // drop preserved memory buffer after each query
	HttpHeaders          map[string]string // set additional headers on HTTP requests
	HttpUrlPath          string            // set additional URL path for HTTP requests
	HttpMaxConnsPerHost  int               // MaxConnsPerHost for http.Transport
	BlockBufferSize      uint8             // default 2 - can be overwritten on query
	MaxCompressionBuffer int               // default 10485760 - measured in bytes  i.e.

	// HTTPProxy specifies an HTTP proxy URL to use for requests made by the client.
	HTTPProxyURL *url.URL

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

func ParseDSN

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

type Parameters

type Parameters map[string]string

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 WithBlockBufferSize

func WithBlockBufferSize(size uint8) QueryOption

func WithExternalTable

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

func WithLogs

func WithLogs(fn func(*Log)) QueryOption

func WithParameters

func WithParameters(params Parameters) 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

func WithUserLocation

func WithUserLocation(location *time.Location) QueryOption

type QueryOptions

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

type ServerVersion

type ServerVersion = proto.ServerHandshake

type Settings

type Settings map[string]any

type TimeUnit

type TimeUnit uint8
const (
	Seconds TimeUnit = iota
	MilliSeconds
	MicroSeconds
	NanoSeconds
)

type Variant

type Variant = chcol.Variant

Variant represents a ClickHouse Variant type that can hold multiple possible types

func NewVariant

func NewVariant(v any) Variant

NewVariant creates a new Variant with the given value

func NewVariantWithType

func NewVariantWithType(v any, chType string) Variant

NewVariantWithType creates a new Variant with the given value and ClickHouse type

Source Files

batch.go bind.go chcol.go clickhouse.go clickhouse_options.go clickhouse_rows.go clickhouse_rows_column_type.go clickhouse_std.go client_info.go conn.go conn_async_insert.go conn_batch.go conn_check_ping.go conn_exec.go conn_handshake.go conn_http.go conn_http_async_insert.go conn_http_batch.go conn_http_exec.go conn_http_query.go conn_logs.go conn_ping.go conn_process.go conn_profile_events.go conn_query.go conn_send_query.go context.go context_watchdog.go query_parameters.go scan.go struct_map.go

Directories

PathSynopsis
benchmark
benchmark/v1
benchmark/v1/read
benchmark/v1/write
benchmark/v2
benchmark/v2/read
benchmark/v2/read-native
benchmark/v2/write
benchmark/v2/write-async
benchmark/v2/write-async-std
benchmark/v2/write-compress-buffer-limit
benchmark/v2/write-native
benchmark/v2/write-native-columnar
benchmark/v2/write-native-struct
contributors
examples
examples/clickhouse_api
examples/std
ext
internal
lib
lib/binary
lib/chcol
lib/cityhash102* COPY from https://github.com/zentures/cityhash/
lib/column
lib/column/codegen
lib/column/orderedmap
lib/driver
lib/proto
lib/timezone
resources
tests
tests/issues
tests/issues/209
tests/issues/360
tests/issues/470
tests/issues/476
tests/issues/484
tests/issues/485
tests/std
tests/stress
Version
v2.34.0 (latest)
Published
Apr 1, 2025
Platform
js/wasm
Imports
43 packages
Last checked
now

Tools for package owners.