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

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

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

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

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

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

Через строку DSN:

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

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

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Установить настройки пула, специфичные для database/sql, после создания
db.SetConnMaxIdleTime(5 * time.Minute)

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

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

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

См. Пул соединений, чтобы узнать подробности использования.

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

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

См. TLS для примеров кода.

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

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

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

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)

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

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

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

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

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

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

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

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

Решение

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

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

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

Решение:

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

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

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

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

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

Решение:

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