Configuración

Configuración del cliente clickhouse-go: opciones de conexión, TLS, autenticación, pool de conexiones, logging y compresión.

​

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