ClickHouse Go

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.

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

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.

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

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

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

go mod tidy

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

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

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

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.

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

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.

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.

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

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.

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.

• 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.

• 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