Início rápido
Detalhes da conexão
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
Copie um código de exemplo
clickhouse-golang-example com o nome main.go.
main.go
Execute o comando go mod tidy
Defina os detalhes da conexão
main.go, na função connect():
Execute o exemplo
Saiba mais
Visão geral
- clickhouse-go - Cliente de alto nível que oferece suporte tanto à interface padrão
database/sqldo Go quanto à API nativa do ClickHouse. - ch-go - Cliente de baixo nível. Apenas interface nativa.
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:
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.
Escolhendo um cliente
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.
Instalação
require github.com/ClickHouse/clickhouse-go/v2 main
Ou clone o repositório:
Controle de versão
Compatibilidade com ClickHouse
- 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
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