設定

clickhouse-goクライアントの設定：接続、TLS、認証、プーリング、ログ、圧縮。

​

接続設定

各オプションの詳細な説明、デフォルト値、DSN パラメータ、ベストプラクティス、トラブルシューティングについては、Configuration Reference を参照してください。

接続を開く際は、Options 構造体を使用してクライアントの動作を制御できます。利用可能な設定は次のとおりです。

Parameter	Type	Default	Description
Protocol	Protocol	Native	転送プロトコル: Native (TCP) または HTTP。詳しくは TCP vs HTTP を参照してください。
Addr	[]string	—	host:port 形式のアドレスを格納したスライス。複数ノードについては 複数のノードへの接続 を参照してください。
Auth	Auth	—	認証情報 (Database、Username、Password) 。詳しくは 認証 を参照してください。
TLS	*tls.Config	nil	TLS 設定。nil 以外の値を指定すると TLS が有効になります。詳しくは TLS を参照してください。
DialContext	func(ctx, addr) (net.Conn, error)	—	TCP 接続の確立方法を制御するためのカスタム dial 関数。
DialTimeout	time.Duration	30s	新しい接続を開く際の最大待機時間。
MaxOpenConns	int	MaxIdleConns + 5	同時にオープンできる接続の最大数。
MaxIdleConns	int	5	接続プール内に保持するアイドル接続の数。
ConnMaxLifetime	time.Duration	1h	プールされた接続の最大存続時間。詳しくは 接続プーリング を参照してください。
ConnOpenStrategy	ConnOpenStrategy	ConnOpenInOrder	Addr からノードを選択する戦略。詳しくは 複数のノードへの接続 を参照してください。
BlockBufferSize	uint8	2	並列にデコードするブロック数。値を大きくするとスループットは向上しますが、その分メモリ使用量も増えます。コンテキスト経由でクエリごとに上書きできます。
Settings	Settings	—	すべてのクエリに適用される ClickHouse settings の map。個々のクエリでは context を介して上書きできます。
Compression	*Compression	nil	ブロック単位の圧縮。詳しくは 圧縮 を参照してください。
ReadTimeout	time.Duration	—	1 回の呼び出しでサーバーからの読み取りを待機する最大時間。
FreeBufOnConnRelease	bool	false	true の場合、クエリごとに接続のメモリバッファをプールへ戻します。わずかな CPU コストと引き換えにメモリ使用量を削減します。
Logger	*slog.Logger	nil	構造化ロガー (Go の log/slog) 。詳しくは ログ を参照してください。
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 トランスポートのみ) 。

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
}

完全なサンプル

​

TLS

低レベルでは、すべてのクライアント接続メソッド (DSN/OpenDB/Open) で、安全な接続を確立するために Go tls package が使用されます。Options 構造体に non-nil の tls.Config ポインターが含まれている場合、クライアントは TLS を使用することを認識します。

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())

完全なサンプル

通常、この最小限の TLS.Config で ClickHouse サーバーのセキュアなネイティブポート (通常は 9440) に接続するには十分です。ClickHouse サーバーに有効な証明書 (有効期限切れ、ホスト名の不一致、公開されている信頼済みルート認証局による署名がない、など) がない場合は、InsecureSkipVerify を true にすることもできますが、これは強く非推奨です。

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()

完全な例

追加のTLSパラメータが必要な場合は、アプリケーションコードで tls.Config 構造体の必要なフィールドを設定する必要があります。これには、特定の暗号スイートの指定、特定のTLSバージョン (1.2 や 1.3 など) の強制、内部CA証明書チェーンの追加、ClickHouse サーバー で必要な場合のクライアント証明書 (および秘密鍵) の追加、さらに高度なセキュリティ構成で利用されるその他の大半のオプションが含まれます。

​

認証

接続情報でユーザー名とパスワードを指定するには、Auth 構造体を指定します。

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()

完全なサンプル

​

複数のノードへの接続

複数のアドレスは、Addr 構造体で指定できます。

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())

完全な例

利用可能な接続戦略は 3 つあります。

• ConnOpenInOrder (デフォルト) - アドレスは定義された順に使用されます。リストの前方にあるアドレスで接続に失敗した場合にのみ、後続のアドレスが使われます。実質的にはフェイルオーバー戦略です。
• ConnOpenRoundRobin - ラウンドロビン戦略によって、各アドレスに負荷が分散されます。
• ConnOpenRandom - アドレスのリストからノードがランダムに選択されます。

これは ConnOpenStrategy オプションで制御できます

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
}

完全な例

​

接続プーリング

クライアントは接続プールを維持し、必要に応じてクエリ間で接続を再利用します。同時に使用される接続数の上限は MaxOpenConns で、プールに保持するアイドル接続数の上限は MaxIdleConns で制御されます。クライアントはクエリを実行するたびにプールから接続を取得し、再利用できるよう実行後にプールへ返します。接続はバッチの存続期間中使用され、Send() で解放されます。

ユーザーが MaxOpenConns=1 を設定しない限り、プール内の同じ接続が後続のクエリでも使われる保証はありません。これが必要になるケースはまれですが、一時テーブルを使用する場合には必要になることがあります。

また、ConnMaxLifetime のデフォルト値は 1 時間である点にも注意してください。そのため、ノードがクラスターから離脱すると、ClickHouse への負荷が不均衡になる場合があります。これは、あるノードが利用できなくなると、接続が他のノードに振り分けられるためです。問題のあるノードがクラスターに復帰しても、これらの接続は維持され、デフォルトでは 1 時間更新されません。ワークロードが高い場合は、この値を小さくすることを検討してください。

接続プーリングは、Native (TCP) と HTTP プロトコルの両方で有効です。

​

ログ

クライアントは、Options の Logger フィールドを使用して、Go 標準の log/slog パッケージによる構造化ログをサポートしています。従来の Debug フィールドと Debugf フィールドは非推奨ですが、後方互換性のため引き続き利用できます (優先順位: Debugf > Logger > no-op) 。

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,
})

ロガーにアプリケーションレベルのコンテキストを追加することもできます：

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,
})

完全なサンプル

​

圧縮

圧縮方式のサポートは、使用する基盤プロトコルに依存します。ネイティブプロトコルでは、クライアントは LZ4 と ZSTD の圧縮をサポートしています。これはブロック単位でのみ行われます。圧縮を有効にするには、接続に Compression 設定を含めます。

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
}

完全な例

HTTPトランスポートを使用する場合は、gzip、deflate、br といった追加の圧縮方式も利用できます。詳しくは、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 に切り替えるには:

// 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")