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

# Conectar ao ClickHouse

> Conecte-se aos serviços BYOC do ClickHouse por meio de balanceadores de carga públicos ou privados, ou endpoints privados (PrivateLink, Private Service Connect, Private Link)

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

Esta página descreve as diferentes formas de se conectar aos seus serviços do ClickHouse no BYOC. Você pode escolher entre balanceadores de carga públicos, balanceadores de carga privados ou endpoints privados (AWS PrivateLink, GCP Private Service Connect ou Azure Private Link), com base nos seus requisitos de segurança e rede.

<div id="connection-via">
  ## Selecionando um caminho de conexão no console
</div>

Os detalhes de conexão de cada serviço BYOC estão disponíveis no console do ClickHouse Cloud: abra o serviço e clique em **Connect**.

Para serviços BYOC, a caixa de diálogo **Connect** inclui um menu suspenso **Connection via**. Use-o para escolher como você acessa o serviço:

* **balanceador de carga público** — o endpoint voltado para a internet.
* **balanceador de carga privado** — o endpoint interno, acessado por VPC peering ou redes conectadas. Listado somente quando um [balanceador de carga privado](#private-load-balancer) está habilitado para sua infraestrutura.
* **PrivateLink** (AWS) / **Private Service Connect** (GCP) / **Private Link** (Azure) — o hostname do endpoint privado do provedor de Cloud. Listado somente quando um [endpoint privado](#privatelink-or-private-service-connect) está habilitado.

Selecionar um caminho atualiza o hostname em cada exemplo de conexão na caixa de diálogo — o comando HTTPS (`curl`), o native client, JDBC e os snippets de client para linguagem (Python, Node.js, Java, Go e C#) — para que você possa copiar um comando pronto para uso para o caminho exato de que precisa, sem editar o hostname manualmente.

O menu suspenso lista apenas os caminhos habilitados para sua infraestrutura, e a lista é atualizada toda vez que a caixa de diálogo é aberta — um balanceador de carga privado ou endpoint PrivateLink recém-habilitado aparece na próxima vez que você abrir **Connect**, sem atraso de propagação. Quando apenas um caminho está disponível, o menu suspenso é exibido desabilitado, com esse endpoint selecionado.

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/tyM7Sy7bE2MbONr4/images/cloud/reference/byoc-connect-via.png?fit=max&auto=format&n=tyM7Sy7bE2MbONr4&q=85&s=1227458693b53ccb065b5299456d5688" size="lg" alt="Caixa de diálogo Connect com o menu suspenso Connection via expandido, mostrando os caminhos de balanceador de carga público, balanceador de carga privado e PrivateLink" background="black" width="1500" height="1060" data-path="images/cloud/reference/byoc-connect-via.png" />

<div id="public-load-balancer">
  ## Balanceador de carga público
</div>

Um balanceador de carga público fornece acesso aos seus serviços ClickHouse pela internet. Esta é a configuração padrão ao usar uma VPC dedicada gerenciada pela ClickHouse.

<div id="public-load-balancer-overview">
  ### Visão geral
</div>

* **Acesso**: Acessível pela internet pública
* **Caso de uso**: Adequado para aplicações e usuários que precisam se conectar a partir de diferentes locais ou redes
* **Segurança**: Protegido por criptografia TLS e filtragem por IP (recomendado)

<div id="connecting-via-public-load-balancer">
  ### Conexão via balanceador de carga público
</div>

Para se conectar ao seu serviço do ClickHouse usando o endpoint público:

1. **Obtenha o endpoint do seu serviço** no console do ClickHouse Cloud. O endpoint é exibido na seção "Connect" do seu serviço.

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/tyM7Sy7bE2MbONr4/images/cloud/reference/byoc-connect-1.webp?fit=max&auto=format&n=tyM7Sy7bE2MbONr4&q=85&s=9665ffe4f2e57490686af8bd5f5c68e9" size="lg" alt="conexão BYOC" background="black" width="2466" height="1742" data-path="images/cloud/reference/byoc-connect-1.webp" />

Por exemplo:

```text theme={null}
sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com
```

O segmento `aws` indica seu provedor de Cloud — para implantações nessas Clouds, ele será `gcp` ou `azure`.

<div id="public-ip-filtering">
  ### Filtragem por IP
</div>

A filtragem por IP (IP Access List) é **altamente recomendada** ao usar um balanceador de carga público para restringir o acesso a endereços IP ou intervalos CIDR autorizados.

Para informações detalhadas sobre a filtragem por IP, consulte a [documentação da IP Access List](/pt-BR/products/cloud/guides/security/connectivity/setting-ip-filters).

<div id="private-load-balancer">
  ## Balanceador de carga privado
</div>

Um balanceador de carga privado fornece acesso interno aos seus serviços ClickHouse, acessível apenas a partir das redes conectadas a ele (por exemplo, VPCs/VNets com peering). Essa é a configuração padrão ao usar uma VPC gerenciada pelo cliente.

<div id="private-load-balancer-overview">
  ### Visão geral
</div>

* **Acesso**: Acessível somente de dentro da sua infraestrutura de rede privada
* **Caso de uso**: Ideal para aplicações executadas no mesmo ambiente de nuvem ou conectadas por peering de VPC/VNet
* **Segurança**: O tráfego permanece dentro da sua rede privada, sem exposição à internet pública

<div id="connecting-via-private-load-balancer">
  ### Conectando via balanceador de carga privado
</div>

Para se conectar usando o endpoint privado:

1. **Habilite o balanceador de carga privado** (caso ainda não esteja habilitado) para sua infraestrutura BYOC no console do ClickHouse Cloud. Consulte [Balanceadores de carga](/pt-BR/products/bring-your-own-cloud/configuration/configurations#load-balancers) para obter detalhes.
2. **Garanta a conectividade de rede**:
   * Para VPC/VNet peering: conclua a configuração de peering (consulte [Configuração de rede privada](/pt-BR/products/bring-your-own-cloud/onboarding/network))
   * Para outras redes privadas: garanta que o roteamento esteja configurado para alcançar a VPC/VNet do BYOC
3. **Obtenha seu endpoint privado**:
   O endpoint privado está disponível no console do ClickHouse Cloud, na seção "Connect" do seu serviço. O endpoint privado segue o mesmo formato do endpoint público, mas com o sufixo `-private` adicionado à parte do ID do serviço. Por exemplo:

   * **Endpoint público**: `sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`
   * **Endpoint privado**: `sb9jmrq2ne-private.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`

   Em vez de montar manualmente o hostname com `-private`, selecione **Private load balancer** na lista suspensa **Connection via** na caixa de diálogo **Connect** para copiar diretamente o endpoint e os comandos de conexão prontos.

<div id="public-ip-filtering">
  ### Filtragem por IP
</div>

Embora os balanceadores de carga privados restrinjam o acesso apenas a redes internas, ainda é possível configurar a filtragem por IP para ter um controle ainda mais granular sobre quais origens dentro da sua rede privada podem se conectar. A filtragem por IP para balanceadores de carga privados usa o mesmo mecanismo de configuração dos balanceadores de carga públicos: defina os endereços IP ou intervalos CIDR permitidos, e o ClickHouse Cloud aplicará essas regras adequadamente a cada tipo de endpoint. A plataforma distingue automaticamente entre intervalos CIDR públicos e privados e os atribui aos endpoints de balanceador de carga correspondentes. Consulte a [documentação da IP Access List](/pt-BR/products/cloud/guides/security/connectivity/setting-ip-filters).

<div id="security-group-configuration">
  ### Configuração do Security Group
</div>

Para implantações na AWS, o security group do balanceador de carga privado controla quais redes podem acessar o endpoint. Por padrão, somente o tráfego originado dentro da VPC do BYOC é permitido.

Para mais detalhes, consulte a [configuração do Security Group do balanceador de carga privado](/pt-BR/products/bring-your-own-cloud/configuration/configurations#private-load-balancer-security-group).

<div id="privatelink-or-private-service-connect">
  ## PrivateLink, Private Service Connect ou Private Link
</div>

O AWS PrivateLink, o GCP Private Service Connect e o Azure Private Link oferecem a opção de conectividade mais segura, permitindo acessar serviços do ClickHouse de forma privada, sem VPC/VNet peering nem gateways de internet.

<div id="public-load-balancer-overview">
  ### Visão geral
</div>

* **Acesso**: Conectividade privada por meio do serviço gerenciado do provedor de Cloud
* **Isolamento de rede**: O tráfego nunca passa pela internet pública
* **Caso de uso**: Implantações Enterprise que exigem segurança máxima e isolamento de rede
* **Benefícios**:
  * Não requer VPC peering
  * Arquitetura de rede simplificada
  * Postura de segurança e conformidade aprimorada

<div id="connecting-via-privatelink">
  ### Conexão por um endpoint privado
</div>

Conclua a configuração do PrivateLink, Private Service Connect ou Private Link (consulte [Configuração de rede privada](/pt-BR/products/bring-your-own-cloud/onboarding/network)). Depois disso, você poderá se conectar ao seu serviço ClickHouse usando um hostname dedicado para o endpoint privado. O comportamento do DNS varia conforme o provedor: na AWS, habilitar **Nomes DNS privados** no endpoint faz com que a resolução de DNS na sua VPC direcione automaticamente o tráfego por ele. No GCP, o Private Service Connect exige que você crie um registro DNS curinga — consulte o [guia de configuração do GCP](/pt-BR/products/bring-your-own-cloud/onboarding/network-gcp) — e o Azure Private Link também exige uma zona DNS privada com um registro curinga vinculado à sua VNet — consulte o [guia de configuração do Azure](/pt-BR/products/bring-your-own-cloud/onboarding/network-azure).

O hostname do endpoint privado é semelhante ao do endpoint público, mas inclui um rótulo específico da nuvem entre o subdomínio do serviço e o subdomínio da infraestrutura BYOC — `vpce` na AWS, `p` no GCP e `privatelink` no Azure. Por exemplo:

* **Endpoint público (AWS)**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **Endpoint PrivateLink (AWS)**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **Endpoint Private Service Connect (GCP)**: `h5ju65kv87.p.mhp0y4dmph.us-central1.gcp.clickhouse-byoc.com`
* **Endpoint Private Link (Azure)**: `h5ju65kv87.privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com`

Depois que o endpoint estiver configurado e incluído na allowlist, selecione **PrivateLink** (**Private Service Connect** no GCP, **Private Link** no Azure) no menu suspenso **Connection via** da caixa de diálogo **Connect** para copiar diretamente os detalhes de conexão do endpoint privado.

<div id="endpoint-id-allowlist">
  ### Lista de permissões de Endpoint ID
</div>

Para usar o PrivateLink, o Private Service Connect ou o Private Link, o Endpoint ID da conexão do cliente precisa estar explicitamente autorizado para cada serviço do ClickHouse. Você pode gerenciar essa lista de permissões no console do ClickHouse Cloud: abra a página Settings do serviço, clique em **Set up private endpoint** e insira o identificador do endpoint do seu provedor de Cloud:

* **AWS**: o VPC Endpoint ID (consulte o [guia de configuração da AWS](/pt-BR/products/bring-your-own-cloud/onboarding/network-aws#setup-privatelink))
* **GCP**: o PSC Connection ID (consulte o [guia de configuração do GCP](/pt-BR/products/bring-your-own-cloud/onboarding/network-gcp#setup-psc))
* **Azure**: o Private Endpoint Resource ID (consulte o [guia de configuração do Azure](/pt-BR/products/bring-your-own-cloud/onboarding/network-azure#setup-privatelink))

<div id="choosing-connection-method">
  ## Escolhendo o método de conexão adequado
</div>

| Método de conexão                                    | Nível de segurança          | Requisitos de rede                        | Caso de uso                                            |
| ---------------------------------------------------- | --------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| **Balanceador de carga público**                     | Médio (com filtragem de IP) | Acesso à internet                         | Aplicações/usuários em vários locais                   |
| **balanceador de carga privado**                     | Alto                        | VPC peering ou rede privada               | Aplicações no mesmo ambiente de Cloud                  |
| **PrivateLink/Private Service Connect/Private Link** | Máximo                      | Serviço gerenciado pelo provedor de Cloud | Implantações corporativas que exigem isolamento máximo |

<div id="troubleshooting">
  ## Solução de problemas de conexão
</div>

Se você estiver enfrentando problemas de conexão:

1. **Verifique se o endpoint está acessível**: Certifique-se de que está usando o endpoint correto (público ou privado)
2. **Verifique os filtros de IP**: Para balanceadores de carga públicos, confirme se o seu endereço IP está na lista de permissões
3. **Verifique a conectividade de rede**: Para conexões privadas, certifique-se de que o VPC/VNet peering ou o endpoint privado esteja configurado corretamente
4. **Verifique os Security Groups**: Para balanceadores de carga privados, confirme se as regras do security group permitem tráfego da sua rede de origem
5. **Verifique a lista de permissões do endpoint**: Para PrivateLink, Private Service Connect ou Private Link, confirme se o Endpoint ID foi adicionado à lista de permissões do serviço ClickHouse
6. **Revise a autenticação**: Certifique-se de que está usando as credenciais corretas (username e password)
7. **Entre em contato com o suporte**: Se os problemas persistirem, entre em contato com o suporte do ClickHouse