Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Configuración

View as MarkdownEdit this pageReport an issueSet up docs MCP

Ajustes de conexió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. Auméntalo a 1m–2m al conectarte a un servicio de ClickHouse Cloud que pueda estar inactivo; consulta Timeouts.
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")
Navigation