Referencia de configuración del cliente Go

Esta página documenta todas las opciones configurables de clickhouse-go v2.x. Para ver una guía con ejemplos de código, consulta Configuración.

Anotaciones de versiónLas opciones añadidas en clickhouse-go v2.35.0 o versiones posteriores están marcadas con (Desde vX.Y.Z) junto a su descripción. Las opciones sin la etiqueta “Desde” están disponibles desde la v2.0 y están presentes en todas las versiones compatibles.

Cómo se configuran las opciones

Las opciones existen en tres ámbitos:

Ámbito	Cómo configurarlo	Duración
Conexión	estructura `clickhouse.Options` o cadena DSN	Todas las consultas de la conexión
Consulta	`clickhouse.Context()` con funciones `WithXxx`	Ejecución de una sola consulta
Lote	funciones de opción de `PrepareBatch()`	Operación de un solo lote

Cuando los ámbitos se superponen, prevalece el más específico: Lote > Consulta > Conexión. Para Settings, las claves del nivel de consulta se combinan con las del nivel de conexión y, en caso de conflicto, prevalecen las del nivel de consulta. Mediante la estructura 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},
})

Mediante una cadena DSN:

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

A través de Connector (database/sql con la estructura Options):

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Establecer configuraciones de pool exclusivas de database/sql tras la creación
db.SetConnMaxIdleTime(5 * time.Minute)

A través del 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 ...")

Opciones de conexión

Protocolo y conexión

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Cuando está mal configurado
`Protocol`	`Protocol` (int)	`Native`	Esquema: `clickhouse://`=Native, `http://`=HTTP	Protocolo de comunicación: `Native` (0) para TCP, `HTTP` (1) para HTTP	Use Native para obtener un rendimiento ~30% mejor. Use HTTP para compatibilidad con proxy, para atravesar firewalls (puerto 80/443) o para compresión disponible solo en HTTP (`gzip`/`br`). Consulte TCP vs HTTP.	Esquema HTTP con puerto Native (9000): conexión rechazada. Native bloqueado por el firewall: tiempos de espera agotados.
`Addr`	`[]string`	`["localhost:9000"]` (Native) `["localhost:8123"]` (HTTP)	Hosts separados por comas en la URL	Lista de direcciones `"host:port"` para la conexión y el failover	Especifique varias direcciones en producción para alta disponibilidad. Puertos correctos: 9000 (Native), 8123 (HTTP), 9440 (Native+TLS), 8443 (HTTP+TLS).	Una sola dirección: sin failover. Puerto incorrecto: `"connection refused"`. Vacío/nil: usa localhost de forma predeterminada y falla en despliegues distribuidos.
`ConnOpenStrategy`	`ConnOpenStrategy` (uint8)	`ConnOpenInOrder` (0)	`connection_open_strategy` (`in_order`, `round_robin`, `random`)	Estrategia para seleccionar un servidor de `Addr`. `InOrder` (0)=failover, `RoundRobin` (1)=balanceo de carga, `Random` (2)=aleatorio.	`InOrder` para activo-en-espera. `RoundRobin` para activo-activo/K8s. `Random` para evitar el efecto de avalancha.	`InOrder` con activo-activo: el primer servidor recibe toda la carga y los demás quedan inactivos. Todas las estrategias prueban todos los servidores si hay fallos; solo cambia cuál se prueba primero.

Autenticación

Option	Type	Default	DSN param	Description	Best practice	When misconfigured
`Auth.Username`	`string`	`"default"`	`username` or URL user portion	Nombre de usuario para la autenticación en ClickHouse	Nunca use `default` en producción. Cree usuarios específicos con permisos mínimos.	Nombre de usuario incorrecto: `"Code: 516. DB::Exception: Authentication failed"`. Cadena vacía: usa `"default"` de forma silenciosa.
`Auth.Password`	`string`	`""`	`password` or URL password portion	Contraseña para la autenticación en ClickHouse	Use variables de entorno o gestores de secretos en producción. Codifique los caracteres especiales en la URL del DSN.	Contraseña incorrecta: `"Code: 516. DB::Exception: Authentication failed"`. Caracteres especiales sin codificar en la URL: errores de parsing.
`Auth.Database`	`string`	`""` (server default)	`database` or URL path (`/mydb`)	Base de datos predeterminada para la conexión	Especifíquela siempre de forma explícita. Use bases de datos específicas por aplicación en producción.	Inexistente: `"Code: 81. DB::Exception: Database xyz doesn't exist"`. Vacía en una configuración multi-tenant: las consultas van a la base de datos equivocada.
`GetJWT`	`func(ctx) (string, error)`	`nil`	(programmatic only)	Función de callback que devuelve un JWT para la autenticación en ClickHouse Cloud. Puede sustituirse por consulta con `WithJWT(token)`. (Desde la v2.35.0)	Implemente caché/renovación de tokens: se invoca por conexión/solicitud.	Token caducado: errores de autenticación. Callback bloqueante: timeout. El JWT tiene prioridad sobre usuario/contraseña. Requiere TLS; sin él, vuelve a usuario/contraseña de forma silenciosa.

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

Tiempos de espera

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Si está mal configurado
`DialTimeout`	`time.Duration`	`30s`	`dial_timeout`	Tiempo máximo para establecer una conexión nueva. También controla el tiempo de espera para obtener una conexión del pool cuando se alcanza `MaxOpenConns`.	5-10s en LAN, 15-30s en WAN/nube, 1-2m si se conecta a un servicio inactivo de ClickHouse Cloud. Nunca por debajo de 1s.	Demasiado corto: `"clickhouse: acquire conn timeout"` durante la congestión, o fallo de conexión antes de que un servicio de Cloud inactivo termine de activarse. Demasiado largo (> 60s): la aplicación queda bloqueada durante caídas del servicio.
`ReadTimeout`	`time.Duration`	`5m` (300s)	`read_timeout`	Tiempo máximo de espera por una respuesta del servidor en cada llamada de lectura. Se aplica por bloque, no a toda la consulta. El límite de tiempo del contexto tiene prioridad.	10-30s para consultas interactivas cortas; 5-30m para consultas analíticas largas.	Demasiado corto: `"i/o timeout"` o `"read: connection reset by peer"` a mitad de la consulta; el servidor sigue ejecutándola. Demasiado largo: no se detectan conexiones muertas.

Un servicio de ClickHouse Cloud que ha estado inactivo entra en pausa y se reactiva con la primera conexión entrante. La reactivación suele tardar unas pocas decenas de segundos, durante las cuales la conexión queda bloqueada. Si DialTimeout es menor que el tiempo de reactivación, la primera consulta después de un período de inactividad falla con un timeout de conexión en lugar de ejecutarse.Configure DialTimeout en 1m–2m para los clients que puedan ser los primeros en llegar a un servicio inactivo. La contrapartida es una detección de fallos más lenta durante una caída real: los intentos de conexión quedan bloqueados durante todo el tiempo de espera antes de devolver un error, así que prefiera limitar el tiempo de espera más alto a la primera conexión, o use límites de tiempo del contexto en consultas individuales para acotar la latencia de extremo a extremo.

Pool de conexiones

Opción	Tipo	Predeterminado	Parámetro DSN	API	Descripción	Mejores prácticas	Cuando está mal configurado
`MaxIdleConns`	`int`	`5`	`max_idle_conns`	Ambas	Número máximo de conexiones inactivas (sin uso, pero abiertas) en el pool	50-80 % de las consultas concurrentes previstas. Bajo: 2-5, medio: 10-20, alto: 20-50.	Demasiado bajo: rotación excesiva de conexiones, mayor latencia. Demasiado alto: memoria desperdiciada. Se limita automáticamente a `MaxOpenConns`.
`MaxOpenConns`	`int`	`MaxIdleConns + 5` (predeterminado: 10)	`max_open_conns`	Ambas	Número máximo total de conexiones (inactivas + activas)	Bajo: 10-20, medio: 20-50, alto: 50-100. Fórmula: consultas concurrentes + ráfaga + búfer. Supervisa: `SELECT * FROM system.metrics WHERE metric='TCPConnection'`.	Demasiado bajo: `"clickhouse: acquire conn timeout"`. Demasiado alto: `"Too many connections"` en el servidor, se superan los límites de FD. Valor predeterminado de `max_connections` en ClickHouse: 1024 (compartido).
`ConnMaxLifetime`	`time.Duration`	`1h`	`conn_max_lifetime`	Ambas	Tiempo máximo durante el que una conexión puede reutilizarse. Se comprueba al devolverla al pool.	1-5 h en entornos estables. 5-15 min para K8s/despliegues graduales. Nunca infinito.	Demasiado corto (< 1 min): rotación excesiva, mayor latencia. Demasiado largo/infinito: conexiones obsoletas, no se detectan cambios de DNS, el tráfico nunca se redistribuye.
`ConnMaxIdleTime`	`time.Duration`	`0` (ninguno)	—	Solo `database/sql`	Tiempo máximo que una conexión puede permanecer inactiva antes de cerrarse. No está en la estructura `Options`; establécelo mediante `db.SetConnMaxIdleTime()`.	5-10 min para K8s/cargas de trabajo intermitentes, para liberar conexiones inactivas después de picos de tráfico.	Si no se configura: las conexiones inactivas permanecen hasta `ConnMaxLifetime`. Demasiado corto (< 30 s): las conexiones se recrean durante huecos habituales.

Solo database/sqlConnMaxIdleTime es una configuración estándar del pool de Go database/sql. No está disponible en la estructura clickhouse.Options ni mediante clickhouse.Open(). Configúralo después de OpenDB():

db := clickhouse.OpenDB(&clickhouse.Options{...})
db.SetConnMaxIdleTime(5 * time.Minute)

Consulta Connection Pooling para ver los detalles de uso.

Configuración estándar del pool de `database/sql`

Al usar clickhouse.OpenDB() o sql.Open("clickhouse", dsn), el *sql.DB devuelto admite los métodos estándar de pool de Go. OpenDB() aplica automáticamente los tres primeros a partir de Options:

Método	Equivalente en Options	Notas
`db.SetMaxIdleConns(n)`	`MaxIdleConns`	Se aplica automáticamente con `OpenDB()`
`db.SetMaxOpenConns(n)`	`MaxOpenConns`	Se aplica automáticamente con `OpenDB()`
`db.SetConnMaxLifetime(d)`	`ConnMaxLifetime`	Se aplica automáticamente con `OpenDB()`
`db.SetConnMaxIdleTime(d)`	None	Debe configurarse manualmente después de crearla

ClickHouse API (clickhouse.Open)Estos métodos no están disponibles en la conexión devuelta por clickhouse.Open(). La ClickHouse API gestiona su propio pool internamente usando directamente los campos de la estructura Options.

Compresión

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Si está mal configurado
`Compression.Method`	`CompressionMethod` (byte)	None	`compress` (`lz4`, `zstd`, `lz4hc`, `gzip`, `deflate`, `br` o `true` para LZ4)	Algoritmo de compresión para la transferencia de datos. Consulte la matriz de compatibilidad de protocolos a continuación.	LAN: None o LZ4. WAN: ZSTD o LZ4. CPU limitada: LZ4. Compresión máxima: ZSTD (Native) o Brotli (HTTP). Omítalo para inserciones de < 1 MB.	GZIP/Brotli en Native: fallo en el handshake. LZ4HC en HTTP: error o fallback silencioso. Sin compresión en redes lentas: inserciones 10-100x más lentas.
`Compression.Level`	`int`	`3`	`compress_level`	Intensidad específica de cada algoritmo. GZIP/Deflate: -2 a 9. Brotli: 0 a 11. LZ4/ZSTD: se ignora.	GZIP equilibrado: 3-6. Brotli equilibrado: 4-6.	Niveles muy altos: uso extremo de CPU y beneficio mínimo. Valor distinto de cero para LZ4/ZSTD: se ignora silenciosamente. Nivel sin compresión habilitada: sin efecto.
`MaxCompressionBuffer`	`int` (bytes)	`10485760` (10 MiB)	`max_compression_buffer`	Tamaño máximo del búfer de compresión antes del vaciado. Cada conexión tiene su propio búfer.	El valor predeterminado de 10 MiB es adecuado. 20-50 MiB para filas anchas. Memoria total = búfer x `MaxOpenConns`.	Demasiado pequeño (< 1 MiB): vaciados frecuentes y poca eficiencia. Demasiado grande (> 100 MiB): OOM con muchas conexiones.

Compatibilidad de métodos de compresión por protocolo:

Método	Native	HTTP
`CompressionLZ4`	Sí	Sí
`CompressionLZ4HC`	Sí	No
`CompressionZSTD`	Sí	Sí
`CompressionGZIP`	No	Sí
`CompressionDeflate`	No	Sí
`CompressionBrotli`	No	Sí

TLS

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Si está mal configurado
`TLS`	`*tls.Config`	`nil` (texto sin cifrar)	`secure=true`, `skip_verify=true`	Configuración de TLS/SSL. Un valor distinto de `nil` habilita TLS. Puertos: Native 9000/9440, HTTP 8123/8443.	Actívelo siempre en producción y en ClickHouse Cloud (obligatorio). `InsecureSkipVerify: false` en producción. Añada CA personalizadas mediante `RootCAs`.	Puerto incorrecto: `"connection reset by peer"`. `skip_verify=true` en producción: vulnerable a ataques MITM. Certificado caducado: `"x509: certificate has expired"`. Host incorrecto: `"x509: certificate is valid for X, not Y"`. CA no confiable: `"x509: certificate signed by unknown authority"`. DSN HTTP con `secure=true`: use el esquema `https://` en su lugar.

Consulte TLS para ver ejemplos de código.

Registro

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Si está mal configurado
`Logger`	`*slog.Logger`	`nil` (sin registro)	—	Logger estructurado mediante `log/slog` de Go. Prioridad: `Debug`+`Debugf` > `Logger` > no-op. (Desde la versión 2.43.0)	Use `slog` con un handler JSON en producción. Añada contexto de la aplicación con `logger.With(...)`.	—
`Debug` (obsoleto)	`bool`	`false`	`debug`	Opción heredada para depuración. Use `Logger` en su lugar. Registra en stdout, a menos que se configure `Debugf`.	—	Activado en producción: sobrecarga de rendimiento, logs verbosos y datos sensibles en la salida.
`Debugf` (obsoleto)	`func(string, ...any)`	`nil`	—	Función personalizada para el registro de depuración. Use `Logger` en su lugar. Requiere `Debug: true`.	—	—

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

Consulta Logging para ver ejemplos completos.

Búferes y memoria

Opción	Tipo	Predeterminado	Parámetro DSN	Por consulta	Descripción	Práctica recomendada	Si está mal configurado
`BlockBufferSize`	`uint8`	`2`	`block_buffer_size`	Sí (`WithBlockBufferSize`)	Cantidad de bloques decodificados que se almacenan en búfer al leer resultados. Permite lectura y decodificación concurrentes.	El valor predeterminado de 2 suele ser suficiente. 5-10 para resultados grandes en streaming. Memoria = búfer x tamaño del bloque x consultas concurrentes.	Demasiado pequeño (1): bloquea el lector de bloques, aumenta la latencia. Demasiado grande (> 50): alto uso de memoria, rendimientos decrecientes.
`FreeBufOnConnRelease`	`bool`	`false`	—	No	Libera el búfer de memoria de la conexión después de cada consulta, en lugar de reutilizarlo.	`false` para tasas altas de consultas. `true` en contenedores con memoria limitada o lotes grandes poco frecuentes.	`false` + memoria limitada: los búferes se acumulan (memoria = búfer x conexiones inactivas). `true` + tasa alta: más presión sobre el GC, aumento del uso de CPU.

Específico de HTTP

Se ignora silenciosamente con NativeEstas opciones solo afectan a Protocol: clickhouse.HTTP. Se ignoran silenciosamente cuando se usa el protocolo Native y no se emite ningún error ni advertencia.

Opción	Tipo	Valor predeterminado	Parámetro DSN	Descripción	Buena práctica	Si está mal configurado
`HttpHeaders`	`map[string]string`	`nil`	—	Encabezados HTTP adicionales en cada solicitud	Úselo para tracing (`X-Request-ID`) y encabezados del proxy de autenticación. Manténgalos al mínimo.	Sobrescribir encabezados internos (`Content-Type`, `Authorization`): comportamiento impredecible.
`HttpUrlPath`	`string`	`""`	`http_path`	Ruta de URL añadida a las solicitudes. La `/` inicial se agrega automáticamente.	Úselo cuando esté detrás de un proxy inverso con enrutamiento por ruta.	Ruta incorrecta: HTTP 404 del proxy/LB.
`HttpMaxConnsPerHost`	`int`	`0` (ilimitado)	—	Conexiones TCP por host en la capa de transporte (`http.Transport.MaxConnsPerHost`).	Déjelo en 0 para la mayoría de las aplicaciones. Ajústelo solo cuando el servidor tenga límites estrictos de conexiones.	Demasiado bajo (p. ej., 10 con `MaxOpenConns`=50): cuello de botella en el transporte, consultas lentas pese a la baja carga del servidor.
`HTTPProxyURL`	`*url.URL`	`nil` (usa variables de entorno)	`http_proxy` (URL codificada)	Proxy HTTP para enrutar solicitudes	Establézcalo explícitamente si se requiere un proxy. Sobrescribe las variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`.	Dirección incorrecta: `"dial tcp: lookup proxy: no such host"`. El proxy requiere autenticación: HTTP 407.
`TransportFunc`	`func(*http.Transport) (http.RoundTripper, error)`	`nil`	—	Fábrica personalizada de transporte HTTP. Recibe el transporte predeterminado para envolverlo. (Desde v2.41.0)	Úselo para middleware de observabilidad. No sobrescriba `Proxy`, `DialContext`, `TLSClientConfig`.	Devolver `nil`: pánico. Sobrescribir campos del cliente: TLS/proxy se ignoran silenciosamente. `RoundTripper` bloqueante: interbloqueos.

Pool HTTP de dos capasAl usar HTTP, hay dos pools de conexiones:

Capa 1 (aplicación): MaxIdleConns / MaxOpenConns — controla los objetos httpConnect
Capa 2 (transporte): HttpMaxConnsPerHost — controla las conexiones TCP subyacentes

El protocolo Native tiene una correspondencia simple 1:1 e ignora HttpMaxConnsPerHost.

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

Conexión avanzada

Opción	Tipo	Predeterminado	Parámetro DSN	Descripción	Práctica recomendada	Si está mal configurado
`DialContext`	`func(ctx, addr) (net.Conn, error)`	`nil` (dialer estándar)	—	Función de conexión personalizada para conexiones TCP. Funciona tanto con Native como con HTTP.	Deja `nil` en el 99 % de los casos. Úsalo para sockets Unix, proxy SOCKS o DNS personalizado.	Si no respeta el contexto: bloqueos y fugas de recursos. Con `TLS` configurado: el dialer personalizado debe encargarse de TLS por sí mismo. `net.Conn` no válido: provoca fallos.
`DialStrategy`	`func(ctx, connID, options, dial) (DialResult, error)`	`DefaultDialStrategy`	—	Estrategia personalizada de selección de servidor y conexión. Anula `ConnOpenStrategy`.	Usa la predeterminada en el 99,9 % de los casos. Personalízala solo para enrutamiento con reconocimiento Geo, selección ponderada o comprobaciones de estado.	Si no prueba todos los servidores: falla aunque haya servidores en buen estado disponibles. Operaciones costosas en su interior: bloquean la adquisición del pool en cada conexión.

Información del cliente

Opción	Tipo	Predeterminado	Parámetro DSN	Por consulta	Descripción	Buenas prácticas	Si está mal configurado
`ClientInfo`	Estructura `ClientInfo`	Automático: versión de `clickhouse-go` + runtime de Go	`client_info_product=myapp/1.0`	Sí (`WithClientInfo`, lo añade)	Identificación de la aplicación que se envía a ClickHouse. Contiene `Products` (`[]struct{Name,Version}`) y `Comment` (`[]string`). Visible en `system.query_log`.	Establezca siempre el nombre y la versión de la aplicación. Atribución de consultas: `SELECT client_name FROM system.query_log WHERE client_name LIKE '%myapp%'`	Si no se establece, no se puede identificar qué servicio emitió consultas en entornos con varios servicios.

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)

Ajustes del servidor ClickHouse

Opción	Tipo	Predeterminado	Parámetro DSN	Por consulta	Descripción	Práctica recomendada	Cuando está mal configurado
`Settings`	`map[string]any`	`nil`	Cualquier parámetro no reconocido (p. ej., `?max_execution_time=60`)	Sí (`WithSettings`; el contexto prevalece en caso de conflicto)	Ajustes del servidor ClickHouse aplicados a cada consulta. Conversión de DSN: `"true"`→`1`, `"false"`→`0`, numérico→`int`.	Establezca límites comunes a nivel de conexión y ajústelos por consulta mediante el contexto.	Errores tipográficos: se ignoran silenciosamente o generan un error según la versión. Tipos incorrectos: `"Cannot parse string 'abc' as Int64"`. `max_execution_time=0` + sin tiempo límite: las consultas se ejecutan indefinidamente.
`CustomSetting`	`CustomSetting{Value string}`	—	—	Sí (mediante `WithSettings`)	Marca un ajuste como “personalizado” (no importante) para el protocolo nativo. No dará error si el servidor no lo reconoce. HTTP trata todos los ajustes como personalizados de forma predeterminada.	Úselo para ajustes experimentales o específicos de una versión.	Marcar ajustes importantes como personalizados: se ignoran silenciosamente si no son compatibles.

Ajustes comunes:

Ajuste	Tipo	Descripción
`max_execution_time`	int	Timeout de consulta en segundos
`max_memory_usage`	int	Límite de memoria por consulta (bytes)
`max_block_size`	int	Tamaño de bloque para el procesamiento
`readonly`	int	1 = solo lectura, 2 = solo lectura + cambios de ajustes

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // importante -- error si se desconoce
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // personalizado -- ignorado si se desconoce
}

Opciones de consulta a nivel de contexto

Configúrelas por consulta con clickhouse.Context():

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

Comportamiento del tiempo límite de contextoSi el contexto tiene un tiempo límite > 1 s, max_execution_time se establece automáticamente en seconds_remaining + 5. Esto anula cualquier valor establecido manualmente.

Opción	Tipo	Valor predeterminado	Protocolo	Descripción	Práctica recomendada	En caso de configuración incorrecta
`WithQueryID`	`string`	Generado automáticamente	Ambos	Identificador personalizado de la consulta. Visible en `system.query_log` y `system.processes`.	Usa UUIDs. Resulta útil para `KILL QUERY WHERE query_id='...'`.	IDs duplicados: generan confusión en `system.query_log`.
`WithQuotaKey`	`string`	`""`	Ambos	Clave de cuota para límites de recursos en entornos multitenant. Requiere configuración de cuotas del servidor.	Úselo para límites por cliente o por usuario.	Quota sin configurar: se ignora silenciosamente.
`WithJWT`	`string`	`""`	Solo HTTPS	Sobrescritura de JWT a nivel de consulta para ClickHouse Cloud. (Desde la versión v2.35.0)	Úselo para autenticación por solicitud en proxies multi-tenant.	Sin TLS: se ignora y se vuelve a la autenticación de la conexión. Caducado: `"Token has expired"`.
`WithSettings`	`Settings`	Heredado de la conexión	Ambos	Configuración del servidor por consulta. Se combina con la configuración de la conexión; el contexto prevalece en caso de conflicto.	Sobrescriba `max_execution_time` o `max_rows_to_read` según el tipo de consulta.	Lo mismo que `Settings` a nivel de conexión.
`WithParameters`	`Parámetros` (`map[string]string`)	`nil`	Ambos	Valores para consultas parametrizadas del lado del servidor. Sintaxis de la consulta: `{param_name:Type}`.	Úselo en lugar de concatenar cadenas para evitar la inyección SQL.	Falta el parámetro: `"Substitution {param_name:Type} isn't set"`. Tipo incorrecto: `"Cannot parse string 'abc' as UInt64"`.
`WithAsync`	`bool` (wait)	Sincrónico	Ambos	Modo de inserción asíncrona. Establece `async_insert=1`. `wait=true` añade `wait_for_async_insert=1`. Requiere ClickHouse 21.11+. (Desde la versión v2.41.0; sustituye al antiguo `WithStdAsync`.)	Úselo para inserciones de alto rendimiento.	`wait=false`: los errores pueden ser asíncronos — consulta `system.asynchronous_insert_log`. Con SELECT: se ignora. En servidores antiguos: `"Unknown setting async_insert"`.
`WithLogs`	`func(*Log)`	`nil`	Solo en Native	Callback para las entradas del log del servidor durante la ejecución de la consulta.	Procure que sea rápido: bloquea la ejecución. Use goroutines para el procesamiento intensivo.	En HTTP: no se llama nunca y no muestra ningún aviso.
`WithProgress`	`func(*Progress)`	`nil`	Solo para Native	Actualizaciones del progreso de la consulta (filas/bytes procesados).	Haz que sea rápido; bloquea la ejecución.	En HTTP: no se llama nunca y no muestra ningún aviso.
`WithProfileInfo`	`func(*ProfileInfo)`	`nil`	Solo nativo	Callback de estadísticas de ejecución de consultas.	Debe ser rápido: bloquea la ejecución.	En HTTP: nunca se llama, sin avisar.
`WithProfileEvents`	`func([]ProfileEvent)`	`nil`	Solo nativo	Callback de contadores de rendimiento.	Procura que sea rápido: bloquea la ejecución.	En HTTP: no se llama nunca, sin aviso.
`WithoutProfileEvents`	—	Eventos enviados	Solo nativo	Suprime los eventos de perfil. Optimización del rendimiento para servidores ≥ 25.11. (Desde la versión 2.44.0)	Úselo cuando no necesite eventos de perfil.	En servidores antiguos: error por ajuste desconocido.
`WithExternalTable`	`...*ext.Table`	`nil`	Ambos	Adjunta tablas temporales de búsqueda a la consulta. Los datos se transfieren por consulta.	Mantén las tablas por debajo de 10 MB. El protocolo nativo es más eficiente que HTTP (multipart).	Tablas grandes: sobrecarga de red en cada consulta.
`WithUserLocation`	`*time.Location`	Zona horaria del servidor	Ambos	Sobrescribe la zona horaria para el procesamiento de DateTime.	Configúrelo explícitamente cuando difieran las zonas horarias del cliente y del servidor.	Zona horaria incorrecta: los valores de DateTime pueden quedar desplazados varias horas sin aviso, con posible corrupción de datos.
`WithColumnNamesAndTypes`	`[]ColumnNameAndType`	`nil` (ejecuta DESCRIBE)	Solo para HTTP	Omita la ida y vuelta de `DESCRIBE TABLE` en las inserciones HTTP proporcionando de antemano la información de las columnas. (Desde la versión 2.37.0)	Úselo cuando el esquema sea conocido y estable.	Tipos incorrectos: `"Cannot convert String to UInt64"`. Desajuste del esquema tras la migración: información obsoleta.
`WithBlockBufferSize`	`uint8`	A nivel de la conexión (2)	Ambos	Sobrescribe el `BlockBufferSize` a nivel de conexión para una sola consulta.	Auméntelo para consultas específicas con conjuntos de resultados grandes.	—
`WithClientInfo`	`ClientInfo`	Nivel de conexión	Ambos	Añade información adicional del cliente para una sola consulta. No la reemplaza; la añade. (Desde la versión v2.42.0)	Agregue contexto por solicitud (p. ej., nombre del endpoint).	—
`WithSpan`	`trace.SpanContext`	Vacío	Solo nativo	Contexto de span de OpenTelemetry para el trazado distribuido.	Consulte OpenTelemetry.	—

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

Opciones de lote

Se pasan a PrepareBatch(). Importación: github.com/ClickHouse/clickhouse-go/v2/lib/driver.

Opción	Valor predeterminado	Descripción	Buena práctica	Si se configura mal
`WithReleaseConnection`	La conexión se mantiene hasta `Send()`	Libera la conexión al pool inmediatamente después de `PrepareBatch()`. La vuelve a adquirir en `Send()`/`Flush()`.	Úselo para lotes de larga duración (minutos/horas) para evitar agotar el pool.	No usarlo con lotes largos: `"acquire conn timeout"` si hay muchas conexiones activas.
`WithCloseOnFlush`	El lote permanece abierto	Cierra automáticamente el lote cuando se llama a `Flush()`.	Úselo para lotes de una sola vez. Evita tener que llamar explícitamente a `Close()`.	Usarlo con varias llamadas a `Flush()`: el primer flush cierra el lote y las operaciones posteriores fallan.

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

Tablas de consulta rápida

Recomendaciones para el dimensionamiento del pool de conexiones

Tipo de aplicación	MaxIdleConns	MaxOpenConns	ConnMaxLifetime
Aplicación web de poco tráfico	5	10	1h
API de tráfico medio	20	50	30m
Servicio de alto tráfico	50	100	15m
Procesos por lotes en segundo plano	10	20	2h
Implementación de Kubernetes	10	20	10m
Sin servidor (Lambda)	1	5	5m

Recomendaciones de timeout

Entorno	DialTimeout	ReadTimeout
Local / LAN	5s	30s
Cloud, misma región	10s	2m
Cloud, entre regiones	30s	5m
workload OLAP	10s	30m
Tiempo real / OLTP	5s	10s

Referencia rápida de los parámetros de DSN

Parámetro de DSN	Campo de opciones	Ejemplo
`username`	`Auth.Username`	`?username=admin`
`password`	`Auth.Password`	`?password=secret`
`database`	`Auth.Database`	`?database=mydb` o `/mydb` en la ruta
`dial_timeout`	`DialTimeout`	`?dial_timeout=10s`
`read_timeout`	`ReadTimeout`	`?read_timeout=5m`
`max_open_conns`	`MaxOpenConns`	`?max_open_conns=50`
`max_idle_conns`	`MaxIdleConns`	`?max_idle_conns=20`
`conn_max_lifetime`	`ConnMaxLifetime`	`?conn_max_lifetime=30m`
`connection_open_strategy`	`ConnOpenStrategy`	`?connection_open_strategy=round_robin`
`block_buffer_size`	`BlockBufferSize`	`?block_buffer_size=10`
`compress`	`Compression.Method`	`?compress=lz4`
`compress_level`	`Compression.Level`	`?compress_level=6`
`max_compression_buffer`	`MaxCompressionBuffer`	`?max_compression_buffer=20971520`
`secure`	`TLS`	`?secure=true`
`skip_verify`	`TLS.InsecureSkipVerify`	`?skip_verify=true`
`debug`	`Debug`	`?debug=true`
`client_info_product`	`ClientInfo.Products`	`?client_info_product=myapp/1.0`
`http_proxy`	`HTTPProxyURL`	`?http_proxy=http%3A%2F%2Fproxy%3A8080`
`http_path`	`HttpUrlPath`	`?http_path=/clickhouse`
(cualquier otro)	`Settings[key]`	`?max_execution_time=60`

Solución de problemas

Pool de conexiones agotado: “acquire conn timeout”

Causa: Se agotó el pool de conexiones: todas las conexiones de MaxOpenConns están en uso y ninguna se liberó dentro de DialTimeout. Solución Pruebe los siguientes pasos en orden y diagnostique la causa raíz antes de ajustar los parámetros:

Compruebe si hay consultas de larga duración que mantienen conexiones ocupadas: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. Si las encuentra, resuelva primero las consultas lentas.
Si ejecuta lotes de larga duración (minutos/horas entre PrepareBatch() y Send()), use WithReleaseConnection() para devolver la conexión al pool mientras el lote permanece abierto.
Aumente MaxOpenConns para ajustarlo a la concurrencia observada.
Aumente DialTimeout solo si se esperan picos y la espera para adquirir una conexión es el verdadero cuello de botella.

Errores de tiempo de espera de lectura y restablecimiento de conexión

Causa: Se superó ReadTimeout mientras se esperaba una respuesta del servidor, o el servidor o la red cerraron la conexión. Solución:

Aumente ReadTimeout para consultas de larga duración
Use fechas límite de contexto para controlar el tiempo de espera de cada consulta
Compruebe los límites de max_execution_time en el servidor de ClickHouse

”Código: 516. Falló la autenticación”

Causa: Nombre de usuario o contraseña incorrectos, o el usuario no existe. Solución:

Verifique las credenciales en la tabla system.users
Compruebe si hay problemas de codificación de URL con caracteres especiales en las contraseñas del DSN
Confirme que el usuario tenga acceso a la base de datos especificada

Errores de certificado TLS

Error	Causa	Solución
`x509: certificate has expired`	El certificado del servidor ha caducado	Renueve el certificado del servidor
`x509: certificate is valid for X, not Y`	El `hostname` no coincide	Use el `hostname` correcto o añádalo a los SAN
`x509: certificate signed by unknown authority`	CA no confiable	Añada la CA a `tls.Config.RootCAs`
`connection reset by peer`	Desajuste entre TLS y el puerto	Use el puerto 9440 (Native) o 8443 (HTTP) para TLS

Aumento gradual de memoria

Causa: Acumulación de búferes grandes en conexiones inactivas. Solución:

Establece FreeBufOnConnRelease: true en entornos con memoria limitada
Reduce MaxIdleConns para limitar las conexiones inactivas
Reduce MaxCompressionBuffer si usas compresión
Reduce ConnMaxLifetime para reciclar las conexiones con más frecuencia

​Cómo se configuran las opciones

​Opciones de conexión

​Protocolo y conexión

​Autenticación

​Tiempos de espera

​Pool de conexiones

​Configuración estándar del pool de database/sql

​Compresión

​TLS

​Registro

​Búferes y memoria

​Específico de HTTP

​Conexión avanzada

​Información del cliente

​Ajustes del servidor ClickHouse

​Opciones de consulta a nivel de contexto

​Opciones de lote

​Tablas de consulta rápida

​Recomendaciones para el dimensionamiento del pool de conexiones

​Recomendaciones de timeout

​Referencia rápida de los parámetros de DSN

​Solución de problemas

​Pool de conexiones agotado: “acquire conn timeout”

​Errores de tiempo de espera de lectura y restablecimiento de conexión

​”Código: 516. Falló la autenticación”

​Errores de certificado TLS

​Aumento gradual de memoria

Cómo se configuran las opciones

Opciones de conexión

Protocolo y conexión

Autenticación

Tiempos de espera

Pool de conexiones

Configuración estándar del pool de `database/sql`

Compresión

TLS

Registro

Búferes y memoria

Específico de HTTP

Conexión avanzada

Información del cliente

Ajustes del servidor ClickHouse

Opciones de consulta a nivel de contexto

Opciones de lote

Tablas de consulta rápida

Recomendaciones para el dimensionamiento del pool de conexiones

Recomendaciones de timeout

Referencia rápida de los parámetros de DSN

Solución de problemas

Pool de conexiones agotado: “acquire conn timeout”

Errores de tiempo de espera de lectura y restablecimiento de conexión

”Código: 516. Falló la autenticación”

Errores de certificado TLS

Aumento gradual de memoria