> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Клиенты Go для ClickHouse позволяют подключаться к ClickHouse через стандартный интерфейс Go database/sql или через оптимизированный нативный интерфейс.
# ClickHouse Go
## Краткое руководство
Для начала рассмотрим простой пример. В нем мы подключимся к 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.
### Инициализация модуля
```bash theme={null}
mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example
```
### Скопируйте пример кода
Скопируйте этот код в каталог `clickhouse-golang-example` и сохраните его в файле `main.go`.
```go title=main.go theme={null}
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{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
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
```bash theme={null}
go mod tidy
```
### Укажите сведения о подключении
Ранее вы нашли сведения о подключении. Укажите их в `main.go` в функции `connect()`:
```go highlight={5,7-9} theme={null}
func connect() (driver.Conn, error) {
var (
ctx = context.Background()
conn, err = clickhouse.Open(&clickhouse.Options{
Addr: []string{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
Password: "",
},
```
### Запустите пример
```bash theme={null}
go run .
```
```response theme={null}
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](https://github.com/ClickHouse/clickhouse-go) - Высокоуровневый клиент, поддерживающий либо стандартный интерфейс Go `database/sql`, либо API ClickHouse.
* [ch-go](https://github.com/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](https://github.com/ClickHouse/ch-go). Он позволяет избежать накладных расходов, связанных с преобразованием данных из построчного формата в столбцы, как того требует собственный формат ClickHouse. Кроме того, в нём не используются рефлексия и тип `interface{}` (`any`), что упрощает работу.
Для рабочих нагрузок запросов, ориентированных на агрегации, или вставки с меньшей пропускной способностью [clickhouse-go](https://github.com/ClickHouse/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`
Или клонируйте репозиторий:
```bash theme={null}
git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github
```
Чтобы установить другую версию, измените путь или имя ветки соответствующим образом.
```bash theme={null}
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, которые в настоящее время поддерживаются и перечислены [здесь](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). Когда поддержка версий 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`](/ru/integrations/language-clients/go/configuration#connection-settings). Это увеличит потребление памяти, но позволит декодировать больше блоков параллельно при итерации по строкам. Значение по умолчанию — 2; оно выбрано с запасом и минимизирует накладные расходы по памяти. Чем выше значение, тем больше блоков будет находиться в памяти. Здесь требуется тестирование, так как разные запросы могут создавать блоки разного размера. Поэтому этот параметр можно задавать на [уровне запроса](/ru/integrations/language-clients/go/clickhouse-api#using-context) через Context.
* При вставке данных явно указывайте типы. Хотя клиент старается быть гибким — например, позволяет разбирать строки как UUID или IP-адреса, — это требует проверки данных и влечет дополнительные затраты во время вставки.
* По возможности используйте столбцовые вставки. Они также должны быть строго типизированы, чтобы клиенту не приходилось преобразовывать ваши значения.
* Следуйте [рекомендациям](/ru/reference/statements/insert-into#performance-considerations) ClickHouse для достижения оптимальной производительности вставки.
## Следующие шаги
* [Конфигурация](/ru/integrations/language-clients/go/configuration) — настройки подключения, TLS, аутентификация, логирование, сжатие
* [API ClickHouse](/ru/integrations/language-clients/go/clickhouse-api) — нативный API Go для запросов и операций вставки
* [API Database/SQL](/ru/integrations/language-clients/go/database-sql-api) — стандартный интерфейс `database/sql`
* [Типы данных](/ru/integrations/language-clients/go/data-types) — сопоставление типов Go и поддержка сложных типов