> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> clickhouse-goクライアントの設定：接続、TLS、認証、プーリング、ログ、圧縮。
# 設定
## 接続設定
各オプションの詳細な説明、デフォルト値、DSN パラメータ、ベストプラクティス、トラブルシューティングについては、[Configuration Reference](/ja/integrations/language-clients/go/config-reference) を参照してください。
接続を開く際は、Options 構造体を使用してクライアントの動作を制御できます。利用可能な設定は次のとおりです。
| Parameter | Type | Default | Description |
| ---------------------- | -------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Protocol` | `Protocol` | `Native` | 転送プロトコル: `Native` (TCP) または `HTTP`。詳しくは [TCP vs HTTP](#tcp-vs-http) を参照してください。 |
| `Addr` | `[]string` | — | `host:port` 形式のアドレスを格納したスライス。複数ノードについては [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 |
| `Auth` | `Auth` | — | 認証情報 (`Database`、`Username`、`Password`) 。詳しくは [認証](#authentication) を参照してください。 |
| `TLS` | `*tls.Config` | `nil` | TLS 設定。`nil` 以外の値を指定すると TLS が有効になります。詳しくは [TLS](#using-tls) を参照してください。 |
| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | TCP 接続の確立方法を制御するためのカスタム dial 関数。 |
| `DialTimeout` | `time.Duration` | `30s` | 新しい接続を開く際の最大待機時間。アイドル状態になっている可能性がある ClickHouse Cloud サービスに接続する場合は、`1m`～`2m` に引き上げてください。詳しくは [Timeouts](/ja/integrations/language-clients/go/config-reference#timeouts) を参照してください。 |
| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | 同時にオープンできる接続の最大数。 |
| `MaxIdleConns` | `int` | `5` | 接続プール内に保持するアイドル接続の数。 |
| `ConnMaxLifetime` | `time.Duration` | `1h` | プールされた接続の最大存続時間。詳しくは [接続プーリング](#connection-pooling) を参照してください。 |
| `ConnOpenStrategy` | `ConnOpenStrategy` | `ConnOpenInOrder` | `Addr` からノードを選択する戦略。詳しくは [複数のノードへの接続](#connecting-to-multiple-nodes) を参照してください。 |
| `BlockBufferSize` | `uint8` | `2` | 並列にデコードするブロック数。値を大きくするとスループットは向上しますが、その分メモリ使用量も増えます。コンテキスト経由でクエリごとに上書きできます。 |
| `Settings` | `Settings` | — | すべてのクエリに適用される ClickHouse settings の map。個々のクエリでは [context](/ja/integrations/language-clients/go/clickhouse-api#using-context) を介して上書きできます。 |
| `Compression` | `*Compression` | `nil` | ブロック単位の圧縮。詳しくは [圧縮](#compression) を参照してください。 |
| `ReadTimeout` | `time.Duration` | — | 1 回の呼び出しでサーバーからの読み取りを待機する最大時間。 |
| `FreeBufOnConnRelease` | `bool` | `false` | `true` の場合、クエリごとに接続のメモリバッファをプールへ戻します。わずかな CPU コストと引き換えにメモリ使用量を削減します。 |
| `Logger` | `*slog.Logger` | `nil` | 構造化ロガー (Go の `log/slog`) 。詳しくは [ログ](#logging) を参照してください。 |
| `Debug` | `bool` | `false` | **非推奨。** 代わりに `Logger` を使用してください。従来のデバッグ出力を stdout に出力します。 |
| `Debugf` | `func(string, ...any)` | — | **非推奨。** 代わりに `Logger` を使用してください。カスタムのデバッグログ関数。`Debug: true` が必要です。 |
| `GetJWT` | `GetJWTFunc` | — | ClickHouse Cloud の認証用 JWT トークンを返すコールバック (HTTPS のみ) 。 |
| `HttpHeaders` | `map[string]string` | — | すべての HTTP リクエストで送信される追加の HTTP ヘッダー (HTTP トランスポートのみ) 。 |
| `HttpUrlPath` | `string` | — | HTTP リクエストに追加される URL パス (HTTP トランスポートのみ) 。 |
| `HttpMaxConnsPerHost` | `int` | — | 基盤となる `http.Transport` の `MaxConnsPerHost` を上書きします (HTTP トランスポートのみ) 。 |
| `TransportFunc` | `func(*http.Transport) (http.RoundTripper, error)` | — | カスタム HTTP トランスポートファクトリ。必要な項目だけを上書きできるよう、デフォルトのトランスポートが渡されます (HTTP トランスポートのみ) 。 |
| `HTTPProxyURL` | `*url.URL` | — | すべてのリクエストに使用される HTTP プロキシ URL (HTTP トランスポートのみ) 。 |
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
DialContext: func(ctx context.Context, addr string) (net.Conn, error) {
dialCount++
var d net.Dialer
return d.DialContext(ctx, "tcp", addr)
},
Debug: true,
Debugf: func(format string, v ...interface{}) {
fmt.Printf(format, v)
},
Settings: clickhouse.Settings{
"max_execution_time": 60,
},
Compression: &clickhouse.Compression{
Method: clickhouse.CompressionLZ4,
},
DialTimeout: time.Duration(10) * time.Second,
MaxOpenConns: 5,
MaxIdleConns: 5,
ConnMaxLifetime: time.Duration(10) * time.Minute,
ConnOpenStrategy: clickhouse.ConnOpenInOrder,
BlockBufferSize: 10,
})
if err != nil {
return err
}
```
[完全なサンプル](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/connect_settings.go)
## TLS
低レベルでは、すべてのクライアント接続メソッド (`DSN/OpenDB/Open`) で、安全な接続を確立するために [Go tls package](https://pkg.go.dev/crypto/tls) が使用されます。Options 構造体に non-nil の `tls.Config` ポインターが含まれている場合、クライアントは TLS を使用することを認識します。
```go theme={null}
env, err := GetNativeTestEnvironment()
if err != nil {
return err
}
cwd, err := os.Getwd()
if err != nil {
return err
}
t := &tls.Config{}
caCert, err := ioutil.ReadFile(path.Join(cwd, "../../tests/resources/CAroot.crt"))
if err != nil {
return err
}
caCertPool := x509.NewCertPool()
successful := caCertPool.AppendCertsFromPEM(caCert)
if !successful {
return err
}
t.RootCAs = caCertPool
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
TLS: t,
})
if err != nil {
return err
}
v, err := conn.ServerVersion()
if err != nil {
return err
}
fmt.Println(v.String())
```
[完全なサンプル](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/ssl.go)
通常、この最小限の `TLS.Config` で ClickHouse サーバーのセキュアなネイティブポート (通常は 9440) に接続するには十分です。ClickHouse サーバーに有効な証明書 (有効期限切れ、ホスト名の不一致、公開されている信頼済みルート認証局による署名がない、など) がない場合は、`InsecureSkipVerify` を `true` にすることもできますが、これは強く非推奨です。
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
TLS: &tls.Config{
InsecureSkipVerify: true,
},
})
if err != nil {
return err
}
v, err := conn.ServerVersion()
```
[完全な例](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/ssl_no_verify.go)
追加のTLSパラメータが必要な場合は、アプリケーションコードで `tls.Config` 構造体の必要なフィールドを設定する必要があります。これには、特定の暗号スイートの指定、特定のTLSバージョン (1.2 や 1.3 など) の強制、内部CA証明書チェーンの追加、ClickHouse サーバー で必要な場合のクライアント証明書 (および秘密鍵) の追加、さらに高度なセキュリティ構成で利用されるその他の大半のオプションが含まれます。
## 認証
接続情報でユーザー名とパスワードを指定するには、Auth 構造体を指定します。
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
})
if err != nil {
return err
}
v, err := conn.ServerVersion()
```
[完全なサンプル](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/auth.go)
## 複数のノードへの接続
複数のアドレスは、`Addr` 構造体で指定できます。
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
})
if err != nil {
return err
}
v, err := conn.ServerVersion()
if err != nil {
return err
}
fmt.Println(v.String())
```
[完全な例](https://github.com/ClickHouse/clickhouse-go/blob/1c0d81d0b1388dbb9e09209e535667df212f4ae4/examples/clickhouse_api/multi_host.go#L26-L45)
利用可能な接続戦略は 3 つあります。
* `ConnOpenInOrder` (デフォルト) - アドレスは定義された順に使用されます。リストの前方にあるアドレスで接続に失敗した場合にのみ、後続のアドレスが使われます。実質的にはフェイルオーバー戦略です。
* `ConnOpenRoundRobin` - ラウンドロビン戦略によって、各アドレスに負荷が分散されます。
* `ConnOpenRandom` - アドレスのリストからノードがランダムに選択されます。
これは `ConnOpenStrategy` オプションで制御できます
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
ConnOpenStrategy: clickhouse.ConnOpenRoundRobin,
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
})
if err != nil {
return err
}
v, err := conn.ServerVersion()
if err != nil {
return err
}
```
[完全な例](https://github.com/ClickHouse/clickhouse-go/blob/1c0d81d0b1388dbb9e09209e535667df212f4ae4/examples/clickhouse_api/multi_host.go#L50-L67)
## 接続プーリング
クライアントは接続プールを維持し、必要に応じてクエリ間で接続を再利用します。同時に使用される接続数の上限は `MaxOpenConns` で、プールに保持するアイドル接続数の上限は `MaxIdleConns` で制御されます。クライアントはクエリを実行するたびにプールから接続を取得し、再利用できるよう実行後にプールへ返します。接続はバッチの存続期間中使用され、`Send()` で解放されます。
ユーザーが `MaxOpenConns=1` を設定しない限り、プール内の同じ接続が後続のクエリでも使われる保証はありません。これが必要になるケースはまれですが、一時テーブルを使用する場合には必要になることがあります。
また、`ConnMaxLifetime` のデフォルト値は 1 時間である点にも注意してください。そのため、ノードがクラスターから離脱すると、ClickHouse への負荷が不均衡になる場合があります。これは、あるノードが利用できなくなると、接続が他のノードに振り分けられるためです。問題のあるノードがクラスターに復帰しても、これらの接続は維持され、デフォルトでは 1 時間更新されません。ワークロードが高い場合は、この値を小さくすることを検討してください。
接続プーリングは、Native (TCP) と HTTP プロトコルの両方で有効です。
## ログ
クライアントは、`Options` の `Logger` フィールドを使用して、Go 標準の `log/slog` パッケージによる構造化ログをサポートしています。従来の `Debug` フィールドと `Debugf` フィールドは非推奨ですが、後方互換性のため引き続き利用できます (優先順位: `Debugf` > `Logger` > no-op) 。
```go theme={null}
import (
"log/slog"
"os"
)
// JSON構造化ロギング
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelDebug,
}))
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
Logger: logger,
})
```
ロガーにアプリケーションレベルのコンテキストを追加することもできます：
```go theme={null}
baseLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))
enrichedLogger := baseLogger.With(
slog.String("service", "my-service"),
slog.String("environment", "production"),
)
conn, err := clickhouse.Open(&clickhouse.Options{
// ...
Logger: enrichedLogger,
})
```
[完全なサンプル](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/logger_test.go)
## 圧縮
圧縮方式のサポートは、使用する基盤プロトコルに依存します。ネイティブプロトコルでは、クライアントは `LZ4` と `ZSTD` の圧縮をサポートしています。これはブロック単位でのみ行われます。圧縮を有効にするには、接続に `Compression` 設定を含めます。
```go theme={null}
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
Auth: clickhouse.Auth{
Database: env.Database,
Username: env.Username,
Password: env.Password,
},
Compression: &clickhouse.Compression{
Method: clickhouse.CompressionZSTD,
},
MaxOpenConns: 1,
})
ctx := context.Background()
defer func() {
conn.Exec(ctx, "DROP TABLE example")
}()
conn.Exec(context.Background(), "DROP TABLE IF EXISTS example")
if err = conn.Exec(ctx, `
CREATE TABLE example (
Col1 Array(String)
) Engine Memory
`); err != nil {
return err
}
batch, err := conn.PrepareBatch(ctx, "INSERT INTO example")
if err != nil {
return err
}
defer batch.Close()
for i := 0; i < 1000; i++ {
if err := batch.Append([]string{strconv.Itoa(i), strconv.Itoa(i + 1), strconv.Itoa(i + 2), strconv.Itoa(i + 3)}); err != nil {
return err
}
}
if err := batch.Send(); err != nil {
return err
}
```
[完全な例](https://github.com/ClickHouse/clickhouse-go/blob/main/examples/clickhouse_api/compression.go)
HTTPトランスポートを使用する場合は、`gzip`、`deflate`、`br` といった追加の圧縮方式も利用できます。詳しくは、[Database/SQL API - Compression](/ja/integrations/language-clients/go/database-sql-api#compression) を参照してください。
## TCP と HTTP
トランスポートは config の切り替えひとつで指定でき、このガイドのそれ以外の内容は両方に共通して適用されます。違いは次のとおりです。
| | TCP (ネイティブプロトコル) | HTTP |
| :----------------------------- | :--------------------- | :-------------------------------------------------- |
| **デフォルトポート** | 9000 (平文), 9440 (TLS) | 8123 (平文), 8443 (TLS) |
| **有効化** | デフォルト — `Protocol` を省略 | `Protocol: clickhouse.HTTP` または `http://` DSN を使用 |
| **圧縮** | `lz4`, `zstd` | `lz4`, `zstd`, `gzip`, `deflate`, `br` |
| **セッション** | 組み込み (常時有効) | 明示的 — 設定として `session_id` を渡す |
| **HTTP ヘッダー** | — | `HttpHeaders`, `HttpUrlPath`, `HttpMaxConnsPerHost` |
| **カスタムトランスポート** | — | `TransportFunc` |
| **JWT 認証** | — | `GetJWT` (ClickHouse Cloud HTTPS) |
| **OpenTelemetry (`WithSpan`)** | ✅ | サーバー側は対応しているが、クライアントはまだ `traceparent` ヘッダーを送信しない |
いずれかの API を HTTP に切り替えるには:
```go theme={null}
// HTTP経由のClickHouse API
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{"host:8123"},
Protocol: clickhouse.HTTP,
// ... 認証など
})
// HTTP経由のdatabase/sql — Optionsを使用
conn := clickhouse.OpenDB(&clickhouse.Options{
Addr: []string{"host:8123"},
Protocol: clickhouse.HTTP,
// ... 認証など
})
// HTTP経由のdatabase/sql — DSNを使用
conn, err := sql.Open("clickhouse", "http://host:8123?username=user&password=pass")
```