ClickHouse Go - ClickHouse Documentation

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

Для начала рассмотрим простой пример. В нем мы подключимся к 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+

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

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

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

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

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

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

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

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

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

​Подробнее

​Обзор

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

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

​Установка

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

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

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

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

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