Справочник по конфигурации клиента Go

На этой странице описаны все параметры, которые можно настроить в clickhouse-go v2.x. Руководство с примерами кода см. в разделе Configuration.

Пометки о версиях

Параметры, добавленные в clickhouse-go v2.35.0 и позже, помечены (Начиная с vX.Y.Z) рядом с описанием. Параметры без метки "Since" доступны с v2.0 и присутствуют во всех поддерживаемых релизах.

Как задаются параметры

Параметры задаются на трех уровнях:

Область видимости	Как задать	Время действия
Соединение	структура `clickhouse.Options` или строка DSN	Все запросы в рамках соединения
Запрос	`clickhouse.Context()` с функциями `WithXxx`	Выполнение одного запроса
Батч	функции параметров `PrepareBatch()`	Одна батч-операция

Если уровни пересекаются, приоритет имеет более конкретный: Батч > Запрос > Соединение. Для Settings ключи уровня запроса объединяются с ключами уровня соединения, и при конфликте приоритет имеют ключи уровня запроса.

Через структуру Options:

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default", Password: ""},
    DialTimeout: 10 * time.Second,
    Compression: &clickhouse.Compression{Method: clickhouse.CompressionLZ4},
})

С помощью строки DSN:

db, err := sql.Open("clickhouse", "clickhouse://user:pass@localhost:9000/default?dial_timeout=10s&compress=lz4")

Через Connector (database/sql с использованием структуры Options):

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Set database/sql-only pool settings after creation
db.SetConnMaxIdleTime(5 * time.Minute)

Через контекст (для каждого запроса):

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query-123"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)
rows, err := conn.Query(ctx, "SELECT ...")

Варианты подключения

Протокол и соединение

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендация	При неверной конфигурации
`Protocol`	`Protocol` (int)	`Native`	Схема: `clickhouse://`=Native, `http://`=HTTP	Протокол обмена: `Native` (0) для TCP, `HTTP` (1) для HTTP	Используйте Native для производительности примерно на 30% выше. Используйте HTTP, если нужна поддержка прокси, прохождение через межсетевой экран (порт 80/443) или сжатие, доступное только по HTTP (`gzip`/`br`). См. TCP vs HTTP.	Схема HTTP с портом Native (9000): отказ в соединении. Native заблокирован межсетевым экраном: тайм-ауты.
`Addr`	`[]string`	`["localhost:9000"]` (Native) `["localhost:8123"]` (HTTP)	Хосты в URL через запятую	Список адресов `"host:port"` для подключения и переключения при отказе	В production указывайте несколько адресов для высокой доступности. Правильные порты: 9000 (Native), 8123 (HTTP), 9440 (Native+TLS), 8443 (HTTP+TLS).	Один адрес: нет переключения при отказе. Неверный порт: `"connection refused"`. Empty/nil: по умолчанию используется localhost, что приводит к сбоям в распределённых развертываниях.
`ConnOpenStrategy`	`ConnOpenStrategy` (uint8)	`ConnOpenInOrder` (0)	`connection_open_strategy` (`in_order`, `round_robin`, `random`)	Стратегия выбора сервера из `Addr`. `InOrder` (0)=переключение при отказе, `RoundRobin` (1)=балансировка нагрузки, `Random` (2)=случайный выбор.	`InOrder` — для active-standby. `RoundRobin` — для active-active/K8s. `Random` — чтобы избежать эффекта thundering herd.	`InOrder` с active-active: вся нагрузка идёт на первый сервер, остальные бездействуют. При сбое все стратегии перебирают все серверы — различается только то, какой из них будет опробован первым.

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

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
`Auth.Username`	`string`	`"default"`	`username` или часть URL с именем пользователя	Имя пользователя для аутентификации в ClickHouse	Никогда не используйте `default` в рабочей среде. Создавайте отдельных пользователей с минимальными правами.	Неверное имя пользователя: `"Code: 516. DB::Exception: Authentication failed"`. Пустая строка: неявно используется `"default"`.
`Auth.Password`	`string`	`""`	`password` или часть URL с паролем	Пароль для аутентификации в ClickHouse	В рабочей среде используйте переменные окружения или менеджеры секретов. Специальные символы в DSN кодируйте для URL.	Неверный пароль: `"Code: 516. DB::Exception: Authentication failed"`. Специальные символы не закодированы для URL: ошибки разбора.
`Auth.Database`	`string`	`""` (значение сервера по умолчанию)	`database` или путь URL (`/mydb`)	База данных по умолчанию для соединения	Всегда указывайте явно. В рабочей среде используйте отдельные базы данных для каждого приложения.	Не существует: `"Code: 81. DB::Exception: Database xyz doesn't exist"`. Пустое значение в мультитантной конфигурации: запросы выполняются не в той базе данных.
`GetJWT`	`func(ctx) (string, error)`	`nil`	(только программно)	Функция обратного вызова, возвращающая JWT для аутентификации в ClickHouse Cloud. Для отдельного запроса можно переопределить с помощью `WithJWT(token)`. (Начиная с v2.35.0)	Реализуйте кэширование и обновление токена — функция вызывается для каждого соединения/запроса.	Просроченный токен: ошибки аутентификации. Блокирующая функция обратного вызова: тайм-ауты. JWT имеет приоритет над user/pass. Требуется TLS — без него происходит тихий откат к user/pass.

GetJWT: func(ctx context.Context) (string, error) {
    return getTokenFromVault(ctx)
}

Тайм-ауты

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендуемая практика	При неверной настройке
`DialTimeout`	`time.Duration`	`30s`	`dial_timeout`	Максимальное время на установление нового соединения. Также определяет, сколько ждать получения соединения из пула, когда достигнут предел `MaxOpenConns`.	5–10 с в LAN, 15–30 с в WAN/облаке. Никогда не устанавливайте меньше 1 с.	Слишком короткий: `"clickhouse: acquire conn timeout"` при перегрузке. Слишком длинный (> 60 с): приложение зависает во время сбоев.
`ReadTimeout`	`time.Duration`	`5m` (300s)	`read_timeout`	Максимальное время ожидания ответа сервера для одного вызова чтения. Применяется к каждому блоку, а не ко всему запросу. Если в контексте задан дедлайн, он имеет приоритет.	10–30 с для коротких интерактивных запросов; 5–30 мин для длительных аналитических запросов.	Слишком короткий: `"i/o timeout"` или `"read: connection reset by peer"` в середине запроса; сервер продолжает выполнение. Слишком длинный: неработающие соединения не обнаруживаются.

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

Option	Type	Default	DSN param	API	Description	Best practice	When misconfigured
`MaxIdleConns`	`int`	`5`	`max_idle_conns`	Оба	Макс. число бездействующих (неиспользуемых, но активных) соединений в пуле	50–80% от ожидаемого числа одновременных запросов. Низкое: 2–5, среднее: 10–20, высокое: 20–50.	Слишком низкое: частое пересоздание соединений, выше задержка. Слишком высокое: лишний расход памяти. Автоматически ограничивается значением `MaxOpenConns`.
`MaxOpenConns`	`int`	`MaxIdleConns + 5` (по умолчанию: 10)	`max_open_conns`	Оба	Макс. общее число соединений (бездействующие + активные)	Низкое: 10–20, среднее: 20–50, высокое: 50–100. Формула: одновременные запросы + всплеск + буфер. Мониторинг: `SELECT * FROM system.metrics WHERE metric='TCPConnection'`.	Слишком низкое: `"clickhouse: acquire conn timeout"`. Слишком высокое: на сервере `"Too many connections"`, превышены лимиты FD. Значение `max_connections` в ClickHouse по умолчанию: 1024 (общее).
`ConnMaxLifetime`	`time.Duration`	`1h`	`conn_max_lifetime`	Оба	Макс. время, в течение которого соединение можно использовать повторно. Проверяется при возврате в пул.	1–5ч для стабильных сред. 5–15м для K8s/роллинг-обновлений. Никогда не используйте бесконечное значение.	Слишком короткое (< 1m): частое пересоздание, выше задержка. Слишком длинное/бесконечное: устаревшие соединения, не подхватываются изменения DNS, трафик не перебалансируется.
`ConnMaxIdleTime`	`time.Duration`	`0` (нет)	—	только `database/sql`	Макс. время, в течение которого соединение может оставаться бездействующим до закрытия. В структуре `Options` отсутствует — задаётся через `db.SetConnMaxIdleTime()`.	5–10м для K8s/неравномерной рабочей нагрузки, чтобы освобождать бездействующие соединения после всплесков трафика.	Не задано: бездействующие соединения сохраняются до `ConnMaxLifetime`. Слишком короткое (< 30s): соединения пересоздаются во время обычных пауз.

Примечание

только database/sql

ConnMaxIdleTime — это стандартная настройка пула Go database/sql. Она недоступна в структуре clickhouse.Options и не задаётся через clickhouse.Open(). Задайте её после OpenDB():

db := clickhouse.OpenDB(&clickhouse.Options{...})
db.SetConnMaxIdleTime(5 * time.Minute)

См. раздел Пул соединений для получения подробной информации по использованию.

Стандартные настройки пула database/sql

При использовании clickhouse.OpenDB() или sql.Open("clickhouse", dsn) возвращаемый объект *sql.DB поддерживает стандартные методы пула Go. OpenDB() автоматически применяет первые три параметра из Options:

Метод	Эквивалент в `Options`	Примечания
`db.SetMaxIdleConns(n)`	`MaxIdleConns`	Автоматически применяется в `OpenDB()`
`db.SetMaxOpenConns(n)`	`MaxOpenConns`	Автоматически применяется в `OpenDB()`
`db.SetConnMaxLifetime(d)`	`ConnMaxLifetime`	Автоматически применяется в `OpenDB()`
`db.SetConnMaxIdleTime(d)`	Нет	Необходимо задать вручную после создания

API ClickHouse (clickhouse.Open)

Эти методы недоступны для соединения, возвращаемого clickhouse.Open(). API ClickHouse управляет собственным пулом внутри драйвера, напрямую используя поля структуры Options.

Сжатие

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендация	При неверной настройке
`Compression.Method`	`CompressionMethod` (byte)	None	`compress` (`lz4`, `zstd`, `lz4hc`, `gzip`, `deflate`, `br` или `true` для LZ4)	Алгоритм сжатия для передачи данных. См. матрицу поддержки протоколов ниже.	LAN: None или LZ4. WAN: ZSTD или LZ4. При ограничении по CPU: LZ4. Максимальное сжатие: ZSTD (Native) или Brotli (HTTP). Не используйте для вставок < 1 MB.	GZIP/Brotli в Native: сбой согласования соединения. LZ4HC в HTTP: ошибка или тихий переход на другой вариант. Без сжатия в медленных сетях: вставки в 10–100 раз медленнее.
`Compression.Level`	`int`	`3`	`compress_level`	Интенсивность, зависящая от алгоритма. GZIP/Deflate: от -2 до 9. Brotli: от 0 до 11. LZ4/ZSTD: игнорируется.	Сбалансированный GZIP: 3-6. Сбалансированный Brotli: 4-6.	Очень высокие уровни: крайне высокая нагрузка на CPU при минимальной пользе. Ненулевое значение для LZ4/ZSTD: молча игнорируется. Уровень без включённого сжатия: без эффекта.
`MaxCompressionBuffer`	`int` (bytes)	`10485760` (10 MiB)	`max_compression_buffer`	Максимальный размер буфера сжатия перед сбросом. У каждого соединения свой буфер.	Значение по умолчанию 10 MiB обычно подходит. 20-50 MiB для широких строк. Общая память = буфер x `MaxOpenConns`.	Слишком маленький (< 1 MiB): частые сбросы, низкая эффективность. Слишком большой (> 100 MiB): OOM при большом количестве соединений.

Поддержка методов сжатия по протоколам:

Метод	Native	HTTP
`CompressionLZ4`	Да	Да
`CompressionLZ4HC`	Да	Нет
`CompressionZSTD`	Да	Да
`CompressionGZIP`	Нет	Да
`CompressionDeflate`	Нет	Да
`CompressionBrotli`	Нет	Да

TLS

Опция	Тип	По умолчанию	Параметр DSN	Описание	Рекомендуемая практика	При неверной настройке
`TLS`	`*tls.Config`	`nil` (без шифрования)	`secure=true`, `skip_verify=true`	Конфигурация TLS/SSL. Ненулевое значение включает TLS. Порты: Native 9000/9440, HTTP 8123/8443.	Всегда включайте в продакшене и в ClickHouse Cloud (обязательно). `InsecureSkipVerify: false` в продакшене. Добавляйте собственные CA через `RootCAs`.	Неверный порт: `"connection reset by peer"`. `skip_verify=true` в продакшене: уязвимость к MITM. Просроченный сертификат: `"x509: certificate has expired"`. Неверное имя хоста: `"x509: certificate is valid for X, not Y"`. Недоверенный CA: `"x509: certificate signed by unknown authority"`. Для HTTP DSN с `secure=true` используйте схему `https://`.

См. TLS, где приведены примеры кода.

Логирование

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендуемая практика	При неверной настройке
`Logger`	`*slog.Logger`	`nil` (без логирования)	—	Структурированный логгер через Go `log/slog`. Приоритет: `Debug`+`Debugf` > `Logger` > no-op. (Начиная с v2.43.0)	В production используйте `slog` с обработчиком JSON. Добавляйте контекст приложения через `logger.With(...)`.	—
`Debug` (deprecated)	`bool`	`false`	`debug`	Устаревший флаг отладки. Используйте `Logger` вместо него. Пишет в stdout, если `Debugf` не задан.	—	Включение в production: накладные расходы по производительности, многословные журналы, вывод чувствительных данных.
`Debugf` (deprecated)	`func(string, ...any)`	`nil`	—	Пользовательская функция для отладочного журналирования. Используйте `Logger` вместо неё. Требует `Debug: true`.	—	—

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
conn, err := clickhouse.Open(&clickhouse.Options{
    Logger: logger,
    // ...
})

См. раздел Логирование, где приведены подробные примеры.

Буферы и память

Параметр	Тип	По умолчанию	Параметр DSN	Для каждого запроса	Описание	Рекомендация	При неверной настройке
`BlockBufferSize`	`uint8`	`2`	`block_buffer_size`	Да (`WithBlockBufferSize`)	Количество декодированных блоков, буферизуемых при чтении результатов. Позволяет выполнять чтение и декодирование параллельно.	Обычно достаточно значения 2 по умолчанию. Используйте 5–10 для больших потоковых результатов. Память = буфер x размер блока x число одновременных запросов.	Слишком мало (1): чтение блокируется, задержка возрастает. Слишком много (> 50): высокое потребление памяти, отдача снижается.
`FreeBufOnConnRelease`	`bool`	`false`	—	Нет	Освобождать буфер памяти соединения после каждого запроса вместо повторного использования.	`false` для высокой частоты запросов. `true` в контейнерах с ограниченной памятью или при редких крупных пакетах.	`false` + ограниченная память: буферы накапливаются (память = буфер x число бездействующих соединений). `true` + высокая частота: нагрузка на GC, рост CPU.

Специфично для HTTP

Молча игнорируется в Native

Эти параметры влияют только на Protocol: clickhouse.HTTP. При использовании протокола Native они молча игнорируются, при этом ни ошибка, ни предупреждение не выводятся.

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
`HttpHeaders`	`map[string]string`	`nil`	—	Дополнительные HTTP-заголовки для каждого запроса	Используйте для трассировки (`X-Request-ID`) и заголовков прокси-аутентификации. Сводите набор к минимуму.	Переопределение внутренних заголовков (`Content-Type`, `Authorization`) может привести к непредсказуемому поведению.
`HttpUrlPath`	`string`	`""`	`http_path`	URL-путь, добавляемый к запросам. Начальный `/` подставляется автоматически.	Используйте при работе через обратный прокси с маршрутизацией по пути.	Неверный путь: HTTP 404 от прокси или балансировщика нагрузки.
`HttpMaxConnsPerHost`	`int`	`0` (без ограничений)	—	TCP-соединения на один хост на транспортном уровне (`http.Transport.MaxConnsPerHost`).	Для большинства приложений оставляйте 0. Указывайте только если на сервере действуют строгие ограничения на число соединений.	Слишком низкое значение (например, 10 при `MaxOpenConns`=50): узкое место на транспортном уровне, медленные запросы даже при низкой нагрузке на сервер.
`HTTPProxyURL`	`*url.URL`	`nil` (используются env vars)	`http_proxy` (URL-encoded)	HTTP-прокси для маршрутизации запросов	Явно задавайте, если требуется прокси. Переопределяет переменные среды `HTTP_PROXY`/`HTTPS_PROXY`.	Неверный адрес: `"dial tcp: lookup proxy: no such host"`. Если прокси требует аутентификацию — HTTP 407.
`TransportFunc`	`func(*http.Transport) (http.RoundTripper, error)`	`nil`	—	Пользовательская фабрика HTTP-транспорта. Получает транспорт по умолчанию для обёртывания. (Начиная с v2.41.0)	Используйте для middleware обсервабилити. Не переопределяйте `Proxy`, `DialContext`, `TLSClientConfig`.	Возврат `nil`: panic. При переопределении полей клиента TLS/прокси будут молча проигнорированы. Блокирующий RoundTripper: deadlock.

Двухуровневый пул HTTP-соединений

При использовании HTTP есть два пула соединений:

Уровень 1 (приложение): MaxIdleConns / MaxOpenConns -- управляет объектами httpConnect
Уровень 2 (транспорт): HttpMaxConnsPerHost -- управляет базовыми TCP-соединениями

У протокола Native простое соответствие 1:1, и HttpMaxConnsPerHost для него игнорируется.

TransportFunc: func(t *http.Transport) (http.RoundTripper, error) {
    return &loggingRoundTripper{transport: t}, nil
}

Расширенные параметры подключения

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендуемая практика	При неверной настройке
`DialContext`	`func(ctx, addr) (net.Conn, error)`	`nil` (стандартный dialer)	—	Пользовательская функция установки TCP-соединений. Работает как с Native, так и с HTTP.	Оставляйте `nil` в 99% случаев. Используйте для Unix-сокетов, SOCKS-прокси и пользовательского DNS.	Если не учитывается context: зависания, утечки ресурсов. Если задан `TLS`: пользовательский dialer должен сам обрабатывать TLS. Некорректный `net.Conn`: сбои.
`DialStrategy`	`func(ctx, connID, options, dial) (DialResult, error)`	`DefaultDialStrategy`	—	Пользовательская стратегия выбора сервера и установки подключения. Переопределяет `ConnOpenStrategy`.	Используйте значение по умолчанию в 99,9% случаев. Пользовательскую стратегию применяйте только для геораспределённой маршрутизации, взвешенного выбора и проверок работоспособности.	Если не выполняются попытки подключения ко всем серверам: сбои даже при наличии доступных исправных серверов. Дорогостоящие операции внутри: блокируют получение подключения из пула при каждом подключении.

Информация о клиенте

Option	Type	Default	DSN param	Per-query	Description	Best practice	When misconfigured
`ClientInfo`	`ClientInfo` struct	Авто: версия `clickhouse-go` + среда выполнения Go	`client_info_product=myapp/1.0`	Да (`WithClientInfo`, добавляется)	Идентификатор приложения, отправляемый в ClickHouse. Содержит `Products` (`[]struct{Name,Version}`) и `Comment` (`[]string`). Отображается в `system.query_log`.	Всегда указывайте имя и версию приложения. Атрибуция запросов: `SELECT client_name FROM system.query_log WHERE client_name LIKE '%myapp%'`	Если не задано, невозможно определить, какой сервис выполнял запросы в средах с несколькими сервисами.

ClientInfo: clickhouse.ClientInfo{
    Products: []struct{ Name, Version string }{
        {Name: "my-service", Version: "1.0.0"},
    },
}
// Appears as: clickhouse-go/2.x my-service/1.0.0 (lv:go/1.23; os:linux)

Настройки сервера ClickHouse

Параметр	Тип	По умолчанию	Параметр DSN	Для отдельных запросов	Описание	Рекомендация	При неверной настройке
`Settings`	`map[string]any`	`nil`	Любой нераспознанный параметр (например, `?max_execution_time=60`)	Да (`WithSettings`, при конфликте приоритет у контекста)	Настройки сервера ClickHouse, применяемые к каждому запросу. Преобразование DSN: `"true"`→`1`, `"false"`→`0`, числовое значение→`int`.	Задавайте общие лимиты на уровне соединения, а для отдельных запросов переопределяйте их через контекст.	Опечатки: могут молча игнорироваться или вызывать ошибку в зависимости от версии. Неверные типы: `"Cannot parse string 'abc' as Int64"`. `max_execution_time=0` и отсутствие deadline: запросы выполняются бесконечно.
`CustomSetting`	`CustomSetting{Value string}`	—	—	Да (через `WithSettings`)	Помечает настройку как "пользовательскую" (необязательную) для протокола Native. Не вызывает ошибку, если сервер её не распознаёт. В HTTP все настройки по умолчанию считаются пользовательскими.	Используйте для экспериментальных настроек или настроек, зависящих от версии.	Если пометить важные настройки как пользовательские, они будут молча игнорироваться, если не поддерживаются.

Распространённые настройки:

Настройка	Тип	Описание
`max_execution_time`	int	Тайм-аут запроса в секундах
`max_memory_usage`	int	Лимит памяти на запрос (в байтах)
`max_block_size`	int	Размер блока для обработки
`readonly`	int	1 = только для чтения, 2 = только для чтения + изменение настроек

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // important -- errors if unknown
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // custom -- ignored if unknown
}

Параметры запроса на уровне объекта Context

Задаются для каждого запроса с помощью clickhouse.Context():

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)

Поведение дедлайна в Context

Если для Context задан дедлайн > 1 с, max_execution_time автоматически устанавливается в seconds_remaining + 5. Это переопределяет любое значение, заданное вручную.

Параметр	Тип	По умолчанию	Протокол	Описание	Рекомендуемая практика	При неправильной настройке
`WithQueryID`	`string`	Автоматически	Оба	Пользовательский идентификатор запроса. Отображается в `system.query_log` и `system.processes`.	Используйте UUID. Удобно для `KILL QUERY WHERE query_id='...'`.	Повторяющиеся идентификаторы: путаница в `system.query_log`.
`WithQuotaKey`	`string`	`""`	Оба	Ключ QUOTA для ограничения потребления ресурсов в многопользовательской среде. Требуется настройка QUOTA на стороне сервера.	Используйте для ограничений на уровне клиента или пользователя.	Квота не настроена: игнорируется без предупреждения.
`WithJWT`	`string`	`""`	Только по HTTPS	Переопределение JWT для отдельных запросов в ClickHouse Cloud. (С версии v2.35.0)	Используйте для аутентификации отдельных запросов в мультитенантных прокси.	Без TLS: игнорируется, используется аутентификация соединения. При истечении срока действия: `"Token has expired"`.
`WithSettings`	`Settings`	Наследуется от подключения	Оба	Настройки сервера для отдельного запроса. Объединяются с настройками соединения; при конфликте приоритет у контекста.	Переопределяйте `max_execution_time` или `max_rows_to_read` для каждого типа запроса.	То же, что и для `Settings` на уровне соединения.
`WithParameters`	`Параметры` (`map[string]string`)	`nil`	Оба	Значения параметров для параметризованных запросов на стороне сервера. Синтаксис запроса: `{param_name:Type}`.	Используйте вместо конкатенации строк, чтобы защититься от SQL-инъекций.	Не задан параметр: `"Substitution {param_name:Type} isn't set"`. Неверный тип: `"Cannot parse string 'abc' as UInt64"`.
`WithAsync`	`bool` (wait)	Синхронный	Оба	Режим асинхронной вставки. Устанавливает `async_insert=1`. При `wait=true` добавляется `wait_for_async_insert=1`. Требуется ClickHouse 21.11+. (Начиная с v2.41.0; заменяет более старый `WithStdAsync`.)	Используйте для высокопроизводительных вставок.	`wait=false`: ошибки могут возникать асинхронно — проверяйте `system.asynchronous_insert_log`. С SELECT: игнорируется. На старом сервере: `"Unknown setting async_insert"`.
`WithLogs`	`func(*Log)`	`nil`	Только для Native	Обработчик записей журнала сервера во время выполнения запроса.	Он должен работать быстро — иначе будет блокировать выполнение. Для ресурсоёмкой обработки используйте goroutines.	При HTTP: не вызывается без предупреждения.
`WithProgress`	`func(*Progress)`	`nil`	Только для native-протокола	Обновления прогресса запроса (обработанные строки/байты).	Должно работать быстро — блокирует выполнение.	При HTTP: не вызывается без предупреждения.
`WithProfileInfo`	`func(*ProfileInfo)`	`nil`	Только для Native	Обработчик статистики выполнения запроса.	Должен работать быстро — блокирует выполнение.	В HTTP молча не вызывается.
`WithProfileEvents`	`func([]ProfileEvent)`	`nil`	Только для Native	Callback-функция счётчиков производительности.	Должно работать быстро — блокирует выполнение.	При HTTP: вызов никогда не выполняется без предупреждения.
`WithoutProfileEvents`	—	События отправляются	Только для Native	Отключает события профилирования. Оптимизация производительности для серверов ≥ 25.11. (Доступно с v2.44.0)	Используйте, если profile events не нужны.	На старых серверах: ошибка из-за неизвестного параметра.
`WithExternalTable`	`...*ext.Table`	`nil`	Оба	Подключение временных lookup-таблиц к запросу. Данные передаются с каждым запросом.	Используйте таблицы размером < 10 МБ. Native-протокол эффективнее HTTP (multipart).	Большие таблицы: сетевые накладные расходы для каждого запроса.
`WithUserLocation`	`*time.Location`	Часовой пояс сервера	Оба	Переопределяет часовой пояс для разбора DateTime.	Явно задавайте, если часовые пояса клиента и сервера различаются.	Неверный часовой пояс: значения DateTime будут незаметно смещены на несколько часов, возможна порча данных.
`WithColumnNamesAndTypes`	`[]ColumnNameAndType`	`nil` (выполняется DESCRIBE)	Только по HTTP	Пропустите дополнительный запрос `DESCRIBE TABLE` при HTTP-вставках, заранее указав сведения о столбцах. (С версии v2.37.0)	Используйте, когда схема известна и стабильна.	Неверные типы: `"Cannot convert String to UInt64"`. Дрейф схемы после миграции: устаревшие данные.
`WithBlockBufferSize`	`uint8`	На уровне соединения (2)	Оба	Переопределяет значение `BlockBufferSize`, заданное на уровне соединения, для отдельного запроса.	Увеличьте для больших результирующих наборов в определённых запросах.	—
`WithClientInfo`	`ClientInfo`	На уровне соединения	Оба	Добавляет дополнительную информацию о клиенте для отдельного запроса. Не заменяет существующую, а дополняет её. (Начиная с v2.42.0)	Добавьте контекст на уровне отдельного запроса (например, имя конечной точки).	—
`WithSpan`	`trace.SpanContext`	Пусто	Только для native-протокола	Контекст спана OpenTelemetry для распределённой трассировки.	См. OpenTelemetry.	—

ctx := clickhouse.Context(ctx,
    clickhouse.WithQueryID("query-123"),
    clickhouse.WithParameters(clickhouse.Parameters{
        "user_id": "12345",
    }),
    clickhouse.WithProgress(func(p *clickhouse.Progress) {
        log.Printf("Progress: %d rows, %d bytes", p.Rows, p.Bytes)
    }),
)
rows, err := conn.Query(ctx, "SELECT * FROM users WHERE id = {user_id:String}")

Параметры батча

Передаются в PrepareBatch(). Импорт: github.com/ClickHouse/clickhouse-go/v2/lib/driver.

Параметр	По умолчанию	Описание	Рекомендуемая практика	При неверной конфигурации
`WithReleaseConnection`	Соединение удерживается до `Send()`	Освобождает соединение обратно в пул сразу после `PrepareBatch()`. Повторно получает его при `Send()`/`Flush()`.	Используйте для долгоживущих батчей (минуты/часы), чтобы избежать исчерпания пула.	Если не использовать для долгих батчей: `"acquire conn timeout"` при большом количестве активных соединений.
`WithCloseOnFlush`	Батч остается открытым	Автоматически закрывает батч при вызове `Flush()`.	Используйте для одноразовых батчей. Это избавляет от явного вызова `Close()`.	При использовании с несколькими вызовами `Flush()`: первый `Flush()` закрывает батч, последующие операции завершаются ошибкой.

batch, err := conn.PrepareBatch(ctx, "INSERT INTO table",
    driver.WithReleaseConnection(),
    driver.WithCloseOnFlush(),
)

Таблицы для быстрой справки

Тип приложения	MaxIdleConns	MaxOpenConns	ConnMaxLifetime
Веб-приложение с низким трафиком	5	10	1h
API со средним трафиком	20	50	30m
Сервис с высоким трафиком	50	100	15m
Фоновые пакетные задачи	10	20	2h
Развертывание в Kubernetes	10	20	10m
Бессерверные функции (Lambda)	1	5	5m

Окружение	DialTimeout	ReadTimeout
Локально / LAN	5s	30s
Cloud, тот же регион	10s	2m
Cloud, другой регион	30s	5m
OLAP рабочая нагрузка	10s	30m
Реальное время / OLTP	5s	10s

Краткая справка по параметрам DSN

Параметр DSN	Поле options	Пример
`username`	`Auth.Username`	`?username=admin`
`password`	`Auth.Password`	`?password=secret`
`database`	`Auth.Database`	`?database=mydb` или `/mydb` в path
`dial_timeout`	`DialTimeout`	`?dial_timeout=10s`
`read_timeout`	`ReadTimeout`	`?read_timeout=5m`
`max_open_conns`	`MaxOpenConns`	`?max_open_conns=50`
`max_idle_conns`	`MaxIdleConns`	`?max_idle_conns=20`
`conn_max_lifetime`	`ConnMaxLifetime`	`?conn_max_lifetime=30m`
`connection_open_strategy`	`ConnOpenStrategy`	`?connection_open_strategy=round_robin`
`block_buffer_size`	`BlockBufferSize`	`?block_buffer_size=10`
`compress`	`Compression.Method`	`?compress=lz4`
`compress_level`	`Compression.Level`	`?compress_level=6`
`max_compression_buffer`	`MaxCompressionBuffer`	`?max_compression_buffer=20971520`
`secure`	`TLS`	`?secure=true`
`skip_verify`	`TLS.InsecureSkipVerify`	`?skip_verify=true`
`debug`	`Debug`	`?debug=true`
`client_info_product`	`ClientInfo.Products`	`?client_info_product=myapp/1.0`
`http_proxy`	`HTTPProxyURL`	`?http_proxy=http%3A%2F%2Fproxy%3A8080`
`http_path`	`HttpUrlPath`	`?http_path=/clickhouse`
(любой другой параметр)	`Settings[key]`	`?max_execution_time=60`

Устранение неполадок

Пул соединений исчерпан: "acquire conn timeout"

Причина: Пул соединений исчерпан — все соединения из MaxOpenConns заняты, и ни одно не освободилось в течение DialTimeout.

Решение

Попробуйте выполнить следующие шаги по порядку и определить первопричину, прежде чем менять параметры:

Проверьте, нет ли длительно выполняющихся запросов, удерживающих соединения: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. Если такие запросы есть, сначала устраните причины их медленной работы.
Если вы запускаете долгоживущие батчи (между PrepareBatch() и Send() проходят минуты или часы), используйте WithReleaseConnection(), чтобы вернуть соединение в пул, пока батч остаётся открытым.
Увеличьте MaxOpenConns в соответствии с наблюдаемым параллелизмом.
Увеличивайте DialTimeout только в том случае, если ожидаются всплески нагрузки и ожидание получения соединения действительно является узким местом.

Ошибки тайм-аута чтения и сброса соединения

Причина: Превышен ReadTimeout при ожидании ответа от сервера, либо соединение было разорвано сервером или сетью.

Решение:

Увеличьте ReadTimeout для длительно выполняющихся запросов
Используйте дедлайны контекста для управления тайм-аутом отдельных запросов
Проверьте ограничения max_execution_time на стороне сервера ClickHouse

"Code: 516. Ошибка аутентификации"

Причина: Неверное имя пользователя или пароль, либо пользователь не существует.

Исправление:

Проверьте учётные данные по таблице system.users
Проверьте, нет ли проблем с URL-кодированием специальных символов в паролях DSN
Убедитесь, что у пользователя есть доступ к указанной базе данных

Ошибки TLS-сертификатов

Ошибка	Причина	Решение
`x509: certificate has expired`	Срок действия сертификата сервера истёк	Обновите сертификат сервера
`x509: certificate is valid for X, not Y`	Несовпадение имени хоста	Используйте правильное имя хоста или добавьте его в SAN
`x509: certificate signed by unknown authority`	Недоверенный центр сертификации	Добавьте CA в `tls.Config.RootCAs`
`connection reset by peer`	Несоответствие TLS и порта	Для TLS используйте порт 9440 (Native) или 8443 (HTTP)

Постепенный рост потребления памяти

Причина: Накопление больших буферов у бездействующих соединений.

Решение:

Установите FreeBufOnConnRelease: true в средах с ограниченным объёмом памяти
Уменьшите MaxIdleConns, чтобы ограничить количество бездействующих соединений
Уменьшите MaxCompressionBuffer, если используете сжатие
Уменьшите ConnMaxLifetime, чтобы соединения переустанавливались чаще

Справочник по конфигурации клиента Go

Как задаются параметры

Варианты подключения

Протокол и соединение

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

Тайм-ауты

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

Стандартные настройки пула database/sql

Сжатие

TLS

Логирование

Буферы и память

Специфично для HTTP

Расширенные параметры подключения

Информация о клиенте

Настройки сервера ClickHouse

Параметры запроса на уровне объекта Context

Параметры батча

Таблицы для быстрой справки

Рекомендации по размеру пула соединений

Рекомендации по тайм-аутам

Краткая справка по параметрам DSN

Устранение неполадок

Пул соединений исчерпан: "acquire conn timeout"

Ошибки тайм-аута чтения и сброса соединения

"Code: 516. Ошибка аутентификации"

Ошибки TLS-сертификатов

Постепенный рост потребления памяти

Как задаются параметры​

Варианты подключения​

Протокол и соединение​

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

Тайм-ауты​

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

Стандартные настройки пула database/sql​

Сжатие​

TLS​

Логирование​

Буферы и память​

Специфично для HTTP​

Расширенные параметры подключения​

Информация о клиенте​

Настройки сервера ClickHouse​

Параметры запроса на уровне объекта Context​

Параметры батча​

Таблицы для быстрой справки​

Рекомендации по размеру пула соединений​

Рекомендации по тайм-аутам​

Краткая справка по параметрам DSN​

Устранение неполадок​

Пул соединений исчерпан: "acquire conn timeout"​

Ошибки тайм-аута чтения и сброса соединения​

"Code: 516. Ошибка аутентификации"​

Ошибки TLS-сертификатов​

Постепенный рост потребления памяти​

Как задаются параметры

Варианты подключения

Протокол и соединение

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

Тайм-ауты

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

Стандартные настройки пула database/sql

Сжатие

TLS

Логирование

Буферы и память

Специфично для HTTP

Расширенные параметры подключения

Информация о клиенте

Настройки сервера ClickHouse

Параметры запроса на уровне объекта Context

Параметры батча

Таблицы для быстрой справки

Рекомендации по размеру пула соединений

Рекомендации по тайм-аутам

Краткая справка по параметрам DSN

Устранение неполадок

Пул соединений исчерпан: "acquire conn timeout"

Ошибки тайм-аута чтения и сброса соединения

"Code: 516. Ошибка аутентификации"

Ошибки TLS-сертификатов

Постепенный рост потребления памяти