database/sql, o API “estándar”, te permite usar el cliente en escenarios en los que el código de la aplicación debe ser independiente de las bases de datos subyacentes, al ajustarse a una interfaz estándar. Esto tiene cierto coste adicional: capas extra de abstracción e indirección, y primitivas que no están necesariamente alineadas con ClickHouse. Aun así, estos costes suelen ser aceptables cuando las herramientas necesitan conectarse a varias bases de datos.
Además, este cliente admite el uso de HTTP como capa de transporte; los datos seguirán codificándose en el formato nativo para ofrecer un rendimiento óptimo.
Conexión
La conexión puede realizarse mediante una cadena DSN con el formatoclickhouse://<host>:<port>?<query_option>=<value> y el método Open, o mediante el método clickhouse.OpenDB. Este último no forma parte de la especificación database/sql, pero devuelve una instancia de sql.DB. Este método ofrece funcionalidades como profiling, para las que no existe una forma clara de exponerlas a través de la especificación database/sql.
conn de ClickHouse ya se ha creado y está disponible.
Configuración de conexión
La mayoría de las opciones de configuración se comparten con la ClickHouse API. Consulte Configuración para ver los ajustes compartidos. Están disponibles los siguientes parámetros de DSN específicos de SQL:hosts- lista de hosts de dirección única separados por comas para balanceo de carga y failover; consulte Conexión a varios nodos.username/password- credenciales de autenticación; consulte Autenticacióndatabase- selecciona la base de datos predeterminada actualdial_timeout- una cadena de duración es una secuencia, posiblemente con signo, de números decimales, cada uno con una fracción opcional y un sufijo de unidad, como300ms,1s. Las unidades de tiempo válidas sonms,s,m.connection_open_strategy-random/in_order(el valor predeterminado esrandom); consulte Conexión a varios nodosround_robin- elige un servidor del conjunto en round robinin_order- se elige el primer servidor activo en el orden especificado
debug- habilita la salida de depuración (valor booleano)compress- especifica el algoritmo de compresión:none(predeterminado),zstd,lz4,gzip,deflate,br. Si se establece entrue, se usarálz4. Solo se admitenlz4yzstdpara la comunicación nativa.compress_level- nivel de compresión (el valor predeterminado es0). Consulte la sección Compresión. Esto depende del algoritmo:gzip--2(máxima velocidad) a9(máxima compresión)deflate--2(máxima velocidad) a9(máxima compresión)br-0(máxima velocidad) a11(máxima compresión)zstd,lz4- se ignoran
secure- establece una conexión SSL segura (el valor predeterminado esfalse)skip_verify- omite la verificación del certificado (el valor predeterminado esfalse)block_buffer_size- permite controlar el tamaño del búfer de bloques. ConsulteBlockBufferSize. (el valor predeterminado es2)
Conexión mediante HTTP
De forma predeterminada, las conexiones se establecen mediante el protocolo nativo. Si necesita HTTP, puede habilitarlo modificando el DSN para incluir el protocolo HTTP o especificando el protocolo en las opciones de conexión.Sesiones
Solo HTTPLas sesiones solo son necesarias cuando se utiliza el transporte HTTP. Las conexiones TCP nativas incorporan automáticamente una sesión.
session_id como parámetro de configuración para habilitar funciones asociadas a la sesión, como las tablas temporales.
Ejecución
Una vez obtenida una conexión, puede ejecutar sentenciassql mediante el método Exec.
ExecContext si es necesario; consulte Uso del contexto.
Inserción por lotes
La semántica de lote puede lograrse creando unsql.Tx mediante el método Being. A partir de este, se puede obtener un lote con el método Prepare y la sentencia INSERT. Esto devuelve un sql.Stmt al que se pueden agregar filas mediante el método Exec. El lote se acumulará en memoria hasta que se ejecute Commit en el sql.Tx original.
Consultar filas
Se puede consultar una sola fila mediante el métodoQueryRow. Esto devuelve un *sql.Row, sobre el que se puede invocar Scan con punteros a variables en las que se deben asignar las columnas. Una variante de QueryRowContext permite pasar un Context distinto de background; consulte Uso del contexto.
Query. Este devuelve una estructura *sql.Rows en la que se puede invocar Next para recorrer las filas. El equivalente QueryContext permite pasar un contexto.
Inserción asíncrona
Las inserciones asíncronas pueden realizarse ejecutando una inserción mediante el métodoExecContext. Debe pasarse un contexto con el modo asíncrono habilitado, como se muestra a continuación. Esto permite al usuario especificar si el cliente debe esperar a que el servidor complete la inserción o responder en cuanto se hayan recibido los datos. En la práctica, esto controla el parámetro wait_for_async_insert.
Parámetros de consulta del lado del servidor
La API estándar admite parámetros de consulta del lado del servidor de ClickHouse mediante marcadores de posición con tipo{name:Type} y valores clickhouse.Named:
string/*string o []byte/*[]byte pasado mediante clickhouse.Named se trata como un valor literal y el controlador lo escapa, por lo que hace el viaje de ida y vuelta byte a byte sin alteraciones. Use un salto de línea o una tabulación reales en el valor de Go cuando eso sea lo que desea transmitir en el wire:
Escaped de ClickHouse, utilice WithParameters en su lugar. Consulte Parámetros de consulta del lado del servidor para obtener una explicación completa de los tipos, el escapado y las diferencias entre {name:Type} y la vinculación en el cliente.
Ejemplo completo con la API estándar
Vinculación de parámetros
La API estándar admite las mismas opciones de vinculación de parámetros que la ClickHouse API, lo que permite pasar parámetros a los métodosExec, Query y QueryRow (y a sus variantes equivalentes de Context). Se admiten parámetros posicionales, con nombre y numerados.
Uso del contexto
La API estándar permite, al igual que la ClickHouse API, pasar fechas límite, señales de cancelación y otros valores asociados a la solicitud mediante el contexto. A diferencia de la ClickHouse API, esto se logra usando variantesContext de los métodos; es decir, métodos como Exec, que usan el contexto de fondo de forma predeterminada, tienen una variante ExecContext a la que se le puede pasar un contexto como primer parámetro. Esto permite pasar un contexto en cualquier etapa del flujo de una aplicación. Por ejemplo, puede pasar un contexto al establecer una conexión mediante ConnContext o al solicitar una fila de una consulta mediante QueryRowContext. A continuación se muestran ejemplos de todos los métodos disponibles.
Para obtener más información sobre cómo usar el contexto para pasar fechas límite, señales de cancelación, identificadores de consulta, claves de cuota y opciones de conexión, consulte Uso del contexto para la ClickHouse API.
Escaneo dinámico
Al igual que en la ClickHouse API, la información sobre el tipo de columna está disponible para crear, en tiempo de ejecución, instancias de variables con el tipo correcto que pueden pasarse a Scan. Esto permite leer columnas cuyo tipo no se conoce.Tablas externas
Las tablas externas permiten que el cliente envíe datos a ClickHouse con una consultaSELECT. Estos datos se almacenan en una tabla temporal y pueden usarse en la propia consulta para su evaluación.
Para enviar datos externos desde el cliente con una consulta, el usuario debe crear una tabla externa mediante ext.NewTable antes de pasarla a través del contexto.
OpenTelemetry
ClickHouse admite la propagación del contexto de trace tanto en el transporte TCP como en el HTTP. Useclickhouse.WithSpan para asociar un span a una consulta mediante el contexto.
Limitación del transporte HTTPAunque ClickHouse server acepta los encabezados HTTP estándar
traceparent / tracestate, el transporte HTTP de clickhouse-go actualmente no los envía, por lo que WithSpan no tiene efecto con HTTP. Como alternativa, puede establecer manualmente el encabezado mediante HttpHeaders en las opciones de conexión.Compresión
La API estándar admite los mismos algoritmos de compresión que la ClickHouse API, es decir, compresiónlz4 y zstd a nivel de bloque. Además, se admiten las compresiones gzip, deflate y br para las conexiones HTTP. Si cualquiera de estas opciones está habilitada, la compresión se aplica a los bloques durante la inserción y en las respuestas a consultas. Otras solicitudes, por ejemplo, pings o solicitudes de consulta, permanecerán sin comprimir. Esto es coherente con las opciones lz4 y zstd.
Si se utiliza el método OpenDB para establecer una conexión, se puede pasar una configuración de compresión. Esto incluye la posibilidad de especificar el nivel de compresión (consulte a continuación). Si se conecta mediante sql.Open con DSN, utilice el parámetro compress. Puede ser un algoritmo de compresión específico, es decir, gzip, deflate, br, zstd o lz4, o una marca booleana. Si se establece en true, se utilizará lz4. El valor predeterminado es none, es decir, la compresión está deshabilitada.
gzip--2(Máxima velocidad) a9(Mejor compresión)deflate--2(Máxima velocidad) a9(Mejor compresión)br-0(Máxima velocidad) a11(Mejor compresión)zstd,lz4- se ignoran