Pular para o conteúdo principal

​
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âmetrosDescrição
HOST e PORTNormalmente, a porta é 9440 ao usar TLS, ou 9000 quando não se usa TLS.
DATABASE NAMEPor padrão, há um banco de dados chamado default; use o nome do banco de dados ao qual você quer se conectar.
USERNAME e PASSWORDPor 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. 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 desempenhoDefina Protocol: clickhouse.HTTP
database/sql API (OpenDB / sql.Open)clickhouse://host:9000http://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 formatTransporte TCPTransporte HTTPEscrita em massaMarshaling de structsCompressãoCallbacks 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 nativoProtocolo nativoProtocolo HTTPAPI orientada a linhasAPI orientada a colunasFlexibilidade de tiposCompressãoPlaceholders 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 clienteVersões do Golang
=> 2.0 <= 2.21.17, 1.18
>= 2.3, < 2.411.18+
>= 2.411.21+
>= 2.431.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

Última modificação em 10 de junho de 2026