Go クライアント設定リファレンス

接続レベル、コンテキストレベル、バッチオプションを網羅した、clickhouse-go クライアントの完全なオプション別設定リファレンスです。

このページでは、clickhouse-go v2.x で設定可能なすべてのオプションを説明します。コード例を含むガイドについては、設定 を参照してください。

バージョン注記

clickhouse-go v2.35.0 以降で追加されたオプションには、説明の横に (Since vX.Y.Z) と記されています。“Since” タグのないオプションは v2.0 以降すべてのサポート対象リリースで利用できます。

​

オプションの設定方法

オプションは、次の 3 つのスコープで設定できます。

Scope	How to set	Lifetime
接続	clickhouse.Options 構造体または DSN 文字列	その接続上のすべてのクエリ
クエリ	WithXxx 関数を使った clickhouse.Context()	1 回のクエリ実行
バッチ	PrepareBatch() のオプション関数	1 回のバッチ操作

スコープが重複する場合は、より具体的なスコープが優先されます: バッチ > クエリ > 接続。Settings については、クエリレベルのキーが接続レベルのキーとマージされ、競合した場合はクエリレベルのキーが優先されます。

Options 構造体を使用する場合:

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default", Password: ""},
    DialTimeout: 10 * time.Second,
    Compression: &clickhouse.Compression{Method: clickhouse.CompressionLZ4},
})

DSN文字列を使用する場合:

db, err := sql.Open("clickhouse", "clickhouse://user:pass@localhost:9000/default?dial_timeout=10s&compress=lz4")

コネクタ経由 (Options 構造体を使用する database/sql) :

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// 作成後にdatabase/sql固有のプール設定を行う
db.SetConnMaxIdleTime(5 * time.Minute)

コンテキスト経由 (クエリ単位) :

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query-123"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)
rows, err := conn.Query(ctx, "SELECT ...")

---

​

接続オプション

​

プロトコルと接続

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
Protocol	Protocol (int)	Native	スキーム: clickhouse://=Native, http://=HTTP	通信プロトコル: TCP には Native (0)、HTTP には HTTP (1) を使用	およそ 30% 高いパフォーマンスが得られるため、通常は Native を使用します。proxy のサポート、ファイアウォール越え (ポート 80/443) 、または HTTP でのみ利用できる圧縮 (gzip/br) が必要な場合は HTTP を使用します。TCP vs HTTP を参照してください。	Native ポート (9000) で HTTP スキームを使うと、接続が拒否されます。ファイアウォールで Native がブロックされていると、タイムアウトが発生します。
Addr	[]string	["localhost:9000"] (Native) ["localhost:8123"] (HTTP)	URL 内でカンマ区切りのホスト	接続とフェイルオーバーに使用する "host:port" 形式のアドレス一覧	HA のため、本番環境では複数のアドレスを指定します。正しいポートは 9000 (Native)、8123 (HTTP)、9440 (Native+TLS)、8443 (HTTP+TLS) です。	単一アドレス: フェイルオーバーなし。誤ったポート: "connection refused"。空または nil: デフォルトで localhost となり、分散デプロイメントでは失敗します。
ConnOpenStrategy	ConnOpenStrategy (uint8)	ConnOpenInOrder (0)	connection_open_strategy (in_order, round_robin, random)	Addr から server を選択する戦略。InOrder (0)=フェイルオーバー、RoundRobin (1)=負荷分散、Random (2)=ランダム。	アクティブ-スタンバイには InOrder。アクティブ-アクティブ/K8s には RoundRobin。thundering herd を避けるには Random。	アクティブ-アクティブ構成で InOrder を使うと、最初の server に負荷が集中し、ほかはアイドル状態になります。障害時には、どの戦略でもすべての server を試行します。違いは、最初にどの server を試すかだけです。

---

​

認証

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
Auth.Username	string	"default"	username or URL user portion	ClickHouse 認証に使用するユーザー名	本番環境では default を決して使用しないでください。最小権限の専用ユーザーを作成してください。	ユーザー名が誤っている場合: "Code: 516. DB::Exception: Authentication failed"。空文字列の場合: 暗黙的に "default" が使用されます。
Auth.Password	string	""	password or URL password portion	ClickHouse 認証に使用するパスワード	本番環境では環境変数またはシークレットマネージャーを使用してください。DSN 内の特殊文字は URL エンコードしてください。	パスワードが誤っている場合: "Code: 516. DB::Exception: Authentication failed"。特殊文字が URL エンコードされていない場合: パースエラー。
Auth.Database	string	"" (server default)	database or URL path (/mydb)	connection に使用するデフォルトの database	必ず明示的に指定してください。本番環境ではアプリケーションごとに専用の database を使用してください。	存在しない場合: "Code: 81. DB::Exception: Database xyz doesn't exist"。マルチテナント構成で空の場合: クエリが誤った database に送られます。
GetJWT	func(ctx) (string, error)	nil	(programmatic only)	ClickHouse Cloud 認証用の JWT を返すコールバック。WithJWT(token) によりクエリごとに上書きできます。 (v2.35.0 以降)	トークンのキャッシュ/更新を実装してください。connection/request ごとに呼び出されます。	トークンの有効期限切れ: 認証エラー。コールバックがブロックする場合: タイムアウト。JWT はユーザー名/パスワードより優先されます。TLS が必要で、これがない場合は黙ってユーザー名/パスワードにフォールバックします。

GetJWT: func(ctx context.Context) (string, error) {
    return getTokenFromVault(ctx)
}

---

​

タイムアウト

オプション	型	デフォルト	DSN パラメータ	説明	推奨事項	誤設定時
DialTimeout	time.Duration	30s	dial_timeout	新しい接続の確立にかけられる最大時間。MaxOpenConns に達した場合のプールからの接続取得待ち時間も制御します。	LAN では 5〜10 秒、WAN/クラウドでは 15〜30 秒、アイドル状態の ClickHouse Cloud サービスに接続する場合は 1〜2 分。1 秒未満にはしないでください。	短すぎる場合: 輻輳時に "clickhouse: acquire conn timeout" が発生するか、アイドル状態の Cloud サービスの起動完了前に接続が失敗します。長すぎる場合 (> 60s): 障害時にアプリが長時間応答しなくなります。
ReadTimeout	time.Duration	5m (300s)	read_timeout	読み取り呼び出しごとにサーバー応答を待つ最大時間。クエリ全体ではなく、ブロックごとに適用されます。コンテキストのデッドラインが優先されます。	短時間の対話型クエリでは 10〜30 秒、長時間の分析クエリでは 5〜30 分。	短すぎる場合: クエリの途中で "i/o timeout" または "read: connection reset by peer" が発生し、サーバー側では実行が継続します。長すぎる場合: 切断された接続を検出できません。

アイドル状態だった ClickHouse Cloud サービスは一時停止され、最初の受信接続で起動します。起動には通常数十秒かかり、その間は接続試行がブロックされます。DialTimeout が起動時間より短いと、アイドル期間後の最初のクエリは実行されず、接続タイムアウトで失敗します。

アイドル状態のサービスに最初に到達する可能性がある client では、DialTimeout を 1m〜2m に設定してください。その代償として、実際の障害時の失敗検出は遅くなります。つまり、エラーになるまで接続試行がタイムアウトいっぱいまでブロックされます。そのため、高めのタイムアウトは最初の接続だけに適用するか、個々のクエリでコンテキストのデッドラインを使ってエンドツーエンドのレイテンシを抑えることを推奨します。

---

​

接続プール

Option	Type	Default	DSN param	API	Description	Best practice	When misconfigured
MaxIdleConns	int	5	max_idle_conns	Both	プール内でアイドル状態 (未使用だが有効) の接続の最大数	想定される同時実行クエリ数の 50〜80%。小規模: 2〜5、中規模: 10〜20、大規模: 20〜50。	低すぎる場合: 接続の張り直しが頻発し、レイテンシーが増加します。高すぎる場合: メモリを無駄に消費します。上限は自動的に MaxOpenConns になります。
MaxOpenConns	int	MaxIdleConns + 5 (デフォルト: 10)	max_open_conns	Both	接続の総数 (アイドル + アクティブ) の最大値	小規模: 10〜20、中規模: 20〜50、大規模: 50〜100。式: 同時実行クエリ数 + バースト + バッファ。監視: SELECT * FROM system.metrics WHERE metric='TCPConnection'。	低すぎる場合: "clickhouse: acquire conn timeout"。高すぎる場合: サーバーで "Too many connections" が発生し、FD 制限を超える可能性があります。ClickHouse のデフォルト max_connections: 1024 (共有) 。
ConnMaxLifetime	time.Duration	1h	conn_max_lifetime	Both	接続を再利用できる最大時間。プールに戻される際にチェックされます。	安定した環境では 1〜5 時間。K8s/ローリングデプロイでは 5〜15 分。無期限にはしないでください。	短すぎる場合 (< 1m): 接続の張り直しが頻発し、レイテンシーが増加します。長すぎる場合 / 無期限の場合: 古い接続が残り、DNS の変更が反映されず、トラフィックも再分散されません。
ConnMaxIdleTime	time.Duration	0 (なし)	—	database/sql のみ	接続が idle 状態のままでいられる最大時間。この時間を超えると接続は閉じられます。Options 構造体には含まれないため、db.SetConnMaxIdleTime() で設定します。	K8s や断続的に負荷が発生するワークロードでは、トラフィックスパイク後にアイドル接続を回収するため 5〜10 分。	未設定の場合: アイドル接続は ConnMaxLifetime まで維持されます。短すぎる場合 (< 30s): 通常のギャップ中でも接続が再作成されます。

database/sql のみ

ConnMaxIdleTime は標準の Go database/sql の接続プール設定です。clickhouse.Options 構造体や clickhouse.Open() からは利用できません。OpenDB() の後に設定してください。

db := clickhouse.OpenDB(&clickhouse.Options{...})
db.SetConnMaxIdleTime(5 * time.Minute)

使用方法の詳細は 接続プーリング を参照してください。

---

​

標準の database/sql プール設定

clickhouse.OpenDB() または sql.Open("clickhouse", dsn) を使用すると、返される *sql.DB では Go の標準的なプールメソッドを利用できます。OpenDB() は Options の最初の 3 つを自動で適用します。

メソッド	Options での対応項目	備考
db.SetMaxIdleConns(n)	MaxIdleConns	OpenDB() によって自動適用されます
db.SetMaxOpenConns(n)	MaxOpenConns	OpenDB() によって自動適用されます
db.SetConnMaxLifetime(d)	ConnMaxLifetime	OpenDB() によって自動適用されます
db.SetConnMaxIdleTime(d)	None	作成後に手動で設定する必要があります

ClickHouse API (clickhouse.Open)

これらのメソッドは、clickhouse.Open() が返す接続では使用できません。ClickHouse API は Options 構造体のフィールドを直接使い、内部で独自にプールを管理します。

---

​

圧縮

オプション	型	デフォルト	DSN param	説明	ベストプラクティス	誤設定時
Compression.Method	CompressionMethod (byte)	None	compress (lz4, zstd, lz4hc, gzip, deflate, br, または LZ4 の場合は true)	データ転送時に使用する圧縮アルゴリズムです。下記のプロトコル対応表を参照してください。	LAN: None または LZ4。WAN: ZSTD または LZ4。CPU に制約がある場合: LZ4。最大圧縮: ZSTD (Native) または Brotli (HTTP)。1 MB 未満の挿入では省略します。	Native で GZIP/Brotli: ハンドシェイク失敗。HTTP で LZ4HC: エラーまたは暗黙的なフォールバック。低速ネットワークで圧縮なし: 挿入が 10〜100 倍遅くなります。
Compression.Level	int	3	compress_level	アルゴリズム固有の圧縮レベルです。GZIP/Deflate: -2〜9。Brotli: 0〜11。LZ4/ZSTD: 無視されます。	GZIP のバランス重視: 3〜6。Brotli のバランス重視: 4〜6。	非常に高いレベル: CPU 負荷が極端に高くなる一方、効果はわずかです。LZ4/ZSTD に 0 以外を指定: 暗黙的に無視されます。圧縮が有効でない状態で Level を指定しても効果はありません。
MaxCompressionBuffer	int (bytes)	10485760 (10 MiB)	max_compression_buffer	フラッシュ前の最大圧縮バッファサイズです。各接続はそれぞれ独自のバッファを持ちます。	デフォルトの 10 MiB で十分です。列数の多い行では 20〜50 MiB。合計メモリ = バッファ x MaxOpenConns。	小さすぎる場合 (< 1 MiB): フラッシュが頻発し、効率が低下します。大きすぎる場合 (> 100 MiB): 接続数が多いと OOM になります。

プロトコルごとの圧縮方式サポート:

Method	Native	HTTP
CompressionLZ4	はい	はい
CompressionLZ4HC	はい	いいえ
CompressionZSTD	はい	はい
CompressionGZIP	いいえ	はい
CompressionDeflate	いいえ	はい
CompressionBrotli	いいえ	はい

---

​

TLS

オプション	型	デフォルト	DSN パラメータ	説明	ベストプラクティス	誤設定時
TLS	*tls.Config	nil (平文)	secure=true, skip_verify=true	TLS/SSL の設定。nil 以外を指定すると TLS が有効になります。ポート: Native 9000/9440、HTTP 8123/8443。	本番環境および ClickHouse Cloud では常に有効にしてください (必須) 。本番環境では InsecureSkipVerify: false にしてください。カスタム CA は RootCAs で追加します。	ポートの指定誤り: "connection reset by peer"。本番環境で skip_verify=true: MITM 攻撃に対して脆弱。証明書の有効期限切れ: "x509: certificate has expired"。ホスト名の誤り: "x509: certificate is valid for X, not Y"。信頼されていない CA: "x509: certificate signed by unknown authority"。HTTP DSN に secure=true を付けた場合: 代わりに https:// スキームを使用してください。

コード例については TLS を参照してください。

---

​

ロギング

オプション	Type	Default	DSN param	説明	ベストプラクティス	誤設定時
Logger	*slog.Logger	nil (ログ出力なし)	—	Go の log/slog による構造化ロガー。優先順位: Debug+Debugf > Logger > no-op。(v2.43.0以降)	本番環境では JSON ハンドラーとともに slog を使用してください。logger.With(...) でアプリケーションのコンテキストを追加します。	—
Debug (deprecated)	bool	false	debug	従来のデバッグ切り替えです。代わりに Logger を使用してください。Debugf が設定されていない場合は標準出力にログを出力します。	—	本番環境で有効にすると、性能低下、冗長なログ出力、機密データが出力に含まれるリスクがあります。
Debugf (deprecated)	func(string, ...any)	nil	—	カスタムのデバッグログ関数です。代わりに Logger を使用してください。Debug: true が必要です。	—	—

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
conn, err := clickhouse.Open(&clickhouse.Options{
    Logger: logger,
    // ...
})

完全な例については、ロギングを参照してください。

---

​

バッファとメモリ

オプション	型	デフォルト	DSN パラメータ	クエリごと	説明	ベストプラクティス	設定を誤った場合
BlockBufferSize	uint8	2	block_buffer_size	はい (WithBlockBufferSize)	結果の読み取り時にバッファするデコード済みブロック数。読み取りとデコードの同時実行が可能になります。	デフォルトの 2 で問題ありません。大きなストリーミング結果では 5～10。メモリ = バッファ x ブロックサイズ x 同時実行クエリ数。	小さすぎる場合 (1): 読み取り側がブロックされ、レイテンシが増加します。大きすぎる場合 (> 50): メモリ使用量が増え、効果は頭打ちになります。
FreeBufOnConnRelease	bool	false	—	いいえ	再利用せず、各クエリの後に接続のメモリバッファを解放します。	クエリ頻度が高い場合は false。メモリに制約のあるコンテナー、または大きなバッチがまれな場合は true。	false + メモリ制限あり: バッファが蓄積します (メモリ = バッファ x アイドル接続数)。true + 高頻度: GC の負荷が増え、CPU 使用率が上がります。

---

​

HTTP固有

Native では暗黙的に無視されます

これらのオプションは Protocol: clickhouse.HTTP にのみ影響します。ネイティブプロトコルの使用時は暗黙的に無視され、エラーや警告は出力されません。

オプション	型	デフォルト	DSN パラメータ	説明	ベストプラクティス	設定を誤ると
HttpHeaders	map[string]string	nil	—	すべてのリクエストに追加される HTTP ヘッダー	トレーシング (X-Request-ID) や認証プロキシのヘッダーに使用します。必要最小限にとどめてください。	内部ヘッダー (Content-Type、Authorization) を上書きすると、予期しない動作を招く可能性があります。
HttpUrlPath	string	""	http_path	リクエストに付加される URL パス。先頭の / は自動的に追加されます。	パスルーティングを行うリバースプロキシの背後にある場合に使用します。	パスが誤っていると、プロキシ/LB から HTTP 404 が返されます。
HttpMaxConnsPerHost	int	0 (無制限)	—	トランスポート層におけるホストごとの TCP 接続数 (http.Transport.MaxConnsPerHost) 。	ほとんどのアプリでは 0 のままにしてください。サーバーに厳しい接続制限がある場合にのみ設定します。	低すぎる場合 (例: MaxOpenConns=50 で 10) 、トランスポートがボトルネックとなり、サーバー負荷が低くてもクエリが遅くなります。
HTTPProxyURL	*url.URL	nil (環境変数を使用)	http_proxy (URL エンコード)	リクエストのルーティングに使用する HTTP プロキシ	プロキシが必要な場合は明示的に設定してください。HTTP_PROXY/HTTPS_PROXY 環境変数より優先されます。	アドレスが誤っている場合: "dial tcp: lookup proxy: no such host"。プロキシに認証が必要な場合: HTTP 407。
TransportFunc	func(*http.Transport) (http.RoundTripper, error)	nil	—	カスタム HTTP トランスポートファクトリ。ラップ用にデフォルトのトランスポートを受け取ります。(v2.41.0 以降)	オブザーバビリティ用のミドルウェアに使用します。Proxy、DialContext、TLSClientConfig は上書きしないでください。	nil を返すと panic になります。クライアントフィールドを上書きすると、TLS/プロキシは暗黙的に無視されます。RoundTripper をブロックするとデッドロックが発生します。

HTTP の 2 層接続プール

HTTP を使用する場合、接続プールは 2 つあります。

• 第 1 層 (アプリケーション) : MaxIdleConns / MaxOpenConns — httpConnect オブジェクトを制御します
• 第 2 層 (トランスポート) : HttpMaxConnsPerHost — 基盤となる TCP 接続を制御します

ネイティブプロトコルは単純な 1:1 の対応となるため、HttpMaxConnsPerHost は無視されます。

TransportFunc: func(t *http.Transport) (http.RoundTripper, error) {
    return &loggingRoundTripper{transport: t}, nil
}

---

​

高度な接続

オプション	型	デフォルト	DSN パラメータ	説明	ベストプラクティス	設定を誤った場合
DialContext	func(ctx, addr) (net.Conn, error)	nil (標準ダイヤラー)	—	TCP connection 用のカスタムダイヤル関数です。Native と HTTP の両方で利用できます。	99% のケースでは nil のままにしてください。Unixソケット、SOCKSプロキシ、カスタムDNSで使用します。	コンテキストを適切に扱わないと、ハングやリソースリークが発生します。TLS を設定している場合、カスタムダイヤラー側で TLS を処理する必要があります。不正な net.Conn を返すとクラッシュします。
DialStrategy	func(ctx, connID, options, dial) (DialResult, error)	DefaultDialStrategy	—	カスタムのサーバー選択および接続戦略です。ConnOpenStrategy をオーバーライドします。	99.9% のケースではデフォルトを使用してください。カスタマイズは、地理情報に基づくルーティング、重み付き選択、ヘルスチェックの場合に限ります。	すべてのサーバーを試行しないと、正常なサーバーが利用可能でも失敗します。内部で高コストな処理を行うと、接続のたびにプール取得がブロックされます。

---

​

クライアント情報

Option	Type	Default	DSN param	Per-query	Description	Best practice	When misconfigured
ClientInfo	ClientInfo struct	自動: clickhouse-go のバージョン + Goランタイム	client_info_product=myapp/1.0	はい (WithClientInfo で追記)	ClickHouse に送信されるアプリケーション識別情報です。Products ([]struct{Name,Version}) と Comment ([]string) が含まれます。system.query_log で確認できます。	アプリ名とバージョンは必ず設定してください。クエリの発行元特定: SELECT client_name FROM system.query_log WHERE client_name LIKE '%myapp%'	未設定の場合: 複数のサービスがある環境では、どのサービスがクエリを発行したか特定できません。

ClientInfo: clickhouse.ClientInfo{
    Products: []struct{ Name, Version string }{
        {Name: "my-service", Version: "1.0.0"},
    },
}
// 表示例: clickhouse-go/2.x my-service/1.0.0 (lv:go/1.23; os:linux)

---

​

ClickHouse サーバー設定

Option	Type	Default	DSN param	Per-query	Description	Best practice	When misconfigured
Settings	map[string]any	nil	認識されない任意のパラメータ (例: ?max_execution_time=60)	はい (WithSettings。競合時はコンテキストが優先)	すべてのクエリに適用される ClickHouse サーバー設定です。DSN の変換: "true"→1、"false"→0、数値→int。	共通の制限は接続レベルで設定し、必要に応じてコンテキスト経由でクエリごとに上書きします。	タイポ: バージョンによっては黙って無視されるか、エラーになります。型が不正: "Cannot parse string 'abc' as Int64"。max_execution_time=0 かつ期限なし: クエリが無期限に実行されます。
CustomSetting	CustomSetting{Value string}	—	—	はい (WithSettings 経由)	ネイティブプロトコルでは、設定を “custom” (重要ではない) としてマークします。サーバーが認識しなくてもエラーにはなりません。HTTP では、デフォルトですべての設定が custom として扱われます。	Experimental な設定やバージョン固有の設定に使用します。	重要な設定を custom として指定すると、未対応の場合でも黙って無視されます。

一般的な設定:

Setting	Type	Description
max_execution_time	int	クエリのタイムアウト (秒)
max_memory_usage	int	クエリごとのメモリ制限 (バイト)
max_block_size	int	処理時の block サイズ
readonly	int	1 = read-only、2 = read-only + 設定変更

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // 重要 -- 不明な場合はエラー
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // カスタム -- 不明な場合は無視
}

---

​

Context レベルのクエリオプション

各クエリに対して clickhouse.Context() を使って設定します。

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)

コンテキストのデッドラインの挙動

コンテキストのデッドラインが > 1 秒の場合、max_execution_time は自動的に seconds_remaining + 5 に設定されます。手動で設定した値は上書きされます。

オプション	型	デフォルト	プロトコル	説明	ベストプラクティス	誤設定時
WithQueryID	string	自動生成	両方	カスタムのクエリ ID。system.query_log と system.processes に表示されます。	UUIDを使用してください。KILL QUERY WHERE query_id='...' を使う際に便利です。	重複した ID: system.query_log で混乱を招きます。
WithQuotaKey	string	""	両方	マルチテナント環境のリソース制限用のQUOTAキーです。サーバー側でQUOTAを設定しておく必要があります。	顧客単位またはユーザー単位の制限に使用します。	Quota が設定されていない場合は、そのまま無視されます。
WithJWT	string	""	HTTPS のみ	ClickHouse Cloud 向けのクエリ単位の JWT オーバーライド。 (v2.35.0 以降)	マルチテナントプロキシでのリクエスト単位の認証に使用します。	TLS を使用しない場合は無視され、接続認証にフォールバックします。期限切れ: "Token has expired".
WithSettings	Settings	接続の設定を継承	両方	クエリごとのサーバー設定。接続設定とマージされ、競合時はコンテキストが優先されます。	クエリタイプごとに max_execution_time または max_rows_to_read の設定を上書きします。	接続レベルのSettingsと同様です。
WithParameters	Parameters (map[string]string)	nil	両方	サーバー側のパラメータ化クエリに渡す値。クエリ構文: {param_name:Type}。	SQLインジェクションを防ぐため、文字列連結の代わりに使用します。	パラメータがありません: "Substitution {param_name:Type} isn't set"。型が不正です: "Cannot parse string 'abc' as UInt64"。
WithAsync	bool (wait)	同期	両方	非同期 INSERT モードです。async_insert=1 を設定します。wait=true を指定すると、wait_for_async_insert=1 も設定されます。ClickHouse 21.11+ が必要です。(v2.41.0 以降。旧 WithStdAsync の後継です。)	高スループットの挿入に使用します。	wait=false: エラーは非同期で発生する場合があります — system.asynchronous_insert_log を確認してください。SELECT では無視されます。古いサーバー: "Unknown setting async_insert"。
WithLogs	func(*Log)	nil	Native のみ	クエリ実行中のサーバーログエントリのコールバック。	高速に保ってください。実行をブロックするため、負荷の高い処理には goroutine を使用してください。	HTTP では、何の通知もなく呼び出されません。
WithProgress	func(*Progress)	nil	Native のみ	クエリの進捗更新 (処理済みの行数/バイト数) 。	高速に保ってください — 実行がブロックされます。	HTTP では、何の通知もなく呼び出されません。
WithProfileInfo	func(*ProfileInfo)	nil	Native のみ	クエリ実行統計情報のコールバック。	高速に保ってください。実行をブロックします。	HTTP では: 呼び出されません (通知もありません) 。
WithProfileEvents	func([]ProfileEvent)	nil	Native のみ	パフォーマンスカウンターのコールバック。	高速に保つこと — 実行をブロックします。	HTTP では、何の通知もなく一度も呼び出されません。
WithoutProfileEvents	—	イベントを送信	Native のみ	プロファイルイベントを無効化します。サーバー 25.11 以降でのパフォーマンス最適化です。 (v2.44.0 以降)	プロファイルイベントが不要な場合に使用します。	古いサーバーでは: 不明な設定としてエラーになります。
WithExternalTable	...*ext.Table	nil	両方	一時的なルックアップテーブルをクエリにアタッチします。データはクエリごとに転送されます。	テーブルは < 10 MB に抑えてください。HTTP (multipart) より native のほうが効率的です。	大きなテーブル: クエリごとにネットワークオーバーヘッドが発生します。
WithUserLocation	*time.Location	サーバーのタイムゾーン	両方	DateTime のパース時に timezone を上書きします。	クライアントとサーバーの timezone が異なる場合は、明示的に設定します。	timezone が誤っていると、DateTime の値が気付かないうちに数時間ずれ、データ破損につながるおそれがあります。
WithColumnNamesAndTypes	[]ColumnNameAndType	nil (DESCRIBEを実行)	HTTPのみ	カラム情報を事前に指定することで、HTTPで insert する際の DESCRIBE TABLE の往復を省略します。 (v2.37.0以降)	スキーマが既知で安定している場合に使用します。	型の不一致: "Cannot convert String to UInt64"。移行後のスキーマドリフト: 情報が古くなります。
WithBlockBufferSize	uint8	接続レベル (2)	両方	接続レベルで設定されたBlockBufferSizeを、単一のクエリに対して上書きします。	特定のクエリでresult setが大きい場合に増やします。	—
WithClientInfo	ClientInfo	接続レベル	両方	単一のクエリに追加のクライアント情報を付加します。置き換えるのではなく、追加します。(v2.42.0 以降)	リクエストごとのコンテキスト (例：エンドポイント名) を追加します。	—
WithSpan	trace.SpanContext	空	ネイティブのみ	分散トレーシング用の OpenTelemetry span コンテキスト。	OpenTelemetryを参照してください。	—

ctx := clickhouse.Context(ctx,
    clickhouse.WithQueryID("query-123"),
    clickhouse.WithParameters(clickhouse.Parameters{
        "user_id": "12345",
    }),
    clickhouse.WithProgress(func(p *clickhouse.Progress) {
        log.Printf("Progress: %d rows, %d bytes", p.Rows, p.Bytes)
    }),
)
rows, err := conn.Query(ctx, "SELECT * FROM users WHERE id = {user_id:String}")

---

​

バッチオプション

PrepareBatch() に渡すオプションです。インポート: github.com/ClickHouse/clickhouse-go/v2/lib/driver.

Option	Default	Description	Best practice	When misconfigured
WithReleaseConnection	Send() まで接続を保持	PrepareBatch() の直後に接続をプールへ解放します。Send()/Flush() 時に再取得します。	プール枯渇を防ぐため、長時間保持するバッチ (数分〜数時間) で使用します。	長時間のバッチで使用しない場合: アクティブなものが多いと "acquire conn timeout" が発生します。
WithCloseOnFlush	バッチは開いたまま	Flush() を呼び出すとバッチを自動的に閉じます。	単発のバッチで使用します。明示的な Close() が不要になります。	複数回 Flush() を呼び出す用途で使用すると、最初の flush でバッチが閉じられ、以降の操作は失敗します。

batch, err := conn.PrepareBatch(ctx, "INSERT INTO table",
    driver.WithReleaseConnection(),
    driver.WithCloseOnFlush(),
)

---

​

早見表

​

接続プールのサイズ設定の推奨値

アプリケーション種別	MaxIdleConns	MaxOpenConns	ConnMaxLifetime
低トラフィックのWebアプリ	5	10	1h
中程度のトラフィックのAPI	20	50	30m
高トラフィックのサービス	50	100	15m
バックグラウンド バッチジョブ	10	20	2h
Kubernetesデプロイメント	10	20	10m
サーバーレス (Lambda)	1	5	5m

​

タイムアウトの推奨値

環境	DialTimeout	ReadTimeout
ローカル / LAN	5s	30s
Cloud (同一リージョン)	10s	2m
Cloud (クロスリージョン)	30s	5m
OLAPワークロード	10s	30m
リアルタイム / OLTP	5s	10s

​

DSN パラメータ早見表

DSN パラメータ	Options のフィールド	例
username	Auth.Username	?username=admin
password	Auth.Password	?password=secret
database	Auth.Database	?database=mydb またはパス中の /mydb
dial_timeout	DialTimeout	?dial_timeout=10s
read_timeout	ReadTimeout	?read_timeout=5m
max_open_conns	MaxOpenConns	?max_open_conns=50
max_idle_conns	MaxIdleConns	?max_idle_conns=20
conn_max_lifetime	ConnMaxLifetime	?conn_max_lifetime=30m
connection_open_strategy	ConnOpenStrategy	?connection_open_strategy=round_robin
block_buffer_size	BlockBufferSize	?block_buffer_size=10
compress	Compression.Method	?compress=lz4
compress_level	Compression.Level	?compress_level=6
max_compression_buffer	MaxCompressionBuffer	?max_compression_buffer=20971520
secure	TLS	?secure=true
skip_verify	TLS.InsecureSkipVerify	?skip_verify=true
debug	Debug	?debug=true
client_info_product	ClientInfo.Products	?client_info_product=myapp/1.0
http_proxy	HTTPProxyURL	?http_proxy=http%3A%2F%2Fproxy%3A8080
http_path	HttpUrlPath	?http_path=/clickhouse
(その他)	Settings[key]	?max_execution_time=60

---

​

トラブルシューティング

​

接続プールの枯渇: “acquire conn timeout”

原因: 接続プールが枯渇しています。MaxOpenConns で許可されたすべての接続が使用中で、DialTimeout 内に空きが出ませんでした。

対処方法

次の手順を順番に試し、調整項目を変更する前に根本原因を切り分けてください。

1. 接続を占有している長時間実行中のクエリがないか確認します: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC。見つかった場合は、まずその低速なクエリへの対処を優先してください。
2. 長時間存続するバッチ (PrepareBatch() から Send() までが数分～数時間) を実行している場合は、WithReleaseConnection() を使用して、バッチを開いたままでも接続をプールに戻してください。
3. 実際に観測された同時実行数に合わせて MaxOpenConns を増やします。
4. バーストが想定され、接続取得の待ち時間が実際のボトルネックである場合にのみ、DialTimeout を増やします。

​

読み取りタイムアウトおよび接続リセットエラー

原因: サーバーからの応答を待っている間に ReadTimeout を超過したか、サーバーまたはネットワークによって connection が切断されました。

対処法:

• 長時間実行されるクエリでは ReadTimeout を増やします
• クエリごとの timeout 制御には context の deadline を使用します
• ClickHouse のサーバー側 max_execution_time 制限を確認します

​

”Code: 516. 認証に失敗しました”

原因: username または password が誤っているか、ユーザーが存在しません。

対処:

• system.users table で認証情報を確認する
• DSN の password に含まれる特殊文字の URL エンコードに問題がないか確認する
• ユーザーに、指定した database へのアクセス権があることを確認する

​

TLS 証明書エラー

エラー	原因	修正方法
x509: certificate has expired	サーバー証明書の有効期限切れ	サーバー証明書を更新する
x509: certificate is valid for X, not Y	ホスト名の不一致	正しいホスト名を使用するか、SAN に追加する
x509: certificate signed by unknown authority	信頼されていない CA	CA を tls.Config.RootCAs に追加する
connection reset by peer	TLS とポートの不一致	TLS にはポート 9440 (Native) または 8443 (HTTP) を使用する

​

徐々に増えるメモリ使用量

原因: 大きなアイドル状態の接続バッファが蓄積している。

対処:

• メモリが限られる環境では FreeBufOnConnRelease: true を設定する
• アイドル接続を制限するために MaxIdleConns を減らす
• 圧縮を使用している場合は MaxCompressionBuffer を減らす
• 接続をより頻繁に入れ替えるために ConnMaxLifetime を短くする