> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Les clients Go de ClickHouse permettent de se connecter à ClickHouse via l'interface standard Go `database/sql` ou via une interface native optimisée.
# ClickHouse Go
## 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
```bash theme={null}
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`.
```go title=main.go theme={null}
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{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
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
```bash theme={null}
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()` :
```go highlight={5,7-9} theme={null}
func connect() (driver.Conn, error) {
var (
ctx = context.Background()
conn, err = clickhouse.Open(&clickhouse.Options{
Addr: []string{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
Password: "",
},
```
### Exécuter l’exemple
```bash theme={null}
go run .
```
```response theme={null}
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](https://github.com/ClickHouse/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](https://github.com/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](https://github.com/ClickHouse/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](https://github.com/ClickHouse/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 :
```bash theme={null}
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.
```bash theme={null}
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](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). 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`](/fr/integrations/language-clients/go/configuration#connection-settings). 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](/fr/integrations/language-clients/go/clickhouse-api#using-context) 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](/fr/reference/statements/insert-into#performance-considerations) de ClickHouse pour obtenir des performances d’insertion optimales.
## Étapes suivantes
* [Configuration](/fr/integrations/language-clients/go/configuration) — paramètres de connexion, TLS, authentification, journalisation, compression
* [ClickHouse API](/fr/integrations/language-clients/go/clickhouse-api) — API Go native pour les requêtes et les insertions
* [API database/sql](/fr/integrations/language-clients/go/database-sql-api) — interface `database/sql` standard
* [Types de données](/fr/integrations/language-clients/go/data-types) — correspondances de types Go et prise en charge des types complexes