ClickHouse Go

Les clients Go de ClickHouse permettent de se connecter à ClickHouse via l’interface standard Go database/sql ou via une interface native optimisée.

​

Démarrage rapide

Commençons par un exemple simple. Il se connectera à ClickHouse et exécutera une requête SELECT sur la base de données système. Pour commencer, vous aurez besoin de vos détails de connexion.

​

Détails de connexion

Pour vous connecter à ClickHouse via TCP natif, vous avez besoin des informations suivantes :

Paramètres	Description
HOST and PORT	En général, le port est 9440 lorsque vous utilisez TLS, ou 9000 lorsque vous ne l’utilisez pas.
DATABASE NAME	Par défaut, une base de données nommée default existe ; utilisez le nom de la base de données à laquelle vous souhaitez vous connecter.
USERNAME and PASSWORD	Par défaut, le nom d’utilisateur est default. Utilisez le nom d’utilisateur adapté à votre cas d’usage.

Les détails de votre service ClickHouse Cloud sont disponibles dans la console ClickHouse Cloud. Sélectionnez le service auquel vous allez vous connecter, puis cliquez sur Connect :

Choisissez Native ; les détails sont disponibles dans un exemple de commande clickhouse-client.

Si vous utilisez une instance ClickHouse autogérée, les détails de connexion sont définis par votre administrateur ClickHouse.

​

Initialiser un module

mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example

​

Copiez un exemple de code

Copiez ce code dans le répertoire clickhouse-golang-example sous le nom main.go.

main.go

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "log"

    "github.com/ClickHouse/clickhouse-go/v2"
    "github.com/ClickHouse/clickhouse-go/v2/lib/driver"
)

func main() {
    conn, err := connect()
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    rows, err := conn.Query(ctx, "SELECT name, toString(uuid) as uuid_str FROM system.tables LIMIT 5")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var name, uuid string
        if err := rows.Scan(&name, &uuid); err != nil {
            log.Fatal(err)
        }
        log.Printf("name: %s, uuid: %s", name, uuid)
    }

    // NOTE: Do not skip rows.Err() check
    if err := rows.Err(); err != nil {
        log.Fatal(err)
    }

}

func connect() (driver.Conn, error) {
    var (
        ctx       = context.Background()
        conn, err = clickhouse.Open(&clickhouse.Options{
            Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
            Auth: clickhouse.Auth{
                Database: "default",
                Username: "default",
                Password: "<DEFAULT_USER_PASSWORD>",
            },
            ClientInfo: clickhouse.ClientInfo{
                Products: []struct {
                    Name    string
                    Version string
                }{
                    {Name: "an-example-go-client", Version: "0.1"},
                },
            },
            Debugf: func(format string, v ...interface{}) {
                fmt.Printf(format, v)
            },
            TLS: &tls.Config{
                InsecureSkipVerify: true,
            },
        })
    )

    if err != nil {
        return nil, err
    }

    if err := conn.Ping(ctx); err != nil {
        if exception, ok := err.(*clickhouse.Exception); ok {
            fmt.Printf("Exception [%d] %s \n%s\n", exception.Code, exception.Message, exception.StackTrace)
        }
        return nil, err
    }
    return conn, nil
}

​

Lancez go mod tidy

go mod tidy

​

Configurez vos détails de connexion

Vous avez relevé précédemment vos détails de connexion. Définissez-les dans main.go, dans la fonction connect() :

func connect() (driver.Conn, error) {
  var (
    ctx       = context.Background()
    conn, err = clickhouse.Open(&clickhouse.Options{
      Addr: []string{"<CLICKHOUSE_SECURE_NATIVE_HOSTNAME>:9440"},
      Auth: clickhouse.Auth{
        Database: "default",
        Username: "default",
        Password: "<DEFAULT_USER_PASSWORD>",
      },

​

Exécuter l’exemple

go run .

2023/03/06 14:18:33 name: COLUMNS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: SCHEMATA, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: TABLES, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: VIEWS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: hourly_data, uuid: a4e36bd4-1e82-45b3-be77-74a0fe65c52b

​

En savoir plus

Le reste de la documentation de cette catégorie présente en détail le client Go de ClickHouse.

​

Vue d’ensemble

ClickHouse prend en charge deux clients Go officiels. Ces clients sont complémentaires et prennent délibérément en charge des cas d’usage différents.

• clickhouse-go - Client Go de haut niveau qui prend en charge soit l’interface database/sql standard de Go, soit l’API native de ClickHouse.
• ch-go - Client de bas niveau. Interface native uniquement.

clickhouse-go fournit une interface de haut niveau, permettant aux utilisateurs d’exécuter des requêtes et d’insérer des données avec une sémantique orientée ligne et un traitement par lots tolérant vis-à-vis des types de données : les valeurs sont converties tant qu’aucune perte de précision n’est à craindre. ch-go, quant à lui, fournit une interface optimisée orientée colonne, permettant le streaming rapide de blocs de données avec une faible surcharge en CPU et en mémoire, au prix de contrôles de type plus stricts et d’une utilisation plus complexe.

À partir de la version 2.3, clickhouse-go utilise ch-go pour les fonctions de bas niveau telles que l’encodage, le décodage et la compression. Les deux clients utilisent le format natif pour leur encodage afin d’offrir des performances optimales et peuvent communiquer via le protocole natif de ClickHouse. clickhouse-go prend également en charge HTTP comme mécanisme de transport lorsque les utilisateurs ont besoin de faire transiter le trafic via un proxy ou d’équilibrer la charge.

​

Quatre façons de se connecter

clickhouse-go vous offre deux choix indépendants : quelle API utiliser et quel transport utiliser. Ces deux choix se combinent en quatre modes de connexion :

	TCP (protocole natif, port 9000/9440)	HTTP (port 8123/8443)
ClickHouse API (clickhouse.Open)	Par défaut — meilleures performances	Définissez Protocol: clickhouse.HTTP
database/sql API (OpenDB / sql.Open)	clickhouse://host:9000	http://host:8123

Choisir une API : choisissez la ClickHouse API pour des performances maximales et l’ensemble complet des fonctionnalités (callbacks de progression, insertions en colonnes, prise en charge étendue des types). Choisissez database/sql lorsque vous devez l’intégrer à des ORM ou à des outils qui attendent une interface Go standard de base de données.

Choisir un transport : TCP est plus rapide et c’est le mode par défaut. Passez à HTTP lorsque votre infrastructure l’exige — par exemple, si vous vous connectez via un proxy HTTP ou un load balancer HTTP, ou si vous avez besoin de fonctionnalités propres à HTTP comme les sessions avec des tables temporaires, ou d’algorithmes de Compression supplémentaires (gzip, deflate, br).

Les deux API utilisent l’encodage binaire natif quel que soit le transport, donc HTTP n’ajoute aucun surcoût de sérialisation.

	Native format	Transport TCP	Transport HTTP	Écriture par lots	Sérialisation de struct	Compression	Callbacks de progression
ClickHouse API	✅	✅	✅	✅	✅	✅	✅
database/sql API	✅	✅	✅	✅		✅

​

Choisir un client

Le choix d’une bibliothèque client dépend de vos usages et de votre besoin de performances optimales. Pour les cas d’usage nécessitant un grand nombre d’insertions, où des millions d’insertions par seconde sont requises, nous recommandons d’utiliser le client bas niveau ch-go. Ce client évite le surcoût lié à la conversion des données d’un format orienté lignes vers des colonnes, comme l’exige le format natif de ClickHouse. En outre, il évite tout recours à la réflexion ou au type interface{} (any), ce qui simplifie son utilisation.

Pour les workloads de requête axés sur les agrégations, ou pour des workloads d’insertion à plus faible débit, clickhouse-go fournit une interface database/sql familière et une sémantique orientée lignes plus simple. Vous pouvez également utiliser HTTP comme protocole de transport, si nécessaire, et tirer parti de fonctions utilitaires pour sérialiser et désérialiser des lignes vers et depuis des structs.

	Format natif	Protocole natif	Protocole HTTP	API orientée lignes	API orientée colonnes	Souplesse des types	Compression	Placeholders de requête
clickhouse-go	✅	✅	✅	✅	✅	✅	✅	✅
ch-go	✅	✅			✅		✅

​

Installation

La v1 du pilote est obsolète et ne recevra plus de mises à jour de fonctionnalités ni de prise en charge des nouveaux types ClickHouse. Nous vous recommandons de migrer vers la v2, qui offre de meilleures performances.

Pour installer la version 2.x du client, ajoutez le paquet à votre fichier go.mod :

require github.com/ClickHouse/clickhouse-go/v2 main

Ou clonez le dépôt :

git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github

Pour installer une autre version, modifiez le chemin ou le nom de la branche en conséquence.

mkdir my-clickhouse-app && cd my-clickhouse-app

cat > go.mod <<-END
  module my-clickhouse-app

  go 1.21

  require github.com/ClickHouse/clickhouse-go/v2 main
END

cat > main.go <<-END
  package main

  import (
    "fmt"
    "github.com/ClickHouse/clickhouse-go/v2"
  )

  func main() {
   conn, _ := clickhouse.Open(&clickhouse.Options{Addr: []string{"127.0.0.1:9000"}})
    v, _ := conn.ServerVersion()
    fmt.Println(v.String())
  }
END

go mod tidy
go run main.go

​

Versions

Le client est publié indépendamment de ClickHouse. La branche 2.x correspond à la version majeure actuellement en cours de développement. Toutes les versions 2.x devraient être compatibles entre elles.

​

Compatibilité avec ClickHouse

Le client prend en charge :

• Toutes les versions de ClickHouse actuellement prises en charge, comme indiqué ici. Lorsqu’une version de ClickHouse n’est plus prise en charge, elle n’est plus non plus testée activement avec les versions du client.
• Toutes les versions de ClickHouse pendant les 2 ans suivant la date de sortie du client. Notez que seules les versions LTS sont testées activement.

​

Compatibilité de Golang

Version du client	Versions de Golang
=> 2.0 <= 2.2	1.17, 1.18
>= 2.3, < 2.41	1.18+
>= 2.41	1.21+
>= 2.43	1.24+

​

Bonnes pratiques

• Utilisez l’ClickHouse API lorsque c’est possible, en particulier pour les types primitifs. Cela évite une réflexion et une indirection importantes.
• Si vous lisez de grands jeux de données, envisagez de modifier le paramètre BlockBufferSize. Cela augmentera l’empreinte mémoire, mais permettra de décoder davantage de blocs en parallèle lors de l’itération sur les lignes. La valeur par défaut de 2 est prudente et minimise la surcharge mémoire. Des valeurs plus élevées signifient davantage de blocs en mémoire. Cela nécessite donc des tests, car différentes requêtes peuvent produire des tailles de bloc différentes. Ce paramètre peut donc être défini au niveau de la requête via le Context.
• Soyez précis quant à vos types lors de l’insertion de données. Bien que le client cherche à être flexible, par exemple en permettant d’analyser des chaînes en UUID ou en adresses IP, cela nécessite une validation des données et entraîne un coût au moment de l’insertion.
• Utilisez des insertions orientées colonnes lorsque c’est possible. Là encore, elles doivent être fortement typées afin d’éviter que le client n’ait à convertir vos valeurs.
• Suivez les recommandations de ClickHouse pour obtenir des performances d’insertion optimales.

​

Étapes suivantes

• Configuration — paramètres de connexion, TLS, authentification, journalisation, compression
• ClickHouse API — API Go native pour les requêtes et les insertions
• API database/sql — interface database/sql standard
• Types de données — correspondances de types Go et prise en charge des types complexes