Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

配置

View as MarkdownEdit this pageReport an issueSet up docs MCP

连接设置

打开连接时，可以使用 Options 结构体来控制客户端行为。可用设置如下：

参数 类型 默认值 说明
Protocol Protocol Native 传输协议：Native (TCP) 或 HTTP。请参阅 TCP 与 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 连接的建立方式。
DialTimeout time.Duration 30s 打开新连接时的最大等待时间。连接到可能处于空闲状态的 ClickHouse Cloud 服务时，请将其提高到 1m–2m——请参阅 超时。
MaxOpenConns int MaxIdleConns + 5 任意时刻允许打开的最大连接数。
MaxIdleConns int 5 连接池中保留的空闲连接数。
ConnMaxLifetime time.Duration 1h 连接池中连接的最大存活时间。请参阅 连接池。
ConnOpenStrategy ConnOpenStrategy ConnOpenInOrder 从 Addr 中选择节点的策略。请参阅 连接到多个节点。
BlockBufferSize uint8 2 并行解码的块数。值越高，吞吐量越高，但内存开销也会增加。可通过上下文按查询覆盖。
Settings Settings — 应用于每个查询的 ClickHouse 设置映射。单个查询可通过 context 覆盖。
Compression *Compression nil 块级压缩。请参阅 压缩。
ReadTimeout time.Duration — 单次调用中，从服务器读取数据时的最大等待时间。
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 传输) 。
HttpUrlPath string — 附加到 HTTP 请求中的额外 URL 路径 (仅 HTTP 传输) 。
HttpMaxConnsPerHost int — 覆盖底层 http.Transport 中的 MaxConnsPerHost (仅 HTTP 传输) 。
TransportFunc func(*http.Transport) (http.RoundTripper, error) — 自定义 HTTP 传输工厂。会传入默认 transport 以便有选择地进行覆盖 (仅 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 结构体中包含一个非空的 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 server 的安全 native 端口 (通常为 9440) 。如果 ClickHouse server 没有有效的证书 (例如证书已过期、hostname 不匹配，或不是由公开认可的根证书颁发机构签发) ，则可以将 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 server 要求时添加客户端证书 (及其私钥) ，还包括更专门的安全配置中的大多数其他选项。

身份验证

在连接详细信息中指定 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())

完整示例

提供三种连接策略：

  • 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 > 空操作) 。

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 - 压缩。

TCP 与 HTTP

传输方式只需切换一个配置项——本指南中的其余内容对两者都适用。区别如下：

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