ClickHouse Go

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

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

Сведения о подключении для вашего сервиса 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.

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

Ранее вы нашли сведения о подключении. Укажите их в 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 использовать и какой транспорт использовать. В сочетании они дают четыре режима подключения:

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

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

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

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

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

Драйвер 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 в течение 2 лет с даты релиза клиента. Обратите внимание: активно тестируются только LTS-версии.

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

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