> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Os clientes Go para ClickHouse permitem conectar-se ao ClickHouse usando a interface padrão database/sql do Go ou uma interface nativa otimizada.

# ClickHouse Go

<div id="quick-start">
  ## Início rápido
</div>

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.

<div id="connection-details">
  ### Detalhes da conexão
</div>

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**:

<Image img="/images/_snippets/cloud-connect-button.webp" size="md" alt="Botão Connect do serviço do ClickHouse Cloud" border />

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

<Image img="/images/_snippets/connection-details-native.webp" size="md" alt="Detalhes da conexão TCP nativa do ClickHouse Cloud" border />

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

<div id="initialize-a-module">
  ### Inicialize um módulo
</div>

```bash theme={null}
mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example
```

<div id="copy-in-some-sample-code">
  ### Copie um código de exemplo
</div>

Copie este código para o diretório `clickhouse-golang-example` com o nome `main.go`.

```go title=main.go theme={null}
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
}
```

<div id="run-go-mod-tidy">
  ### Execute o comando go mod tidy
</div>

```bash theme={null}
go mod tidy
```

<div id="set-your-connection-details">
  ### Defina os detalhes da conexão
</div>

Antes, você consultou os detalhes da conexão. Defina-os em `main.go`, na função `connect()`:

```go highlight={5,7-9} theme={null}
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>",
      },
```

<div id="run-the-example">
  ### Execute o exemplo
</div>

```bash theme={null}
go run .
```

```response theme={null}
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
```

<div id="learn-more">
  ### Saiba mais
</div>

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

<div id="overview">
  ## Visão geral
</div>

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

* [clickhouse-go](https://github.com/ClickHouse/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](https://github.com/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.

<div id="four-ways-to-connect">
  ### Quatro maneiras de se conectar
</div>

`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 |       ✅       |        ✅       |        ✅        |         ✅        |                       |      ✅     |                        |

<div id="choosing-a-client">
  ### Escolhendo um cliente
</div>

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](https://github.com/ClickHouse/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](https://github.com/ClickHouse/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     |        ✅       |         ✅        |                |                        |            ✅            |                        |      ✅     |                          |

<div id="installation">
  ## Instalação
</div>

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:

```bash theme={null}
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.

```bash theme={null}
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

```

<div id="versioning">
  ### Controle de versão
</div>

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.

<div id="clickhouse-compatibility">
  #### Compatibilidade com ClickHouse
</div>

O cliente oferece suporte a:

* Todas as versões do ClickHouse com suporte atualmente, conforme listado [aqui](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). 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.

<div id="golang-compatibility">
  #### Compatibilidade do Golang
</div>

| 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+       |

<div id="best-practices">
  ## Boas práticas
</div>

* 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`](/pt-BR/integrations/language-clients/go/configuration#connection-settings). 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](/pt-BR/integrations/language-clients/go/clickhouse-api#using-context) 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](/pt-BR/reference/statements/insert-into#performance-considerations) do ClickHouse para obter o melhor desempenho de inserção.

<div id="next-steps">
  ## Próximos passos
</div>

* [Configuração](/pt-BR/integrations/language-clients/go/configuration) — configurações de conexão, TLS, autenticação, logging, compressão
* [ClickHouse API](/pt-BR/integrations/language-clients/go/clickhouse-api) — API nativa do Go para consultas e inserções
* [API de banco de dados/SQL](/pt-BR/integrations/language-clients/go/database-sql-api) — interface padrão `database/sql`
* [Tipos de dados](/pt-BR/integrations/language-clients/go/data-types) — mapeamentos de tipos do Go e suporte a tipos complexos