Конфигурация

Настройка клиента clickhouse-go: параметры подключения, TLS, аутентификация, пул соединений, логирование и сжатие.

​

Настройки соединения

Подробное описание каждого параметра, включая значения по умолчанию, параметры DSN, рекомендации и устранение неполадок, см. в Справочнике по конфигурации.

При открытии соединения для управления поведением клиента можно использовать структуру Options. Доступны следующие настройки:

Параметр	Тип	По умолчанию	Описание
Protocol	Protocol	Native	Транспортный протокол: Native (TCP) или HTTP. См. TCP и HTTP.
Addr	[]string	—	Срез адресов в формате host:port. О подключении к нескольким узлам см. Подключение к нескольким узлам.
Auth	Auth	—	Учетные данные для аутентификации (Database, Username, Password). См. Аутентификация.
TLS	*tls.Config	nil	Настройка TLS. Значение, отличное от nil, включает TLS. См. TLS.
DialContext	func(ctx, addr) (net.Conn, error)	—	Пользовательская функция dial для управления установкой TCP-соединений.
DialTimeout	time.Duration	30s	Максимальное время ожидания при открытии нового соединения.
MaxOpenConns	int	MaxIdleConns + 5	Максимальное число одновременно открытых соединений.
MaxIdleConns	int	5	Количество бездействующих соединений, сохраняемых в пуле.
ConnMaxLifetime	time.Duration	1h	Максимальное время жизни соединения в пуле. См. Пул соединений.
ConnOpenStrategy	ConnOpenStrategy	ConnOpenInOrder	Стратегия выбора узла из Addr. См. Подключение к нескольким узлам.
BlockBufferSize	uint8	2	Количество блоков, декодируемых параллельно. Более высокие значения повышают пропускную способность за счет памяти. Можно переопределить для каждого запроса через контекст.
Settings	Settings	—	Карта настроек ClickHouse, применяемых ко всем запросам. Отдельные запросы могут переопределять их через контекст.
Compression	*Compression	nil	Сжатие на уровне блоков. См. Сжатие.
ReadTimeout	time.Duration	—	Максимальное время ожидания чтения с сервера за один вызов.
FreeBufOnConnRelease	bool	false	Если установлено true, буфер памяти соединения возвращается в пул после каждого запроса. Снижает использование памяти ценой небольшой дополнительной нагрузки на CPU.
Logger	*slog.Logger	nil	Структурированный логгер (Go log/slog). См. Логирование.
Debug	bool	false	Устарело. Используйте Logger. Включает устаревший отладочный вывод в stdout.
Debugf	func(string, ...any)	—	Устарело. Используйте Logger. Пользовательская функция отладочного логирования. Требует Debug: true.
GetJWT	GetJWTFunc	—	Функция обратного вызова, возвращающая JWT-токен для аутентификации в ClickHouse Cloud (только HTTPS).
HttpHeaders	map[string]string	—	Дополнительные HTTP-заголовки, отправляемые с каждым запросом (только HTTP-транспорт).
HttpUrlPath	string	—	Дополнительный путь URL, добавляемый к HTTP-запросам (только HTTP-транспорт).
HttpMaxConnsPerHost	int	—	Переопределяет MaxConnsPerHost в базовом http.Transport (только HTTP-транспорт).
TransportFunc	func(*http.Transport) (http.RoundTripper, error)	—	Пользовательская фабрика HTTP-транспорта. Транспорт по умолчанию передается для выборочного переопределения (только HTTP-транспорт).
HTTPProxyURL	*url.URL	—	URL HTTP-прокси для всех запросов (только HTTP-транспорт).

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    DialContext: func(ctx context.Context, addr string) (net.Conn, error) {
        dialCount++
        var d net.Dialer
        return d.DialContext(ctx, "tcp", addr)
    },
    Debug: true,
    Debugf: func(format string, v ...interface{}) {
        fmt.Printf(format, v)
    },
    Settings: clickhouse.Settings{
        "max_execution_time": 60,
    },
    Compression: &clickhouse.Compression{
        Method: clickhouse.CompressionLZ4,
    },
    DialTimeout:      time.Duration(10) * time.Second,
    MaxOpenConns:     5,
    MaxIdleConns:     5,
    ConnMaxLifetime:  time.Duration(10) * time.Minute,
    ConnOpenStrategy: clickhouse.ConnOpenInOrder,
    BlockBufferSize: 10,
})
if err != nil {
    return err
}

Полный пример

​

TLS

На низком уровне все методы подключения клиента (DSN/OpenDB/Open) используют пакет Go tls для установки защищённого соединения. Клиент понимает, что нужно использовать TLS, если структура Options содержит ненулевой указатель tls.Config.

env, err := GetNativeTestEnvironment()
if err != nil {
    return err
}
cwd, err := os.Getwd()
if err != nil {
    return err
}
t := &tls.Config{}
caCert, err := ioutil.ReadFile(path.Join(cwd, "../../tests/resources/CAroot.crt"))
if err != nil {
    return err
}
caCertPool := x509.NewCertPool()
successful := caCertPool.AppendCertsFromPEM(caCert)
if !successful {
    return err
}
t.RootCAs = caCertPool
conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    TLS: t,
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}
fmt.Println(v.String())

Полный пример

Этой минимальной конфигурации TLS.Config обычно достаточно для подключения к защищённому native-порту (обычно 9440) на сервере ClickHouse. Если у сервера ClickHouse нет действительного сертификата (истёк срок действия, неверное имя хоста, сертификат не подписан общепризнанным корневым центром сертификации), для InsecureSkipVerify можно установить значение true, но делать это настоятельно не рекомендуется.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    TLS: &tls.Config{
        InsecureSkipVerify: true,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()

Полный пример

Если требуются дополнительные параметры TLS, прикладной код должен задать нужные поля в структуре tls.Config. Это может включать указание конкретных наборов шифров, принудительное использование определённой версии TLS (например, 1.2 или 1.3), добавление внутренней цепочки CA‑сертификатов, добавление клиентского сертификата (и приватного ключа), если этого требует сервер ClickHouse, а также большинство других параметров для более специализированной конфигурации безопасности.

​

Аутентификация

Укажите структуру Auth в сведениях о подключении, чтобы задать имя пользователя и пароль.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}

v, err := conn.ServerVersion()

Полный пример

​

Подключение к нескольким узлам

Можно указать несколько адресов с помощью структуры Addr.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}
fmt.Println(v.String())

Полный пример

Доступны три стратегии подключения:

• ConnOpenInOrder (по умолчанию) - адреса используются по порядку. Последующие адреса задействуются только в случае сбоя при подключении к адресам, расположенным выше в списке. По сути, это стратегия переключения при отказе.
• ConnOpenRoundRobin - Нагрузка равномерно распределяется между адресами по стратегии round-robin.
• ConnOpenRandom - Узел случайным образом выбирается из списка адресов.

Этим можно управлять с помощью параметра ConnOpenStrategy

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:             []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
    ConnOpenStrategy: clickhouse.ConnOpenRoundRobin,
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}

Полный пример

​

Пул соединений

Клиент поддерживает пул соединений и при необходимости повторно использует соединения между запросами. Одновременно используется не более MaxOpenConns, а максимальный размер пула задается параметром MaxIdleConns. Для выполнения каждого запроса клиент получает соединение из пула, а затем возвращает его обратно для повторного использования. Соединение используется на протяжении всего жизненного цикла батча и освобождается при вызове Send().

Нет гарантии, что для последующих запросов из пула будет использоваться одно и то же соединение, если только пользователь не задаст MaxOpenConns=1. Это требуется редко, но может быть необходимо при использовании временных таблиц.

Также обратите внимание, что значение ConnMaxLifetime по умолчанию составляет 1 час. Это может приводить к неравномерному распределению нагрузки на ClickHouse, если узлы покидают кластер. Например, если узел становится недоступным, соединения перераспределяются на другие узлы. По умолчанию эти соединения сохраняются и не обновляются в течение 1 часа, даже если проблемный узел вернется в кластер. При высокой рабочей нагрузке стоит рассмотреть уменьшение этого значения.

Пул соединений поддерживается как для Native (TCP), так и для HTTP-протокола.

​

Логирование

Клиент поддерживает структурированное логирование через стандартный пакет Go log/slog, используя поле Logger в Options. Поля Debug и Debugf считаются устаревшими, но по-прежнему работают для обратной совместимости (приоритет: Debugf > Logger > no-op).

import (
    "log/slog"
    "os"
)

// Структурированное логирование в формате JSON
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    Logger: logger,
})

Вы также можете добавить в логгер контекст уровня приложения:

baseLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelInfo,
}))
enrichedLogger := baseLogger.With(
    slog.String("service", "my-service"),
    slog.String("environment", "production"),
)

conn, err := clickhouse.Open(&clickhouse.Options{
    // ...
    Logger: enrichedLogger,
})

Полный пример

​

Сжатие

Поддержка методов сжатия зависит от используемого протокола. Для собственного протокола клиент поддерживает сжатие LZ4 и ZSTD. Оно выполняется только на уровне блоков. Сжатие можно включить, добавив конфигурацию Compression к соединению.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    Compression: &clickhouse.Compression{
        Method: clickhouse.CompressionZSTD,
    },
    MaxOpenConns: 1,
})
ctx := context.Background()
defer func() {
    conn.Exec(ctx, "DROP TABLE example")
}()
conn.Exec(context.Background(), "DROP TABLE IF EXISTS example")
if err = conn.Exec(ctx, `
    CREATE TABLE example (
            Col1 Array(String)
    ) Engine Memory
    `); err != nil {
    return err
}
batch, err := conn.PrepareBatch(ctx, "INSERT INTO example")
if err != nil {
    return err
}
defer batch.Close()

for i := 0; i < 1000; i++ {
    if err := batch.Append([]string{strconv.Itoa(i), strconv.Itoa(i + 1), strconv.Itoa(i + 2), strconv.Itoa(i + 3)}); err != nil {
        return err
    }
}
if err := batch.Send(); err != nil {
    return err
}

Полный пример

При использовании HTTP-транспорта доступны дополнительные методы сжатия: gzip, deflate и br. Подробнее см. в разделе Database/SQL API — Compression.

​

TCP vs HTTP

Транспорт переключается одним параметром конфигурации — всё остальное в этом руководстве применимо к обоим вариантам. Вот что меняется:

	TCP (собственный протокол)	HTTP
Порт по умолчанию	9000 (без шифрования), 9440 (TLS)	8123 (без шифрования), 8443 (TLS)
Включение	По умолчанию — не указывайте Protocol	Protocol: clickhouse.HTTP или используйте DSN с http://
Сжатие	lz4, zstd	lz4, zstd, gzip, deflate, br
Сеансы	Встроены (всегда активны)	Явно — передавайте session_id как параметр настройки
HTTP-заголовки	—	HttpHeaders, HttpUrlPath, HttpMaxConnsPerHost
Пользовательский транспорт	—	TransportFunc
JWT-аутентификация	—	GetJWT (HTTPS в ClickHouse Cloud)
OpenTelemetry (WithSpan)	✅	Сервер это поддерживает, но клиент пока не отправляет заголовок traceparent

Чтобы переключить любой API на HTTP:

// API ClickHouse через HTTP
conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... аутентификация и т.д.
})

// database/sql через HTTP — через Options
conn := clickhouse.OpenDB(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... аутентификация и т.д.
})

// database/sql через HTTP — через DSN
conn, err := sql.Open("clickhouse", "http://host:8123?username=user&password=pass")