ClickHouse Go

Início rápido

Vamos começar com um exemplo simples. Ele se conectará ao ClickHouse e fará uma consulta no banco de dados do sistema. Para começar, você precisará dos detalhes de conexão.

Detalhes da conexão

Para se conectar ao ClickHouse com TCP nativo, você precisa destas informações:

Parâmetros	Descrição
`HOST` e `PORT`	Normalmente, a porta é 9440 ao usar TLS, ou 9000 quando não se usa TLS.
`DATABASE NAME`	Por padrão, há um banco de dados chamado `default`; use o nome do banco de dados ao qual você quer se conectar.
`USERNAME` e `PASSWORD`	Por padrão, o nome de usuário é `default`. Use o nome de usuário apropriado para o seu caso de uso.

Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud. Selecione o serviço ao qual você vai se conectar e clique em Connect:

Escolha Native; os detalhes estarão disponíveis em um comando clickhouse-client de exemplo.

Detalhes da conexão TCP nativa do ClickHouse Cloud

Se você estiver usando ClickHouse autogerenciado, os detalhes da conexão serão definidos pelo administrador do ClickHouse.

Inicialize um módulo

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

Copie um código de exemplo

Copie este código para o diretório clickhouse-golang-example com o nome 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)
    }

    // NOTA: Não omita a verificação de rows.Err()
    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
}

Execute o comando go mod tidy

go mod tidy

Defina os detalhes da conexão

Antes, você consultou os detalhes da conexão. Defina-os em main.go, na função 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>",
      },

Execute o exemplo

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

Saiba mais

O restante da documentação desta categoria aborda os detalhes do cliente Go para ClickHouse.

Visão geral

O ClickHouse oferece dois clientes Go oficiais. Eles são complementares e foram projetados intencionalmente para atender a diferentes casos de uso.

clickhouse-go - Cliente de alto nível que oferece suporte tanto à interface padrão database/sql do Go quanto à API nativa do ClickHouse.
ch-go - Cliente de baixo nível. Apenas interface nativa.

O clickhouse-go fornece uma interface de alto nível, permitindo que os usuários façam consultas e insiram dados com semântica orientada a linhas e processamento em lote, com tolerância a tipos de dados — os valores serão convertidos desde que isso não implique perda potencial de precisão. Já o ch-go fornece uma interface otimizada orientada a colunas, oferecendo streaming rápido de blocos de dados com baixa sobrecarga de CPU e memória, em troca de maior rigor de tipos e de um uso mais complexo. A partir da versão 2.3, o clickhouse-go utiliza o ch-go para funções de baixo nível, como codificação, decodificação e compressão. Ambos os clientes usam o formato nativo para codificação, a fim de oferecer desempenho ideal, e podem se comunicar pelo protocolo nativo do ClickHouse. O clickhouse-go também oferece suporte a HTTP como mecanismo de transporte para casos em que os usuários precisam usar proxy ou fazer balanceamento de carga do tráfego.

Quatro maneiras de se conectar

clickhouse-go oferece duas escolhas independentes: qual API usar e qual transporte usar. Elas se combinam em quatro modos de conexão:

	TCP (protocolo nativo, porta 9000/9440)	HTTP (porta 8123/8443)
ClickHouse API (`clickhouse.Open`)	Padrão — melhor desempenho	Defina `Protocol: clickhouse.HTTP`
`database/sql` API (`OpenDB` / `sql.Open`)	`clickhouse://host:9000`	`http://host:8123`

Escolhendo uma API: Escolha a ClickHouse API para obter o máximo desempenho e o conjunto completo de recursos (callbacks de progresso, inserções colunares, suporte avançado a tipos). Escolha database/sql quando precisar integrar com ORMs ou ferramentas que esperam uma interface padrão de banco de dados do Go. Escolhendo um transporte: TCP é mais rápido e é o padrão. Mude para HTTP quando sua infraestrutura exigir isso — por exemplo, ao se conectar por meio de um balanceador de carga HTTP ou proxy, ou quando precisar de recursos específicos de HTTP, como sessões com tabelas temporárias, ou algoritmos adicionais de compressão (gzip, deflate, br). Ambas as APIs usam a codificação binária nativa independentemente do transporte, portanto o HTTP não adiciona sobrecarga de serialização.

	Native format	Transporte TCP	Transporte HTTP	Escrita em massa	Marshaling de structs	Compressão	Callbacks de progresso
ClickHouse API	✅	✅	✅	✅	✅	✅	✅
`database/sql` API	✅	✅	✅	✅		✅

Escolhendo um cliente

A escolha de uma biblioteca cliente depende dos seus padrões de uso e da necessidade de obter o melhor desempenho. Para casos de uso com muitas inserções, em que são necessárias milhões de inserções por segundo, recomendamos usar o cliente de baixo nível ch-go. Esse cliente evita a sobrecarga de converter os dados de um formato orientado a linhas para colunas, como exige o formato nativo do ClickHouse. Além disso, dispensa reflection e o uso do tipo interface{} (any), o que simplifica o uso. Para cargas de trabalho de consulta focadas em agregações ou cargas de trabalho de inserção com menor vazão, o clickhouse-go oferece uma interface database/sql familiar e uma semântica baseada em linhas mais simples. Você também pode usar HTTP opcionalmente como protocolo de transporte e aproveitar funções auxiliares para converter linhas de e para structs.

	Formato nativo	Protocolo nativo	Protocolo HTTP	API orientada a linhas	API orientada a colunas	Flexibilidade de tipos	Compressão	Placeholders de consulta
clickhouse-go	✅	✅	✅	✅	✅	✅	✅	✅
ch-go	✅	✅			✅		✅

Instalação

A v1 do driver está obsoleta e não receberá atualizações de recursos nem suporte a novos tipos do ClickHouse. Você deve migrar para a v2, que oferece desempenho superior. Para instalar a versão 2.x do cliente, adicione o pacote ao arquivo go.mod: require github.com/ClickHouse/clickhouse-go/v2 main Ou clone o repositório:

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

Para instalar outra versão, modifique o caminho ou o nome da branch conforme apropriado.

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

Controle de versão

O cliente é lançado independentemente do ClickHouse. A série 2.x representa a atual versão principal em desenvolvimento. Todas as versões da série 2.x devem ser compatíveis entre si.

Compatibilidade com ClickHouse

O cliente oferece suporte a:

Todas as versões do ClickHouse com suporte atualmente, conforme listado aqui. Quando uma versão do ClickHouse deixa de ter suporte, ela também deixa de ser testada ativamente nos lançamentos do cliente.
Todas as versões do ClickHouse lançadas nos 2 anos anteriores à data de lançamento do cliente. Observe que apenas as versões LTS são testadas ativamente.

Compatibilidade do Golang

Versão do cliente	Versões do Golang
=> 2.0 <= 2.2	1.17, 1.18
>= 2.3, < 2.41	1.18+
>= 2.41	1.21+
>= 2.43	1.24+

Boas práticas

Utilize a API do ClickHouse sempre que possível, especialmente para tipos primitivos. Isso evita reflexão e indireção significativas.
Se estiver lendo grandes conjuntos de dados, considere modificar o BlockBufferSize. Isso aumentará o uso de memória, mas permitirá que mais blocos sejam decodificados em paralelo durante a iteração pelas linhas. O valor padrão de 2 é conservador e minimiza a sobrecarga de memória. Valores mais altos significam mais blocos na memória. Isso exige testes, já que consultas diferentes podem produzir blocos de tamanhos diferentes. Portanto, isso pode ser definido no nível da consulta por meio do Context.
Seja específico com os tipos ao inserir dados. Embora o cliente procure ser flexível, por exemplo, permitindo analisar strings como UUIDs ou IPs, isso exige validação de dados e tem um custo no momento da inserção.
Use inserções orientadas a colunas sempre que possível. Novamente, elas devem ter tipagem forte, evitando que o cliente precise converter seus valores.
Siga as recomendações do ClickHouse para obter o melhor desempenho de inserção.

Próximos passos

Configuração — configurações de conexão, TLS, autenticação, logging, compressão
ClickHouse API — API nativa do Go para consultas e inserções
API de banco de dados/SQL — interface padrão database/sql
Tipos de dados — mapeamentos de tipos do Go e suporte a tipos complexos

Início

JavaScript

Python

Java

C++

C

Clientes de terceiros

Início rápido

Detalhes da conexão

Inicialize um módulo

Copie um código de exemplo

Execute o comando go mod tidy

Defina os detalhes da conexão

Execute o exemplo

Saiba mais

Visão geral

Quatro maneiras de se conectar

Escolhendo um cliente

Instalação

Controle de versão

Compatibilidade com ClickHouse

Compatibilidade do Golang

Boas práticas

Próximos passos

​Início rápido

​Detalhes da conexão

​Inicialize um módulo

​Copie um código de exemplo

​Execute o comando go mod tidy

​Defina os detalhes da conexão

​Execute o exemplo

​Saiba mais

​Visão geral

​Quatro maneiras de se conectar

​Escolhendo um cliente

​Instalação

​Controle de versão

​Compatibilidade com ClickHouse

​Compatibilidade do Golang

​Boas práticas

​Próximos passos

Início rápido

Detalhes da conexão

Inicialize um módulo

Copie um código de exemplo

Execute o comando go mod tidy

Defina os detalhes da conexão

Execute o exemplo

Saiba mais

Visão geral

Quatro maneiras de se conectar

Escolhendo um cliente

Instalação

Controle de versão

Compatibilidade com ClickHouse

Compatibilidade do Golang

Boas práticas

Próximos passos