Référence de configuration du client Go

Cette page répertorie toutes les options configurables de clickhouse-go v2.x. Pour un guide avec des exemples de code, consultez Configuration.

Les options existent à trois niveaux :

Lorsque plusieurs portées se chevauchent, la plus spécifique l'emporte : Batch > Requête > Connexion. Pour Settings, les clés au niveau de la requête sont fusionnées avec celles au niveau de la connexion, et celles de la requête l'emportent en cas de conflit.

Via la struct 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},
})

À l’aide d’une chaîne DSN :

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

Par le connecteur (database/sql avec la structure Options) :

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Set database/sql-only pool settings after creation
db.SetConnMaxIdleTime(5 * time.Minute)

Via le contexte (par requête) :

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query-123"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)
rows, err := conn.Query(ctx, "SELECT ...")

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

Voir le pool de connexions pour plus de détails sur l'utilisation.

Lorsque vous utilisez clickhouse.OpenDB() ou sql.Open("clickhouse", dsn), le *sql.DB renvoyé prend en charge les méthodes standard de gestion du pool de Go. OpenDB() applique automatiquement les trois premières à partir de Options :

Prise en charge des méthodes de compression par protocole :

Voir TLS pour des exemples de code.

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

Consultez Journalisation pour voir des exemples complets.

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

ClientInfo: clickhouse.ClientInfo{
    Products: []struct{ Name, Version string }{
        {Name: "my-service", Version: "1.0.0"},
    },
}
// Appears as: clickhouse-go/2.x my-service/1.0.0 (lv:go/1.23; os:linux)

Paramètres courants :

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // important -- errors if unknown
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // custom -- ignored if unknown
}

Définissez-les pour chaque requête à l’aide de clickhouse.Context() :

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

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

Passées à PrepareBatch(). Import : github.com/ClickHouse/clickhouse-go/v2/lib/driver.

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

Cause : Pool de connexions épuisé : toutes les connexions MaxOpenConns sont utilisées et aucune n’est redevenue disponible avant l’expiration de DialTimeout.

Correctif

Essayez les étapes suivantes dans l’ordre et identifiez la cause sous-jacente avant d’ajuster les paramètres :

1. Vérifiez si des requêtes longues monopolisent des connexions : SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. Si c’est le cas, commencez par corriger les requêtes lentes.
2. Si vous exécutez des batchs de longue durée (minutes/heures entre PrepareBatch() et Send()), utilisez WithReleaseConnection() pour libérer la connexion et la remettre dans le pool pendant que le batch reste ouvert.
3. Augmentez MaxOpenConns pour l’aligner sur la concurrence observée.
4. Augmentez DialTimeout uniquement si des pics de charge sont attendus et que le temps d’attente pour obtenir une connexion est le véritable goulot d’étranglement.

Cause : ReadTimeout a été dépassé pendant l’attente d’une réponse du serveur, ou la connexion a été fermée par le serveur ou le réseau.

Correctif :

• Augmentez ReadTimeout pour les requêtes de longue durée
• Utilisez des délais d’expiration du contexte pour contrôler le timeout de chaque requête
• Vérifiez les limites max_execution_time côté serveur dans ClickHouse

Cause : Nom d’utilisateur ou mot de passe incorrect, ou utilisateur inexistant.

Solution :

• Vérifiez les identifiants dans la table system.users
• Vérifiez qu’il n’y a pas de problème d’encodage d’URL des caractères spéciaux dans les mots de passe du DSN
• Confirmez que l’utilisateur a accès à la base de données spécifiée

Cause : accumulation de buffers de connexions inactives de grande taille.

Correctif :

• Définissez FreeBufOnConnRelease: true dans les environnements à mémoire limitée
• Réduisez MaxIdleConns pour limiter le nombre de connexions inactives
• Réduisez MaxCompressionBuffer si vous utilisez la compression
• Réduisez ConnMaxLifetime pour recycler les connexions plus fréquemment