Go-client configuration reference

This page documents every configurable option in clickhouse-go v2.x. For a guide with code examples, see Configuration.

How options are set

Options exist at three scopes:

Where scopes overlap, the more specific scope wins: Batch > Query > Connection. For Settings, query-level keys are merged with connection-level keys and query-level wins on conflict.

Via Options struct:

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

Via DSN string:

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

Via Connector (database/sql with Options struct):

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Set database/sql-only pool settings after creation
db.SetConnMaxIdleTime(5 * time.Minute)

Via context (per-query):

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

Connection options

Protocol and connection

Authentication

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

Timeouts

Connection pool

See Connection Pooling for usage details.

Standard database/sql pool settings

When using clickhouse.OpenDB() or sql.Open("clickhouse", dsn), the returned *sql.DB supports Go’s standard pool methods. OpenDB() auto-applies the first three from Options:

Compression

Compression method support by protocol:

TLS

See TLS for code examples.

Logging

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

See Logging for full examples.

Buffers and memory

HTTP-specific

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

Advanced connection

Client information

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

ClickHouse server settings

Common settings:

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // important -- errors if unknown
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // custom -- ignored if unknown
}

Context-level query options

Set per-query using clickhouse.Context():

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

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

Batch options

Passed to PrepareBatch(). Import: github.com/ClickHouse/clickhouse-go/v2/lib/driver.

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

Quick reference tables

Connection pool sizing recommendations

Timeout recommendations

DSN parameter quick reference

Troubleshooting

Connection pool exhausted: “acquire conn timeout”

Cause: Connection pool exhausted - all MaxOpenConns connections are in use and none became available within DialTimeout.

Fix

Try the following steps in order, and diagnose the root cause before tuning knobs:

1. Check for long-running queries holding connections: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. If found, address the slow queries first.
2. If you run long-lived batches (minutes/hours between PrepareBatch() and Send()), use WithReleaseConnection() to return the connection to the pool while the batch is open.
3. Increase MaxOpenConns to match observed concurrency.
4. Increase DialTimeout only if bursts are expected and acquisition wait is the actual bottleneck.

Read timeout and connection reset errors

Cause: ReadTimeout exceeded while waiting for a server response, or the connection was closed by the server/network.

Fix:

• Increase ReadTimeout for long-running queries
• Use context deadlines for per-query timeout control
• Check ClickHouse server-side max_execution_time limits

“Code: 516. Authentication failed”

Cause: Wrong username, password, or the user doesn’t exist.

Fix:

• Verify credentials against system.users table
• Check for URL-encoding issues with special characters in DSN passwords
• Confirm the user has access to the specified database

TLS certificate errors

Gradual memory growth

Cause: Large idle connection buffers accumulating.

Fix:

• Set FreeBufOnConnRelease: true in memory-constrained environments
• Reduce MaxIdleConns to limit idle connections
• Reduce MaxCompressionBuffer if using compression
• Lower ConnMaxLifetime to cycle connections more frequently