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

На этой странице описаны все настраиваемые параметры в clickhouse-go v2.x. Примеры с кодом см. в разделе Конфигурация.

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

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

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

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

Если области видимости пересекаются, приоритет имеет более конкретный уровень: батч > Query > Connection. Для 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,
}))
// Установить настройки пула, специфичные для database/sql, после создания
db.SetConnMaxIdleTime(5 * time.Minute)

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

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, если нужна поддержка proxy, обход firewall (порт 80/443) или сжатие, доступное только через HTTP (`gzip`/`br`). См. TCP vs HTTP.	HTTP-схема с портом Native (9000): отказ в подключении. Native заблокирован firewall: тайм-ауты.
`Addr`	`[]string`	`["localhost:9000"]` (Native) `["localhost:8123"]` (HTTP)	Хосты в URL, разделенные запятыми	Список адресов `"host:port"` для подключения и failover	В продакшн указывайте несколько адресов для высокой доступности. Правильные порты: 9000 (Native), 8123 (HTTP), 9440 (Native+TLS), 8443 (HTTP+TLS).	Один адрес: нет failover. Неверный порт: `"connection refused"`. Пустое значение или nil: по умолчанию используется localhost, что приводит к сбою в распределенных развертываниях.
`ConnOpenStrategy`	`ConnOpenStrategy` (uint8)	`ConnOpenInOrder` (0)	`connection_open_strategy` (`in_order`, `round_robin`, `random`)	Стратегия выбора сервера из `Addr`. `InOrder` (0)=failover, `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` or URL user portion	Имя пользователя для аутентификации в ClickHouse	Никогда не используйте `default` в продакшне. Создавайте отдельных пользователей с минимальными разрешениями.	Неверное имя пользователя: `"Code: 516. DB::Exception: Authentication failed"`. Пустая строка: без уведомления используется `"default"`.
`Auth.Password`	`string`	`""`	`password` or URL password portion	Пароль для аутентификации в ClickHouse	В продакшне используйте переменные окружения или менеджеры секретов. Кодируйте специальные символы в DSN для URL.	Неверный пароль: `"Code: 516. DB::Exception: Authentication failed"`. Специальные символы не закодированы для URL: ошибки разбора.
`Auth.Database`	`string`	`""` (server default)	`database` or URL path (`/mydb`)	База данных по умолчанию для подключения	Всегда указывайте явно. В продакшне используйте отдельные базы данных для каждого приложения.	Не существует: `"Code: 81. DB::Exception: Database xyz doesn't exist"`. Пустое значение в многотенантной конфигурации: запросы выполняются не в той базе данных.
`GetJWT`	`func(ctx) (string, error)`	`nil`	(programmatic only)	Callback-функция, возвращающая JWT для аутентификации ClickHouse Cloud. Можно переопределить для каждого запроса с помощью `WithJWT(token)`. (Начиная с v2.35.0)	Реализуйте кэширование и обновление токена — функция вызывается для каждого подключения/запроса.	Истёкший токен: ошибки аутентификации. Блокирующий callback: тайм-ауты. 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-10s в LAN, 15-30s в WAN/cloud, 1-2m при подключении к приостановленному сервису ClickHouse Cloud. Никогда не меньше 1s.	Слишком короткий: `"clickhouse: acquire conn timeout"` при перегрузке или сбой соединения до того, как приостановленный сервис Cloud завершит пробуждение. Слишком длинный (> 60s): приложение зависает во время сбоев.
`ReadTimeout`	`time.Duration`	`5m` (300s)	`read_timeout`	Максимальное время ожидания ответа сервера для каждого вызова чтения. Применяется к каждому блоку, а не ко всему запросу. Приоритет имеет дедлайн контекста.	10-30s для коротких интерактивных запросов; 5-30m для длительных аналитических запросов.	Слишком короткий: `"i/o timeout"` или `"read: connection reset by peer"` в середине запроса; сервер продолжает выполнение. Слишком длинный: разорванные соединения не обнаруживаются.

Сервис ClickHouse Cloud, который некоторое время не использовался, приостанавливается и пробуждается при первом входящем соединении. Пробуждение обычно занимает несколько десятков секунд, в течение которых попытка подключения блокируется. Если DialTimeout меньше времени пробуждения, первый запрос после периода простоя завершается ошибкой тайм-аута подключения вместо выполнения.Установите DialTimeout в 1m–2m для клиентов, которые могут первыми обратиться к приостановленному сервису. Компромисс в том, что при реальном сбое обнаружение ошибки будет медленнее — попытка подключения будет блокироваться на весь тайм-аут перед возвратом ошибки, — поэтому лучше ограничить увеличенный тайм-аут только первым подключением или использовать дедлайны контекста для отдельных запросов, чтобы ограничить сквозную задержку.

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

Параметр	Тип	По умолчанию	Параметр DSN	API	Описание	Рекомендации	При неверной настройке
`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/rolling deploys. Никогда не используйте бесконечное значение.	Слишком мало (< 1m): частое открытие/закрытие соединений, более высокая задержка. Слишком много/бесконечно: устаревшие соединения, не подхватываются изменения DNS, трафик не перераспределяется.
`ConnMaxIdleTime`	`time.Duration`	`0` (нет)	—	только `database/sql`	Максимальное время, в течение которого соединение может оставаться бездействующим перед закрытием. В структуре `Options` отсутствует — задаётся через `db.SetConnMaxIdleTime()`.	5–10 мин для K8s и неравномерной рабочей нагрузки, чтобы освобождать бездействующие соединения после всплесков трафика.	Не задано: бездействующие соединения сохраняются до `ConnMaxLifetime`. Слишком мало (< 30s): соединения пересоздаются во время обычных пауз.

только для database/sqlConnMaxIdleTime — это стандартная настройка пула 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.

Сжатие

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
`Compression.Method`	`CompressionMethod` (byte)	None	`compress` (`lz4`, `zstd`, `lz4hc`, `gzip`, `deflate`, `br`, or `true` for 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 при большом числе соединений.

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

Method	Native	HTTP
`CompressionLZ4`	Да	Да
`CompressionLZ4HC`	Да	Нет
`CompressionZSTD`	Да	Да
`CompressionGZIP`	Нет	Да
`CompressionDeflate`	Нет	Да
`CompressionBrotli`	Нет	Да

TLS

Параметр	Тип	По умолчанию	Параметр DSN	Описание	Рекомендуемая практика	При неверной настройке
`TLS`	`*tls.Config`	`nil` (без шифрования)	`secure=true`, `skip_verify=true`	Конфигурация TLS/SSL. Значение, отличное от `nil`, включает 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 для примеров кода.

Журналирование

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

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

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`: взаимная блокировка.

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

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

Собственный протокол использует простое соотношение 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.	В 99% случаев оставляйте `nil`. Используйте для 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"},
    },
}
// Отображается как: clickhouse-go/2.x my-service/1.0.0 (lv:go/1.23; os:linux)

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

Option	Type	Default	DSN param	Per-query	Description	Best practice	When misconfigured
`Settings`	`map[string]any`	`nil`	Любой нераспознанный параметр (например, `?max_execution_time=60`)	Да (`WithSettings`, при конфликте приоритет у context)	Настройки сервера ClickHouse, применяемые к каждому запросу. Преобразование DSN: `"true"`→`1`, `"false"`→`0`, числовые значения→`int`.	Задавайте общие ограничения на уровне соединения, а для отдельных запросов переопределяйте их через context.	Опечатки: молча игнорируются или вызывают ошибку в зависимости от версии. Неверные типы: `"Cannot parse string 'abc' as Int64"`. `max_execution_time=0` + отсутствие deadline: запросы выполняются бесконечно.
`CustomSetting`	`CustomSetting{Value string}`	—	—	Да (через `WithSettings`)	Помечает настройку как “пользовательскую” (неважную) для собственного протокола. Ошибки не будет, если сервер её не распознаёт. HTTP по умолчанию считает все настройки пользовательскими.	Используйте для экспериментальных настроек или настроек, зависящих от версии.	Если пометить важные настройки как пользовательские, они будут молча проигнорированы, если не поддерживаются.

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

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

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // важный параметр — вызывает ошибку, если неизвестен
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // пользовательский параметр — игнорируется, если неизвестен
}

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

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

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

Поведение дедлайна контекстаЕсли для контекста задан дедлайн > 1s, 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 не настроена: молча игнорируется.
`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-протокола	Обратный вызов для записей журнала сервера во время выполнения запроса.	Должен работать быстро — блокирует выполнение. Для ресурсоёмкой обработки используйте goroutine.	При HTTP: никогда не вызывается без каких-либо уведомлений.
`WithProgress`	`func(*Progress)`	`nil`	Только для native-протокола	Обновления Прогресса запроса (обработанные строки/байты).	Обработчик должен работать быстро — он блокирует выполнение.	При HTTP: никогда не вызывается без каких-либо уведомлений.
`WithProfileInfo`	`func(*ProfileInfo)`	`nil`	Только для Native	Колбэк со статистикой выполнения запроса.	Должен выполняться быстро — блокирует выполнение.	При HTTP: никогда не вызывается без предупреждения.
`WithProfileEvents`	`func([]ProfileEvent)`	`nil`	Только для Native	Колбэк счётчиков производительности.	Должен выполняться быстро — блокирует выполнение.	При HTTP молча не вызывается.
`WithoutProfileEvents`	—	События отправляются	Только для Native	Отключает события профилирования. Оптимизация производительности для серверов ≥ 25.11. (С версии v2.44.0)	Используйте, если profile events не нужны.	На старых серверах: ошибка из-за неизвестного параметра.
`WithExternalTable`	`...*ext.Table`	`nil`	Оба	Подключает временные lookup-таблицы к запросу. Данные передаются с каждым запросом.	Используйте таблицы размером < 10 МБ. Нативный протокол эффективнее 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`	Пусто	Только для нативного протокола	Контекст span 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.

Option	Default	Description	Best practice	When misconfigured
`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
Serverless (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 server

”Код: 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	Добавьте 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”

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

”Код: 516. Ошибка аутентификации”

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

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

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

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

​Протокол и подключение

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

​Тайм-ауты

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

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

​Сжатие

​TLS

​Журналирование

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

​Для HTTP

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

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

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

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

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

​Справочные таблицы

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

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

​Краткий справочник по параметрам DSN

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

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

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

​”Код: 516. Ошибка аутентификации”

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

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

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

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

Протокол и подключение

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

Тайм-ауты

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

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

Сжатие

TLS

Журналирование

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

Для HTTP

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

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

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

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

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

Справочные таблицы

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

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

Краткий справочник по параметрам DSN

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

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

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

”Код: 516. Ошибка аутентификации”

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

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