Configuration

Configuration du client clickhouse-go : paramètres de connexion, TLS, authentification, pool de connexions, journalisation et compression.

​

Paramètres de connexion

Pour une présentation détaillée de chaque option, avec les valeurs par défaut, les paramètres DSN, les bonnes pratiques et le dépannage, consultez la Référence de configuration.

Lors de l’ouverture d’une connexion, une structure Options peut être utilisée pour contrôler le comportement du client. Les paramètres suivants sont disponibles :

Paramètre	Type	Par défaut	Description
Protocol	Protocol	Native	Protocole de transport : Native (TCP) ou HTTP. Voir TCP vs HTTP.
Addr	[]string	—	Liste d’adresses host:port. Pour plusieurs nœuds, voir Connexion à plusieurs nœuds.
Auth	Auth	—	Identifiants d’authentification (Database, Username, Password). Voir Authentification.
TLS	*tls.Config	nil	Configuration TLS. Une valeur non nulle active TLS. Voir TLS.
DialContext	func(ctx, addr) (net.Conn, error)	—	Fonction personnalisée pour contrôler la manière dont les connexions TCP sont établies.
DialTimeout	time.Duration	30s	Temps d’attente maximal lors de l’ouverture d’une nouvelle connexion. Augmentez-le à 1m–2m lors de la connexion à un service ClickHouse Cloud susceptible d’être inactif — voir Délais d’attente.
MaxOpenConns	int	MaxIdleConns + 5	Nombre maximal de connexions ouvertes à tout moment.
MaxIdleConns	int	5	Nombre de connexions inactives à conserver dans le pool.
ConnMaxLifetime	time.Duration	1h	Durée de vie maximale d’une connexion du pool. Voir Pool de connexions.
ConnOpenStrategy	ConnOpenStrategy	ConnOpenInOrder	Stratégie utilisée pour choisir un nœud dans Addr. Voir Connexion à plusieurs nœuds.
BlockBufferSize	uint8	2	Nombre de blocs à décoder en parallèle. Des valeurs plus élevées augmentent le débit au prix d’une consommation mémoire plus importante. Peut être redéfini pour chaque requête via le contexte.
Settings	Settings	—	Ensemble de paramètres ClickHouse appliqués à chaque requête. Les requêtes individuelles peuvent les redéfinir via le contexte.
Compression	*Compression	nil	Compression au niveau des blocs. Voir Compression.
ReadTimeout	time.Duration	—	Temps d’attente maximal pour une lecture depuis le serveur lors d’un appel unique.
FreeBufOnConnRelease	bool	false	Si true, libère à chaque requête le buffer mémoire de la connexion vers le pool. Réduit l’utilisation de la mémoire au prix d’un léger surcoût CPU.
Logger	*slog.Logger	nil	Logger structuré (Go log/slog). Voir Journalisation.
Debug	bool	false	Obsolète. Utilisez Logger à la place. Active la sortie de débogage historique vers stdout.
Debugf	func(string, ...any)	—	Obsolète. Utilisez Logger à la place. Fonction personnalisée de journalisation du débogage. Nécessite Debug: true.
GetJWT	GetJWTFunc	—	Fonction de rappel renvoyant un jeton JWT pour l’authentification ClickHouse Cloud (HTTPS uniquement).
HttpHeaders	map[string]string	—	En-têtes HTTP supplémentaires envoyés avec chaque requête (transport HTTP uniquement).
HttpUrlPath	string	—	Chemin d’URL supplémentaire ajouté aux requêtes HTTP (transport HTTP uniquement).
HttpMaxConnsPerHost	int	—	Redéfinit MaxConnsPerHost dans le http.Transport sous-jacent (transport HTTP uniquement).
TransportFunc	func(*http.Transport) (http.RoundTripper, error)	—	Fabrique de transport HTTP personnalisée. Le transport par défaut est transmis pour permettre des redéfinitions sélectives (transport HTTP uniquement).
HTTPProxyURL	*url.URL	—	URL du proxy HTTP pour toutes les requêtes (transport HTTP uniquement).

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
}

Exemple complet

​

TLS

À bas niveau, toutes les méthodes de connexion du client (DSN/OpenDB/Open) utilisent le paquet tls de Go pour établir une connexion sécurisée. Le client sait qu’il doit utiliser TLS si la structure Options contient un pointeur tls.Config non nul.

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

Exemple complet

Cette configuration TLS.Config minimale suffit généralement pour se connecter au port natif sécurisé (généralement 9440) d’un serveur ClickHouse. Si le serveur ClickHouse ne dispose pas d’un certificat valide (expiré, avec un hostname incorrect, ou non signé par une autorité de certification racine reconnue publiquement), InsecureSkipVerify peut être défini sur true, mais cela est fortement déconseillé.

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

Exemple complet

Si des paramètres TLS supplémentaires sont nécessaires, le code de l’application doit renseigner les champs souhaités dans la structure tls.Config. Cela peut inclure des suites de chiffrement spécifiques, l’utilisation forcée d’une version TLS particulière (comme 1.2 ou 1.3), l’ajout d’une chaîne de certificats d’une autorité de certification interne, l’ajout d’un certificat client (et d’une clé privée) si le serveur ClickHouse l’exige, ainsi que la plupart des autres options liées à une configuration de sécurité plus spécialisée.

​

Authentification

Indiquez une structure Auth dans les détails de connexion afin de définir un nom d’utilisateur et un mot de passe.

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

Exemple complet

​

Connexion à plusieurs nœuds

Plusieurs adresses peuvent être spécifiées dans la structure 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())

Exemple complet

Trois stratégies de connexion sont disponibles :

• ConnOpenInOrder (par défaut) - les adresses sont utilisées dans l’ordre. Les adresses suivantes ne sont sollicitées qu’en cas d’échec de connexion aux adresses précédentes dans la liste. Il s’agit en pratique d’une stratégie de basculement.
• ConnOpenRoundRobin - La charge est répartie entre les adresses selon une stratégie round-robin.
• ConnOpenRandom - Un nœud est sélectionné aléatoirement dans la liste des adresses.

Ce comportement peut être contrôlé via l’option 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
}

Exemple complet

​

Pool de connexions

Le client maintient un pool de connexions et les réutilise entre les requêtes selon les besoins. À tout moment, le nombre de connexions utilisées ne dépassera pas MaxOpenConns, tandis que la taille maximale du pool est contrôlée par MaxIdleConns. Le client récupère une connexion dans le pool pour chaque exécution de requête, puis la remet dans le pool pour qu’elle soit réutilisée. Une connexion est utilisée pendant toute la durée de vie d’un batch et libérée lors de Send().

Rien ne garantit que la même connexion du pool sera utilisée pour les requêtes suivantes, sauf si l’utilisateur définit MaxOpenConns=1. Cela est rarement nécessaire, mais peut être requis lorsque des utilisateurs emploient des tables temporaires.

Notez également que ConnMaxLifetime vaut par défaut 1 heure. Cela peut entraîner un déséquilibre de charge sur ClickHouse si des nœuds quittent le cluster. Cela peut se produire lorsqu’un nœud devient indisponible : les connexions se répartissent alors sur les autres nœuds. Par défaut, ces connexions persistent et ne sont pas renouvelées avant 1 heure, même si le nœud défaillant réintègre le cluster. Envisagez de réduire cette valeur en cas de forte charge.

Le pool de connexions est activé pour Native (TCP) et pour le protocole HTTP.

​

Journalisation

Le client prend en charge la journalisation structurée via le paquet standard log/slog de Go, à l’aide du champ Logger dans Options. Les anciens champs Debug et Debugf sont obsolètes, mais fonctionnent toujours pour assurer la rétrocompatibilité (priorité : Debugf > Logger > no-op).

import (
    "log/slog"
    "os"
)

// JSON structured logging
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,
})

Vous pouvez également enrichir le logger avec un contexte applicatif :

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

Exemple complet

​

Compression

La prise en charge des méthodes de compression dépend du protocole sous-jacent utilisé. Pour le protocole natif, le client prend en charge la compression LZ4 et ZSTD. Celle-ci s’effectue uniquement au niveau des blocs. La compression peut être activée en incluant une configuration Compression dans la connexion.

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
}

Exemple complet

D’autres techniques de compression sont disponibles lors de l’utilisation du transport HTTP : gzip, deflate et br. Consultez API Database/SQL - Compression pour plus d’informations.

​

TCP vs HTTP

Le transport se change via un simple paramètre de config — tout le reste de ce guide s’applique aux deux. Voici ce qui change :

	TCP (protocole natif)	HTTP
Port par défaut	9000 (non chiffré), 9440 (TLS)	8123 (non chiffré), 8443 (TLS)
Activation	Par défaut — omettez Protocol	Protocol: clickhouse.HTTP ou utilisez un DSN http://
Compression	lz4, zstd	lz4, zstd, gzip, deflate, br
Sessions	Intégrées (toujours actives)	Explicite — transmettez session_id comme paramètre de configuration
En-têtes HTTP	—	HttpHeaders, HttpUrlPath, HttpMaxConnsPerHost
Transport personnalisé	—	TransportFunc
Authentification JWT	—	GetJWT (ClickHouse Cloud HTTPS)
OpenTelemetry (WithSpan)	✅	Le serveur le prend en charge ; le client n’envoie pas encore l’en-tête traceparent

Pour basculer l’une ou l’autre API vers HTTP :

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

// database/sql over HTTP — via Options
conn := clickhouse.OpenDB(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... auth, etc.
})

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