Referência de configuração do cliente Go

Esta página documenta todas as opções configuráveis do clickhouse-go v2.x. Para um guia com exemplos de código, consulte Configuração.

As opções existem em três escopos:

Quando os escopos se sobrepõem, o escopo mais específico prevalece: Lote > Consulta > Conexão. Para Settings, as chaves no nível da consulta são mescladas com as chaves no nível da conexão; em caso de conflito, prevalece o nível da consulta.

Via a struct 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},
})

Via string de conexão DSN:

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

Por meio do conector (database/sql com a struct Options):

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Defina as configurações de pool exclusivas do database/sql após a criação
db.SetConnMaxIdleTime(5 * time.Minute)

Por meio do contexto (por consulta):

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

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

Consulte Pool de conexões para mais detalhes de uso.

Ao usar clickhouse.OpenDB() ou sql.Open("clickhouse", dsn), o *sql.DB retornado é compatível com os métodos padrão de pool do Go. OpenDB() aplica automaticamente os três primeiros com base em Options:

Suporte a métodos de compressão por protocolo:

Consulte TLS para ver exemplos de código.

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

Consulte Logging para ver exemplos completos.

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

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

Configurações comuns:

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // importante -- retorna erro se desconhecido
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // personalizado -- ignorado se desconhecido
}

Configure por consulta com 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}")

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

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

Causa: Pool de conexões esgotado — todas as conexões de MaxOpenConns estão em uso, e nenhuma foi liberada dentro de DialTimeout.

Correção

Tente as etapas a seguir em ordem e identifique a causa raiz antes de ajustar os parâmetros:

1. Verifique se há consultas de longa execução mantendo conexões ocupadas: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. Se encontrar alguma, resolva primeiro as consultas lentas.
2. Se você executa lotes de longa duração (minutos/horas entre PrepareBatch() e Send()), use WithReleaseConnection() para devolver a conexão ao pool enquanto o lote estiver aberto.
3. Aumente MaxOpenConns para acompanhar a concorrência observada.
4. Aumente DialTimeout apenas se forem esperados picos de uso e a espera para adquirir conexão for o verdadeiro gargalo.

Causa: ReadTimeout foi excedido enquanto se aguardava uma resposta do servidor, ou a conexão foi fechada pelo servidor/rede.

Correção:

• Aumente o ReadTimeout para consultas de longa duração
• Use prazos de contexto para controlar o timeout por consulta
• Verifique os limites de max_execution_time no lado do servidor do ClickHouse

Causa: Nome de usuário ou senha incorretos, ou o usuário não existe.

Correção:

• Verifique as credenciais na tabela system.users
• Verifique se há problemas de codificação de URL com caracteres especiais nas senhas do DSN
• Confirme se o usuário tem acesso ao banco de dados especificado

Causa: Acúmulo de buffers grandes em conexões ociosas.

Correção:

• Defina FreeBufOnConnRelease: true em ambientes com memória limitada
• Reduza MaxIdleConns para limitar o número de conexões ociosas
• Reduza MaxCompressionBuffer se estiver usando compressão
• Diminua ConnMaxLifetime para reciclar as conexões com mais frequência