ClickHouse Go

Клиенты Go для ClickHouse позволяют подключаться к ClickHouse через стандартный интерфейс Go database/sql или через оптимизированный нативный интерфейс.

​

Краткое руководство

Для начала рассмотрим простой пример. В нем мы подключимся к ClickHouse и выполним выборку из системной базы данных. Для этого вам понадобятся сведения о подключении.

​

Сведения о подключении

Чтобы подключиться к ClickHouse по native TCP, вам понадобится следующая информация:

Параметры	Описание
HOST and PORT	Обычно используется порт 9440 при использовании TLS или 9000 без TLS.
DATABASE NAME	По умолчанию доступна база данных default; используйте имя базы данных, к которой хотите подключиться.
USERNAME and PASSWORD	По умолчанию используется имя пользователя default. Используйте имя пользователя, подходящее для вашего сценария.

Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите сервис, к которому хотите подключиться, и нажмите Connect:

Выберите Native — сведения будут показаны в примере команды clickhouse-client.

Если вы используете самоуправляемый ClickHouse, сведения о подключении задаются администратором ClickHouse.

​

Инициализация модуля

mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example

​

Скопируйте пример кода

Скопируйте этот код в каталог clickhouse-golang-example и сохраните его в файле main.go.

main.go

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "log"

    "github.com/ClickHouse/clickhouse-go/v2"
    "github.com/ClickHouse/clickhouse-go/v2/lib/driver"
)

func main() {
    conn, err := connect()
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    rows, err := conn.Query(ctx, "SELECT name, toString(uuid) as uuid_str FROM system.tables LIMIT 5")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var name, uuid string
        if err := rows.Scan(&name, &uuid); err != nil {
            log.Fatal(err)
        }
        log.Printf("name: %s, uuid: %s", name, uuid)
    }

    // ПРИМЕЧАНИЕ: Не пропускайте проверку rows.Err()
    if err := rows.Err(); err != nil {
        log.Fatal(err)
    }

}

func connect() (driver.Conn, error) {
    var (
        ctx       = context.Background()
        conn, err = clickhouse.Open(&clickhouse.Options{
            Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
            Auth: clickhouse.Auth{
                Database: "default",
                Username: "default",
                Password: "<DEFAULT_USER_PASSWORD>",
            },
            ClientInfo: clickhouse.ClientInfo{
                Products: []struct {
                    Name    string
                    Version string
                }{
                    {Name: "an-example-go-client", Version: "0.1"},
                },
            },
            Debugf: func(format string, v ...interface{}) {
                fmt.Printf(format, v)
            },
            TLS: &tls.Config{
                InsecureSkipVerify: true,
            },
        })
    )

    if err != nil {
        return nil, err
    }

    if err := conn.Ping(ctx); err != nil {
        if exception, ok := err.(*clickhouse.Exception); ok {
            fmt.Printf("Exception [%d] %s \n%s\n", exception.Code, exception.Message, exception.StackTrace)
        }
        return nil, err
    }
    return conn, nil
}

​

Запустите go mod tidy

go mod tidy

​

Укажите сведения о подключении

Ранее вы нашли сведения о подключении. Укажите их в main.go в функции connect():

func connect() (driver.Conn, error) {
  var (
    ctx       = context.Background()
    conn, err = clickhouse.Open(&clickhouse.Options{
      Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
      Auth: clickhouse.Auth{
        Database: "default",
        Username: "default",
        Password: "<DEFAULT_USER_PASSWORD>",
      },

​

Запустите пример

go run .

2023/03/06 14:18:33 name: COLUMNS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: SCHEMATA, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: TABLES, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: VIEWS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: hourly_data, uuid: a4e36bd4-1e82-45b3-be77-74a0fe65c52b

​

Подробнее

В остальной документации этого раздела подробно рассматривается клиент Go для ClickHouse.

​

Обзор

ClickHouse поддерживает два официальных клиента Go. Эти клиенты дополняют друг друга и намеренно предназначены для разных сценариев использования.

• clickhouse-go - Высокоуровневый клиент, поддерживающий либо стандартный интерфейс Go database/sql, либо API ClickHouse.
• ch-go - Низкоуровневый клиент. Только нативный интерфейс.

clickhouse-go предоставляет высокоуровневый интерфейс, позволяя пользователям выполнять запросы и вставку данных с использованием построчной семантики и батчинга, не слишком строгого к типам данных: значения будут преобразованы, если это не приведет к потенциальной потере точности. ch-go, в свою очередь, предоставляет оптимизированный интерфейс, ориентированный на столбцы, который обеспечивает быстрый стриминг блоков данных при низких накладных расходах CPU и памяти, ценой более строгой типизации и более сложного использования.

Начиная с версии 2.3 clickhouse-go использует ch-go для низкоуровневых функций, таких как кодирование, декодирование и сжатие. Оба клиента используют для кодирования нативный формат, чтобы обеспечить оптимальную производительность, и могут взаимодействовать по нативному протоколу ClickHouse. clickhouse-go также поддерживает HTTP в качестве транспортного механизма в случаях, когда пользователям требуется проксировать трафик или балансировать нагрузку.

​

Четыре способа подключения

clickhouse-go предоставляет два независимых варианта: какой API использовать и какой транспорт использовать. В сочетании они дают четыре режима подключения:

	TCP (собственный протокол, порт 9000/9440)	HTTP (порт 8123/8443)
API ClickHouse (clickhouse.Open)	По умолчанию — максимальная производительность	Укажите Protocol: clickhouse.HTTP
API database/sql (OpenDB / sql.Open)	clickhouse://host:9000	http://host:8123

Выбор API: Выбирайте API ClickHouse, если нужна максимальная производительность и полный набор возможностей (обратные вызовы прогресса, столбцовые вставки, расширенная поддержка типов). Выбирайте database/sql, если нужна интеграция с ORM или инструментами, которым требуется стандартный интерфейс базы данных Go.

Выбор транспорта: TCP быстрее и используется по умолчанию. Переключайтесь на HTTP, если этого требует ваша инфраструктура — например, при подключении через HTTP-балансировщик или proxy, либо если вам нужны специфичные для HTTP возможности, такие как сеансы с временными таблицами или дополнительные алгоритмы сжатия (gzip, deflate, br).

Оба API используют собственное двоичное кодирование независимо от транспорта, поэтому HTTP не добавляет накладных расходов на serialization.

	Native format	TCP transport	HTTP transport	Bulk write	Struct marshaling	Сжатие	Обратные вызовы прогресса
API ClickHouse	✅	✅	✅	✅	✅	✅	✅
API database/sql	✅	✅	✅	✅		✅

​

Выбор клиента

Выбор клиентской библиотеки зависит от характера использования и требований к производительности. Для сценариев с интенсивной вставкой, где нужно выполнять миллионы вставок в секунду, мы рекомендуем использовать низкоуровневый клиент ch-go. Он позволяет избежать накладных расходов, связанных с преобразованием данных из построчного формата в столбцы, как того требует собственный формат ClickHouse. Кроме того, в нём не используются рефлексия и тип interface{} (any), что упрощает работу.

Для рабочих нагрузок запросов, ориентированных на агрегации, или вставки с меньшей пропускной способностью clickhouse-go предоставляет привычный интерфейс database/sql и более простую модель работы со строками. При необходимости вы также можете использовать HTTP в качестве транспортного протокола и воспользоваться вспомогательными функциями для маршалинга строк в структуры и обратно.

	Native format	Собственный протокол	HTTP-протокол	API с построчной моделью	API с моделью по столбцам	Гибкость типов	Сжатие	Плейсхолдеры запросов
clickhouse-go	✅	✅	✅	✅	✅	✅	✅	✅
ch-go	✅	✅			✅		✅

​

Установка

Драйвер v1 устарел и не будет получать обновления функциональности или поддержку новых типов ClickHouse. Вам следует перейти на v2, который обеспечивает более высокую производительность.

Чтобы установить клиент версии 2.x, добавьте пакет в файл go.mod:

require github.com/ClickHouse/clickhouse-go/v2 main

Или клонируйте репозиторий:

git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github

Чтобы установить другую версию, измените путь или имя ветки соответствующим образом.

mkdir my-clickhouse-app && cd my-clickhouse-app

cat > go.mod <<-END
  module my-clickhouse-app

  go 1.21

  require github.com/ClickHouse/clickhouse-go/v2 main
END

cat > main.go <<-END
  package main

  import (
    "fmt"
    "github.com/ClickHouse/clickhouse-go/v2"
  )

  func main() {
   conn, _ := clickhouse.Open(&clickhouse.Options{Addr: []string{"127.0.0.1:9000"}})
    v, _ := conn.ServerVersion()
    fmt.Println(v.String())
  }
END

go mod tidy
go run main.go

​

Версионирование

Клиент выпускается независимо от ClickHouse. 2.x — это текущая разрабатываемая мажорная версия. Все версии 2.x должны быть совместимы друг с другом.

​

Совместимость с ClickHouse

Клиент поддерживает:

• Все версии ClickHouse, которые в настоящее время поддерживаются и перечислены здесь. Когда поддержка версий ClickHouse прекращается, они также перестают проходить активное тестирование на совместимость с релизами клиента.
• Все версии ClickHouse в течение 2 лет с даты релиза клиента. Обратите внимание: активно тестируются только LTS-версии.

​

Совместимость с Golang

Версия клиента	Версии Golang
=> 2.0 <= 2.2	1.17, 1.18
>= 2.3, < 2.41	1.18+
>= 2.41	1.21+
>= 2.43	1.24+

​

Рекомендации

• По возможности используйте API ClickHouse, особенно для примитивных типов. Это позволяет избежать существенных накладных расходов на рефлексию и дополнительные уровни косвенности.
• Если вы читаете большие наборы данных, рассмотрите возможность изменить BlockBufferSize. Это увеличит потребление памяти, но позволит декодировать больше блоков параллельно при итерации по строкам. Значение по умолчанию — 2; оно выбрано с запасом и минимизирует накладные расходы по памяти. Чем выше значение, тем больше блоков будет находиться в памяти. Здесь требуется тестирование, так как разные запросы могут создавать блоки разного размера. Поэтому этот параметр можно задавать на уровне запроса через Context.
• При вставке данных явно указывайте типы. Хотя клиент старается быть гибким — например, позволяет разбирать строки как UUID или IP-адреса, — это требует проверки данных и влечет дополнительные затраты во время вставки.
• По возможности используйте столбцовые вставки. Они также должны быть строго типизированы, чтобы клиенту не приходилось преобразовывать ваши значения.
• Следуйте рекомендациям ClickHouse для достижения оптимальной производительности вставки.

​

Следующие шаги

• Конфигурация — настройки подключения, TLS, аутентификация, логирование, сжатие
• API ClickHouse — нативный API Go для запросов и операций вставки
• API Database/SQL — стандартный интерфейс database/sql
• Типы данных — сопоставление типов Go и поддержка сложных типов