> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.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`, чтобы соединения пересоздавались чаще