> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/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 endpoints públicos, privados ou do PrivateLink

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 do PrivateLink/Private Service Connect, 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) — o hostname do endpoint privado do provedor de Cloud. Listado somente quando [PrivateLink ou Private Service Connect](#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, MySQL 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/nS3fqaRk31wnsutS/images/cloud/reference/byoc-connect-via.png?fit=max&auto=format&n=nS3fqaRk31wnsutS&q=85&s=4028c9ccc734cae0794b4a62a7fddf4f" 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 ClickHouse Cloud console. O endpoint é exibido na seção "Connect" do seu serviço.

<Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/reference/byoc-connect-1.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=869486bfed0c8ee1b9028e7a08948d91" 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
```

<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](/docs/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 com peering). Essa é a configuração padrão ao usar uma VPC gerenciada pelo cliente.

<div id="public-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 VPC peering
* **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). Entre em contato com o suporte do ClickHouse se precisar [habilitar um balanceador de carga privado](/docs/pt-BR/products/bring-your-own-cloud/configuration/configurations#load-balancers) para sua implantação.
2. **Garanta a conectividade de rede**:
   * Para VPC peering: conclua a configuração de VPC peering (consulte [Configuração de rede privada](/docs/pt-BR/products/bring-your-own-cloud/onboarding/network))
   * Para outras redes privadas: garanta que o roteamento esteja configurado para alcançar a VPC 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](/docs/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](/docs/pt-BR/products/bring-your-own-cloud/configuration/configurations#private-load-balancer-security-group).

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

O AWS PrivateLink e o GCP Private Service Connect oferecem a opção de conectividade mais segura, permitindo acessar serviços do ClickHouse de forma privada, sem VPC 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 via PrivateLink/Private Service Connect
</div>

Conclua a configuração do PrivateLink ou do Private Service Connect (consulte [Configuração de rede privada](/docs/pt-BR/products/bring-your-own-cloud/onboarding/network)). Depois de concluir a configuração, você poderá se conectar ao seu serviço ClickHouse usando um formato de endpoint específico do PrivateLink. O endpoint do PrivateLink inclui um subdomínio `vpce` para indicar que o tráfego é roteado por meio do endpoint da VPC. A resolução de DNS na sua VPC roteia automaticamente o tráfego por meio do endpoint do PrivateLink.

O formato do endpoint do PrivateLink é semelhante ao do endpoint público, mas inclui um subdomínio `vpce` entre o subdomínio do serviço e o subdomínio da infraestrutura BYOC. Por exemplo:

* **Endpoint público**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **Endpoint do PrivateLink**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`

Depois que o endpoint estiver configurado e incluído na lista de permissões, selecione **PrivateLink** (ou **Private Service Connect** no GCP) 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 ou o Private Service Connect, o Endpoint ID da conexão do cliente deve ser explicitamente permitido para cada serviço do ClickHouse. Entre em contato com o suporte do ClickHouse e informe seus Endpoint IDs para que eles possam ser adicionados à lista de permissões do serviço.

Para instruções detalhadas de configuração, consulte o [guia de configuração de rede privada](/docs/pt-BR/products/bring-your-own-cloud/onboarding/network).

<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** | 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 peering ou o PrivateLink 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 os Security Groups**: Para PrivateLink ou Private Service Connect, 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