Configuración - ClickHouse Documentation

Ajustes de conexión

Para un análisis detallado y completo de cada opción, con valores predeterminados, parámetros DSN, buenas prácticas y solución de problemas, consulta la Referencia de configuración.

Al abrir una conexión, se puede usar una estructura Options para controlar el comportamiento del cliente. Están disponibles los siguientes ajustes:

Parámetro	Tipo	Predeterminado	Descripción
`Protocol`	`Protocol`	`Native`	Protocolo de transporte: `Native` (TCP) o `HTTP`. Consulta TCP vs HTTP.
`Addr`	`[]string`	—	Slice de direcciones `host:port`. Para varios nodos, consulta conexión a varios nodos.
`Auth`	`Auth`	—	Credenciales de autenticación (`Database`, `Username`, `Password`). Consulta Autenticación.
`TLS`	`*tls.Config`	`nil`	Configuración de TLS. Un valor distinto de `nil` habilita TLS. Consulta TLS.
`DialContext`	`func(ctx, addr) (net.Conn, error)`	—	Función personalizada para controlar cómo se establecen las conexiones TCP.
`DialTimeout`	`time.Duration`	`30s`	Tiempo máximo de espera al abrir una conexión nueva.
`MaxOpenConns`	`int`	`MaxIdleConns + 5`	Número máximo de conexiones abiertas en un momento dado.
`MaxIdleConns`	`int`	`5`	Número de conexiones inactivas que se mantienen en el grupo.
`ConnMaxLifetime`	`time.Duration`	`1h`	Tiempo de vida máximo de una conexión del grupo. Consulta pool de conexiones.
`ConnOpenStrategy`	`ConnOpenStrategy`	`ConnOpenInOrder`	Estrategia para elegir un nodo de `Addr`. Consulta conexión a varios nodos.
`BlockBufferSize`	`uint8`	`2`	Número de bloques que se decodifican en paralelo. Los valores más altos aumentan el rendimiento a costa de más memoria. Se puede sobrescribir por consulta mediante el contexto.
`Settings`	`Settings`	—	Mapa de ajuste de ClickHouse aplicados a cada consulta. Las consultas individuales pueden sobrescribirlos mediante context.
`Compression`	`*Compression`	`nil`	Compresión a nivel de bloque. Consulta compresión.
`ReadTimeout`	`time.Duration`	—	Tiempo máximo de espera para una lectura del servidor en una sola llamada.
`FreeBufOnConnRelease`	`bool`	`false`	Si es `true`, libera el búfer de memoria de la conexión de vuelta al grupo en cada consulta. Reduce el uso de memoria con un pequeño coste de CPU.
`Logger`	`*slog.Logger`	`nil`	Logger estructurado (Go `log/slog`). Consulta registro.
`Debug`	`bool`	`false`	Obsoleto. Usa `Logger` en su lugar. Habilita la salida de depuración heredada a stdout.
`Debugf`	`func(string, ...any)`	—	Obsoleto. Usa `Logger` en su lugar. Función personalizada de registro de depuración. Requiere `Debug: true`.
`GetJWT`	`GetJWTFunc`	—	Callback que devuelve un token JWT para la autenticación de ClickHouse Cloud (solo HTTPS).
`HttpHeaders`	`map[string]string`	—	Headers HTTP adicionales enviados en cada solicitud (solo transporte HTTP).
`HttpUrlPath`	`string`	—	Ruta URL adicional añadida a las solicitudes HTTP (solo transporte HTTP).
`HttpMaxConnsPerHost`	`int`	—	Sobrescribe `MaxConnsPerHost` en el `http.Transport` subyacente (solo transporte HTTP).
`TransportFunc`	`func(*http.Transport) (http.RoundTripper, error)`	—	Fábrica personalizada de transporte HTTP. El transporte predeterminado se pasa para aplicar sobrescrituras selectivas (solo transporte HTTP).
`HTTPProxyURL`	`*url.URL`	—	URL del proxy HTTP para todas las solicitudes (solo transporte 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
}

Ejemplo completo

TLS

A bajo nivel, todos los métodos de conexión del cliente (DSN/OpenDB/Open) usarán el paquete tls de Go para establecer una conexión segura. El cliente sabe que debe usar TLS si la estructura Options contiene un puntero tls.Config distinto de nil.

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

Ejemplo completo Esta configuración mínima de TLS.Config suele ser suficiente para conectarse al puerto nativo seguro (normalmente, el 9440) de un servidor ClickHouse. Si el servidor ClickHouse no tiene un certificado válido (caducado, con un hostname incorrecto o no firmado por una autoridad de certificación raíz reconocida públicamente), InsecureSkipVerify puede establecerse en true, pero se desaconseja encarecidamente.

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

Ejemplo completo Si se necesitan parámetros de TLS adicionales, el código de la aplicación debe configurar los campos deseados en la estructura tls.Config. Esto puede incluir conjuntos de cifrado específicos, forzar una versión concreta de TLS (como 1.2 o 1.3), añadir una cadena interna de certificados de una CA, añadir un certificado de cliente (y su clave privada) si lo requiere el ClickHouse server, y la mayoría de las demás opciones propias de una configuración de seguridad más especializada.

Autenticación

Especifique una estructura Auth en los detalles de conexión para definir un nombre de usuario y una contraseña.

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

Ejemplo completo

Conexión a varios nodos

Se pueden especificar varias direcciones mediante la estructura 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())

Ejemplo completo Hay tres estrategias de conexión disponibles:

ConnOpenInOrder (predeterminada) - las direcciones se recorren en orden. Las direcciones posteriores solo se utilizan si falla la conexión con las direcciones anteriores de la lista. En la práctica, se trata de una estrategia de conmutación por error.
ConnOpenRoundRobin - La carga se distribuye entre las direcciones mediante una estrategia round-robin.
ConnOpenRandom - Se selecciona un nodo aleatoriamente de la lista de direcciones.

Esto se puede controlar mediante la opción 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
}

Ejemplo completo

Pool de conexiones

El cliente mantiene un pool de conexiones y las reutiliza entre consultas según sea necesario. Como máximo, se usará MaxOpenConns en un momento dado, y MaxIdleConns controla el tamaño máximo del pool. El cliente obtiene una conexión del pool para cada ejecución de consulta y la devuelve al pool para reutilizarla. Una conexión se usa durante toda la vida útil de un batch y se libera en Send(). No se garantiza que se use la misma conexión del pool en consultas posteriores, a menos que el usuario establezca MaxOpenConns=1. Esto rara vez es necesario, pero puede serlo en casos en los que se usen tablas temporales. Además, tenga en cuenta que ConnMaxLifetime es, de forma predeterminada, de 1 h. Esto puede hacer que la carga en ClickHouse se desequilibre si algunos nodos abandonan el cluster. Esto puede ocurrir cuando un nodo deja de estar disponible; las conexiones se redistribuyen entre los demás nodos. Estas conexiones persistirán y no se actualizarán durante 1 h de forma predeterminada, incluso si el nodo problemático vuelve al cluster. Considere reducir este valor en casos de workload elevado. La agrupación de conexiones está habilitada tanto para Native (TCP) como para el protocolo HTTP.

Registro

El cliente admite el registro estructurado a través del paquete estándar log/slog de Go mediante el campo Logger de Options. Los campos Debug y Debugf anteriores están obsoletos, pero siguen funcionando por compatibilidad con versiones anteriores (prioridad: Debugf > Logger > no-op).

import (
    "log/slog"
    "os"
)

// Registro estructurado en 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,
})

También puedes enriquecer el logger con contexto de la aplicación:

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

Ejemplo completo

Compresión

La compatibilidad con los métodos de compresión depende del protocolo subyacente que se utilice. En el protocolo nativo, el cliente admite compresión LZ4 y ZSTD. Esto se realiza únicamente a nivel de bloque. La compresión puede habilitarse añadiendo una configuración Compression a la conexión.

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
}

Ejemplo completo Hay técnicas de compresión adicionales disponibles cuando se usa el transporte HTTP: gzip, deflate y br. Consulta Base de datos/API SQL: compresión para obtener más detalles.

TCP vs HTTP

El transporte se cambia con una sola opción de configuración; todo lo demás de esta guía se aplica a ambos. Esto es lo que cambia:

	TCP (protocolo nativo)	HTTP
Puerto predeterminado	9000 (sin cifrado), 9440 (TLS)	8123 (sin cifrado), 8443 (TLS)
Habilitar	Predeterminado: omita `Protocol`	`Protocol: clickhouse.HTTP` o use un DSN `http://`
Compresión	`lz4`, `zstd`	`lz4`, `zstd`, `gzip`, `deflate`, `br`
Sesiones	Integradas (siempre activas)	Explícitas: pase `session_id` como ajuste
header HTTP	—	`HttpHeaders`, `HttpUrlPath`, `HttpMaxConnsPerHost`
Transporte personalizado	—	`TransportFunc`
Autenticación JWT	—	`GetJWT` (HTTPS de ClickHouse Cloud)
OpenTelemetry (`WithSpan`)	✅	El servidor lo admite; el cliente aún no envía el header `traceparent`

Para cambiar cualquiera de las dos API a HTTP:

// ClickHouse API sobre HTTP
conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... autenticación, etc.
})

// database/sql sobre HTTP — mediante Options
conn := clickhouse.OpenDB(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... autenticación, etc.
})

// database/sql sobre HTTP — mediante DSN
conn, err := sql.Open("clickhouse", "http://host:8123?username=user&password=pass")

​Ajustes de conexión

​TLS

​Autenticación

​Conexión a varios nodos

​Pool de conexiones

​Registro

​Compresión

​TCP vs HTTP

Ajustes de conexión

TLS

Autenticación

Conexión a varios nodos

Pool de conexiones

Registro

Compresión

TCP vs HTTP