> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

На этой странице описаны все настраиваемые параметры в `clickhouse-go` v2.x. Примеры с кодом см. в разделе [Конфигурация](/ru/integrations/language-clients/go/configuration).

<Info>
  **Пометки о версиях**

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

<div id="how-options-are-set">
  ## Как задаются параметры
</div>

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

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

Если области видимости пересекаются, приоритет имеет более конкретный уровень: **батч > Query > Connection**. Для `Settings` ключи уровня запроса объединяются с ключами уровня соединения; при конфликте приоритет у ключей уровня запроса.

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

```go theme={null}
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:**

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

**Через Connector (database/sql со структурой Options):**

```go theme={null}
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 (для каждого запроса):**

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

***

<div id="connection-options">
  ## Варианты подключения
</div>

<div id="protocol-and-connection">
  ### Протокол и подключение
</div>

| Опция              | Тип                        | По умолчанию                                              | Параметр 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](/ru/integrations/language-clients/go/configuration#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: всю нагрузку получает первый сервер, остальные бездействуют. При сбое все стратегии пробуют все серверы — различается только то, какой сервер будет опробован *первым*. |

***

<div id="authentication">
  ### Аутентификация
</div>

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

```go theme={null}
GetJWT: func(ctx context.Context) (string, error) {
    return getTokenFromVault(ctx)
}
```

***

<div id="timeouts">
  ### Тайм-ауты
</div>

| Параметр      | Тип             | По умолчанию | Параметр 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"` в середине запроса; сервер продолжает выполнение. Слишком длинный: разорванные соединения не обнаруживаются.                                   |

<Note title="Приостановленные сервисы ClickHouse Cloud">
  Сервис ClickHouse Cloud, который некоторое время не использовался, приостанавливается и пробуждается при первом входящем соединении. Пробуждение обычно занимает несколько десятков секунд, в течение которых попытка подключения блокируется. Если `DialTimeout` меньше времени пробуждения, первый запрос после периода простоя завершается ошибкой тайм-аута подключения вместо выполнения.

  Установите `DialTimeout` в `1m`–`2m` для клиентов, которые могут первыми обратиться к приостановленному сервису. Компромисс в том, что при реальном сбое обнаружение ошибки будет медленнее — попытка подключения будет блокироваться на весь тайм-аут перед возвратом ошибки, — поэтому лучше ограничить увеличенный тайм-аут только первым подключением или использовать дедлайны контекста для отдельных запросов, чтобы ограничить сквозную задержку.
</Note>

***

<div id="connection-pool">
  ### Пул соединений
</div>

| Параметр          | Тип             | По умолчанию                          | Параметр 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): соединения пересоздаются во время обычных пауз.                                                              |

<Info>
  **только для `database/sql`**

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

  ```go theme={null}
  db := clickhouse.OpenDB(&clickhouse.Options{...})
  db.SetConnMaxIdleTime(5 * time.Minute)
  ```
</Info>

См. [Пул соединений](/ru/integrations/language-clients/go/configuration#connection-pooling), чтобы узнать подробности использования.

***

<div id="sql-db-settings">
  ### Стандартные настройки пула database/sql
</div>

При использовании `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)` | *Нет*                | Необходимо задать вручную после создания   |

<Info>
  **API ClickHouse (clickhouse.Open)**

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

***

<div id="compression">
  ### Сжатие
</div>

| 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`  | Нет    | Да   |

***

<div id="tls">
  ### TLS
</div>

| Параметр | Тип           | По умолчанию           | Параметр 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](/ru/integrations/language-clients/go/configuration#using-tls) для примеров кода.

***

<div id="logging">
  ### Журналирование
</div>

| Параметр            | 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`.     | —                                                                                                           | —                                                                                                                      |

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

Подробные примеры см. в разделе [Логирование](/ru/integrations/language-clients/go/configuration#logging).

***

<div id="buffers-and-memory">
  ### Буферы и память
</div>

| Опция                  | Тип     | По умолчанию | Параметр 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. |

***

<div id="http-specific">
  ### Для HTTP
</div>

<Warning>
  **Молча игнорируется при использовании собственного протокола**

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

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

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

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

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

  Собственный протокол использует простое соотношение 1:1 и игнорирует `HttpMaxConnsPerHost`.
</Info>

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

***

<div id="advanced-connection">
  ### Расширенные настройки подключения
</div>

| Параметр       | Тип                                                    | По умолчанию               | Параметр 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% случаев используйте значение по умолчанию. Пользовательскую стратегию применяйте только для маршрутизации с учётом географии, взвешенного выбора и проверок работоспособности. | Если не перебирать все серверы: сбои даже при наличии доступных исправных серверов. Дорогостоящие операции внутри: блокируют получение соединения из пула при каждом подключении. |

***

<div id="client-information">
  ### Информация о клиенте
</div>

| 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%'` | Если не задано, в средах с несколькими сервисами невозможно определить, какой сервис отправлял запросы. |

```go theme={null}
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)
```

***

<div id="server-settings">
  ### Настройки сервера ClickHouse
</div>

| 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 = только для чтения + изменение настроек |

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

***

<div id="context-options">
  ## Параметры запроса на уровне Context
</div>

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

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

<Info>
  **Поведение дедлайна контекста**

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

| Параметр                  | Тип                               | По умолчанию                 | Протокол                       | Описание                                                                                                                                                                                                        | Рекомендуемая практика                                                                           | При неправильной настройке                                                                                                                                                |
| ------------------------- | --------------------------------- | ---------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](/ru/integrations/language-clients/go/clickhouse-api#open-telemetry).         | —                                                                                                                                                                         |

```go theme={null}
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}")
```

***

<div id="batch-options">
  ## Параметры батча
</div>

Передаются в `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()` закрывает батч, последующие операции завершаются ошибкой. |

```go theme={null}
batch, err := conn.PrepareBatch(ctx, "INSERT INTO table",
    driver.WithReleaseConnection(),
    driver.WithCloseOnFlush(),
)
```

***

<div id="quick-reference-tables">
  ## Справочные таблицы
</div>

<div id="pool-sizing">
  ### Рекомендации по настройке размера пула соединений
</div>

| Тип приложения                    | 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              |

<div id="timeout-recommendations">
  ### Рекомендации по тайм-аутам
</div>

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

<div id="dsn-parameters">
  ### Краткий справочник по параметрам DSN
</div>

| Параметр 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`                |

***

<div id="troubleshooting">
  ## Устранение неполадок
</div>

<div id="acquire-conn-timeout">
  ### Пул соединений исчерпан: "acquire conn timeout"
</div>

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

**Решение**

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

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

<div id="io-timeout">
  ### Ошибки тайм-аута чтения и сброса соединения
</div>

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

**Решение:**

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

<div id="auth-failed">
  ### "Код: 516. Ошибка аутентификации"
</div>

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

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

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

<div id="tls-errors">
  ### Ошибки TLS-сертификатов
</div>

| Ошибка                                          | Причина                                 | Решение                                                 |
| ----------------------------------------------- | --------------------------------------- | ------------------------------------------------------- |
| `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)  |

<div id="memory-growth">
  ### Постепенный рост потребления памяти
</div>

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

**Решение:**

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