Connect to ClickHouse

This page describes the different ways to connect to your ClickHouse services in BYOC. You can choose from public load balancers, private load balancers, or private endpoints (AWS PrivateLink, GCP Private Service Connect, or Azure Private Link) based on your security and networking requirements.

Selecting a connection path in the console

Connection details for every BYOC service are available in the ClickHouse Cloud console: open the service and click Connect.

For BYOC services, the Connect dialog includes a Connection via dropdown. Use it to choose how you reach the service:

• Public load balancer — the internet-facing endpoint.
• Private load balancer — the internal endpoint, reached over VPC peering or connected networks. Listed only when a private load balancer is enabled for your infrastructure.
• PrivateLink (AWS) / Private Service Connect (GCP) / Private Link (Azure) — the cloud provider's private-endpoint hostname. Listed only when a private endpoint is enabled.

Selecting a path updates the hostname in every connection example in the dialog — the HTTPS (curl) command, the native client, JDBC, MySQL, and the language-client snippets (Python, Node.js, Java, Go, and C#) — so you can copy a ready-to-use command for the exact path you need without editing the hostname by hand.

The dropdown lists only the paths enabled for your infrastructure, and the list is refreshed each time the dialog opens — a newly enabled private load balancer or PrivateLink endpoint appears the next time you open Connect, with no propagation delay. When only one path is available, the dropdown is shown disabled with that endpoint selected.

Public Load Balancer

A public load balancer provides internet-facing access to your ClickHouse services. This is the default configuration when using a ClickHouse-managed dedicated VPC.

Overview

• Access: Accessible from the public internet
• Use case: Suitable for applications and users that need to connect from various locations or networks
• Security: Protected by TLS encryption and IP filtering (recommended)

Connecting via Public Load Balancer

To connect to your ClickHouse service using the public endpoint:

1. Obtain your service endpoint from the ClickHouse Cloud console. The endpoint is displayed in the "Connect" session of your service.

For example:

sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com

The aws segment reflects your cloud provider — it is gcp or azure for deployments on those clouds.

IP Filtering

IP filtering (IP Access List) is strongly recommended when using a public load balancer to restrict access to authorized IP addresses or CIDR ranges.

For detailed information about IP filtering, see the IP Access List documentation.

Private Load Balancer

A private load balancer provides internal access to your ClickHouse services, accessible only from within your connected networks (e.g., peered VPCs/VNets). This is the default configuration when using a customer-managed VPC.

Overview

• Access: Accessible only from within your private network infrastructure
• Use case: Ideal for applications running in the same cloud environment or connected via VPC/VNet peering
• Security: Traffic stays within your private network, no public internet exposure

Connecting via Private Load Balancer

To connect using the private endpoint:

1. Enable private load balancer (if not already enabled). Contact ClickHouse Support if you need to enable a private load balancer for your deployment.

2. Ensure network connectivity:

   • For VPC/VNet peering: Complete the peering setup (see Private Networking Setup)
   • For other private networks: Ensure routing is configured to reach the BYOC VPC/VNet

3. Obtain your private endpoint: The private endpoint is available in the ClickHouse Cloud console in the "Connect" section of your service. The private endpoint follows the same format as the public endpoint, but with a -private suffix added to the service ID portion. For example:

   • Public endpoint: sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com
   • Private endpoint: sb9jmrq2ne-private.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com

   Rather than deriving the -private hostname by hand, select Private load balancer from the Connection via dropdown in the Connect dialog to copy the endpoint and ready-made connection commands directly.

IP Filtering

Although private load balancers restrict access to internal networks only, you may still set up IP filtering for even finer-grained control over which sources within your private network can connect. IP filtering for private load balancers uses the same configuration mechanism as with public load balancers: define your allowed IP addresses or CIDR ranges, and ClickHouse Cloud will apply these rules appropriately to each endpoint type. The platform automatically distinguishes between public and private CIDR ranges and assigns them to the corresponding load balancer endpoints. See the IP Access List documentation.

Security Group Configuration

For AWS deployments, the private load balancer's security group controls which networks can access the endpoint. By default, only traffic from within the BYOC VPC is allowed.

For more details, see Private Load Balancer Security Group configuration.

PrivateLink, Private Service Connect, or Private Link

AWS PrivateLink, GCP Private Service Connect, and Azure Private Link provide the most secure connectivity option, allowing you to access ClickHouse services privately without VPC/VNet peering or internet gateways.

Overview

• Access: Private connectivity via cloud provider's managed service
• Network isolation: Traffic never traverses the public internet
• Use case: Enterprise deployments requiring maximum security and network isolation
• Benefits:
  • No VPC peering required
  • Simplified network architecture
  • Enhanced security and compliance posture

Connecting via a private endpoint

Complete the PrivateLink, Private Service Connect, or Private Link setup (see Private Networking Setup). Once configured, you can connect to your ClickHouse service using a dedicated private-endpoint hostname. DNS resolution in your VPC/VNet automatically routes traffic through the private endpoint.

The private-endpoint hostname is similar to the public endpoint, but adds a cloud-specific label between the service subdomain and the BYOC infrastructure subdomain — vpce on AWS, p on GCP, and privatelink on Azure. For example:

• Public endpoint (AWS): h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com
• PrivateLink endpoint (AWS): h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com
• Private Service Connect endpoint (GCP): h5ju65kv87.p.mhp0y4dmph.us-central1.gcp.clickhouse-byoc.com
• Private Link endpoint (Azure): h5ju65kv87.privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com

Once the endpoint is set up and allowlisted, select PrivateLink (Private Service Connect on GCP, Private Link on Azure) from the Connection via dropdown in the Connect dialog to copy the private-endpoint connection details directly.

Endpoint ID Allowlist

In order to use PrivateLink, Private Service Connect, or Private Link, the Endpoint ID of your client connection must be explicitly allowed for each ClickHouse service. Please contact ClickHouse Support and provide your Endpoint IDs so they can be added to the service allowlist.

For detailed setup instructions, see the Private Networking Setup guide.

Choosing the Right Connection Method

Connection Method	Security Level	Network Requirements	Use Case
Public Load Balancer	Medium (with IP filtering)	Internet access	Applications/users from various locations
Private Load Balancer	High	VPC peering or private network	Applications in same cloud environment
PrivateLink/Private Service Connect/Private Link	Highest	Cloud provider managed service	Enterprise deployments requiring maximum isolation

Troubleshooting Connection Issues

If you're experiencing connection issues:

1. Verify endpoint accessibility: Ensure you're using the correct endpoint (public vs. private)
2. Check IP filters: For public load balancers, verify your IP address is in the allow list
3. Verify network connectivity: For private connections, ensure VPC/VNet peering or the private endpoint is properly configured
4. Check security groups: For private load balancers, verify security group rules allow traffic from your source network
5. Check security groups: For PrivateLink, Private Service Connect, or Private Link, verify the endpoint ID has been added to the allowlist of the ClickHouse service
6. Review authentication: Ensure you're using correct credentials (username and password)
7. Contact Support: If issues persist, contact ClickHouse Support