database/sql, ou API “padrão”, permite usar o cliente em cenários nos quais o código da aplicação deve ser agnóstico em relação aos bancos de dados subjacentes, seguindo uma interface padrão. Isso tem um custo: camadas adicionais de abstração e indireção, além de primitivos que nem sempre estão alinhados ao ClickHouse. Ainda assim, esses custos normalmente são aceitáveis em cenários nos quais as ferramentas precisam se conectar a vários bancos de dados.
Além disso, este cliente oferece suporte ao uso de HTTP como camada de transporte — os dados ainda serão codificados no formato Native para desempenho ideal.
Conexão
A conexão pode ser feita por meio de uma string DSN no formatoclickhouse://<host>:<port>?<query_option>=<value> com o método Open, ou por meio do método clickhouse.OpenDB. Este último não faz parte da especificação database/sql, mas retorna uma instância de sql.DB. Esse método oferece funcionalidades como profiling, para as quais não há uma forma óbvia de exposição pela especificação database/sql.
conn do ClickHouse já foi criada e está disponível.
Configurações de conexão
A maioria das opções de configuração é compartilhada com a ClickHouse API. Consulte Configuração para ver as configurações compartilhadas. Os seguintes parâmetros de DSN específicos de SQL estão disponíveis:hosts- lista separada por vírgulas de hosts com um único endereço para balanceamento de carga e failover - consulte Conexão com vários nós.username/password- credenciais de autenticação - consulte Autenticaçãodatabase- seleciona o banco de dados padrão atualdial_timeout- uma string de duração é uma sequência de números decimais, possivelmente com sinal, cada um com fração opcional e um sufixo de unidade, como300ms,1s. As unidades de tempo válidas sãoms,s,m.connection_open_strategy-random/in_order(o padrão érandom) - consulte Conexão com vários nósround_robin- seleciona um servidor do conjunto em round-robinin_order- o primeiro servidor ativo é escolhido na ordem especificada
debug- habilita a saída de depuração (valor booleano)compress- especifica o algoritmo de compressão -none(padrão),zstd,lz4,gzip,deflate,br. Se definido comotrue,lz4será usado. Somentelz4ezstdsão compatíveis com a comunicação nativa.compress_level- nível de compressão (o padrão é0). Consulte compressão. Isso é específico do algoritmo:gzip--2(Melhor velocidade) a9(Melhor compressão)deflate--2(Melhor velocidade) a9(Melhor compressão)br-0(Melhor velocidade) a11(Melhor compressão)zstd,lz4- ignorado
secure- estabelece uma conexão SSL segura (o padrão éfalse)skip_verify- ignora a verificação do certificado (o padrão éfalse)block_buffer_size- permite controlar o tamanho do buffer de bloco. ConsulteBlockBufferSize. (o padrão é2)
Conexão via HTTP
Por padrão, as conexões são estabelecidas pelo protocolo nativo. Para usuários que precisem de HTTP, isso pode ser habilitado modificando o DSN para incluir o protocolo HTTP ou especificando o protocolo nas opções de conexão.Sessões
Somente HTTPAs sessões só são necessárias ao usar o transporte HTTP. As conexões TCP nativas já têm uma sessão integrada automaticamente.
session_id como configuração para habilitar recursos vinculados à sessão, como tabelas temporárias.
Execução
Após obter uma conexão, você pode executar instruçõessql por meio do método Exec.
ExecContext — consulte Usando contexto.
Inserção em lote
É possível obter a semântica de lote criando umsql.Tx por meio do método Being. A partir dele, é possível obter um lote usando o método Prepare com a instrução INSERT. Isso retorna um sql.Stmt, ao qual é possível adicionar linhas usando o método Exec. O lote será acumulado na memória até que Commit seja executado no sql.Tx original.
Consultando linhas
É possível consultar uma única linha usando o métodoQueryRow. Isso retorna um *sql.Row, no qual é possível invocar Scan com ponteiros para variáveis nas quais as colunas devem ser atribuídas. Uma variante QueryRowContext permite passar um contexto diferente de background - veja Usando Context.
Query. Ele retorna uma struct *sql.Rows, na qual o método Next pode ser chamado para percorrer as linhas. O equivalente QueryContext permite passar um contexto.
Inserção assíncrona
As inserções assíncronas podem ser feitas executando uma inserção por meio do métodoExecContext. Para isso, passe a ele um contexto com o modo assíncrono habilitado, como mostrado abaixo. Isso permite que o usuário especifique se o cliente deve aguardar o servidor concluir a inserção ou responder assim que os dados forem recebidos. Isso controla efetivamente o parâmetro wait_for_async_insert.
Parâmetros de consulta do lado do servidor
A API padrão oferece suporte a parâmetros de consulta do lado do servidor do ClickHouse por meio de marcadores tipados{name:Type} e valores clickhouse.Named:
string/*string ou []byte/*[]byte passado via clickhouse.Named é tratado como valor literal e escapado pelo driver, de modo que faz a ida e volta byte a byte sem alterações. Use uma quebra de linha ou tabulação real no valor Go quando for isso que você quiser no wire:
Escaped do ClickHouse, use WithParameters; consulte Parâmetros de consulta do lado do servidor para uma explicação completa sobre tipos, escaping e as diferenças entre {name:Type} e a vinculação do lado do cliente.
Exemplo completo com a API padrão
Vinculação de parâmetros
A API padrão oferece os mesmos recursos de vinculação de parâmetros da ClickHouse API, permitindo passar parâmetros aos métodosExec, Query e QueryRow (e às variantes equivalentes de Context). Há suporte a parâmetros posicionais, nomeados e numerados.
Usando contexto
A API padrão oferece a mesma capacidade de transmitir prazos, sinais de cancelamento e outros valores com escopo de requisição por meio do contexto que a ClickHouse API. Diferentemente da ClickHouse API, isso é feito usando variantesContext dos métodos; ou seja, métodos como Exec, que usam o contexto de background por padrão, têm uma variante ExecContext, à qual um contexto pode ser passado como primeiro parâmetro. Isso permite passar um contexto em qualquer etapa do fluxo de uma aplicação. Por exemplo, você pode passar um contexto ao estabelecer uma conexão via ConnContext ou ao solicitar uma linha de consulta via QueryRowContext. Exemplos de todos os métodos disponíveis são mostrados abaixo.
Para mais detalhes sobre como usar o contexto para transmitir prazos, sinais de cancelamento, IDs de consulta, chaves de quota e configurações de conexão, consulte Usando contexto da ClickHouse API.
Escaneamento dinâmico
Assim como na ClickHouse API, as informações sobre o tipo da coluna ficam disponíveis para que você possa criar, em tempo de execução, instâncias de variáveis com a tipagem correta que podem ser passadas para o Scan. Isso permite ler colunas mesmo quando o tipo não é conhecido.Tabelas externas
Tabelas externas permitem que o cliente envie dados ao ClickHouse com uma consultaSELECT. Esses dados são colocados em uma tabela temporária e podem ser usados na própria consulta para avaliação.
Para enviar dados externos junto com uma consulta, o usuário deve criar uma tabela externa por meio de ext.NewTable antes de passá-la pelo contexto.
OpenTelemetry
O ClickHouse oferece suporte à propagação de contexto de rastreamento nos transportes TCP e HTTP. Useclickhouse.WithSpan para associar um span a uma consulta por meio do contexto.
Limitação do transporte HTTPEmbora o servidor ClickHouse aceite os cabeçalhos HTTP padrão
traceparent / tracestate, o transporte HTTP do clickhouse-go ainda não os envia — WithSpan não tem efeito via HTTP. Como alternativa, você pode definir o cabeçalho manualmente por meio de HttpHeaders nas opções de conexão.Compressão
A API padrão oferece suporte aos mesmos algoritmos de compressão da ClickHouse API, ou seja, compressãolz4 e zstd no nível de bloco. Além disso, gzip, deflate e br também são compatíveis com conexões HTTP. Se qualquer um deles estiver habilitado, a compressão será aplicada aos blocos durante a inserção e às respostas de consulta. Outras requisições, como pings ou requisições de consulta, permanecerão sem compressão. Isso é consistente com as opções lz4 e zstd.
Se você usar o método OpenDB para estabelecer uma conexão, poderá passar uma configuração de compressão. Isso inclui a possibilidade de especificar o nível de compressão (veja abaixo). Se a conexão for feita via sql.Open com DSN, use o parâmetro compress. Ele pode ser um algoritmo de compressão específico, ou seja, gzip, deflate, br, zstd ou lz4, ou uma flag booleana. Se definido como true, lz4 será usado. O padrão é none, ou seja, compressão desabilitada.
compress_level da DSN ou pelo campo Level da opção Compression. O padrão é 0, mas varia conforme o algoritmo:
gzip--2(Maior velocidade) a9(Melhor compressão)deflate--2(Maior velocidade) a9(Melhor compressão)br-0(Maior velocidade) a11(Melhor compressão)zstd,lz4- ignorado