Question​

How can I use API to manage clusters on ClickHouse Cloud?

Answer​

We will use Terraform to configure our infra and ClickHouse Provider

Steps:

1). Create an API Key on Cloud. Follow the docs here - https://clickhouse.com/docs/cloud/manage/openapi

Save the creds locally.

2). Install Terraform using - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli

You can use Homebrew package manager if you're on Mac.

3). Create a directory anywhere you like:

mkdir test
➜  test pwd
/Users/jaijhala/Desktop/terraform/test

4). Create 2 files: main.tf and secret.tfvars

Copy the following:

main.tf file would be:

terraform {
 required_providers {
   clickhouse = {
     source = "ClickHouse/clickhouse"
     version = "0.0.2"
   }
 }
}

variable "organization_id" {
  type = string
}

variable "token_key" {
  type = string
}

variable "token_secret" {
  type = string
}

provider clickhouse {
  environment 	= "production"
  organization_id = var.organization_id
  token_key   	= var.token_key
  token_secret	= var.token_secret
}


variable "service_password" {
  type = string
  sensitive   = true
}

resource "clickhouse_service" "service123" {
  name       	= "jai-terraform"
  cloud_provider = "aws"
  region     	= "us-east-2"
  tier       	= "development"
  idle_scaling   = true
  password  = var.service_password
  ip_access = [
	{
    	source  	= "0.0.0.0/0"
    	description = "Anywhere"
	}
  ]
}

output "CLICKHOUSE_HOST" {
  value = clickhouse_service.service123.endpoints.0.host
}

You can replace your own parameters like service name, region etc.. in the resources section above.

secret.tfvars is where you'll put all the API Key related info that you downloaded earlier. The idea behind this file is that all your secret credentials will be hidden from the main config file.

It would be something like (replace these parameters):

organization_id = "e957a5f7-4qe3-4b05-ad5a-d02b2dcd0593"
token_key = "QWhhkMeytqQruTeKg"
token_secret = "4b1dNmjWdLUno9lXxmKvSUcPP62jvn7irkuZPbY"
service_password = "password123!"

5). Run terraform init from this directory

Expected output:

Initializing the backend...

Initializing provider plugins...
- Finding clickhouse/clickhouse versions matching "0.0.2"...
- Installing clickhouse/clickhouse v0.0.2...
- Installed clickhouse/clickhouse v0.0.2 (self-signed, key ID D7089EE5C6A92ED1)

Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://www.terraform.io/docs/cli/plugins/signing.html

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

6). Run terraform apply -var-file=secret.tfvars command.

Something like:

➜  test terraform apply -var-file=secret.tfvars

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with
the following symbols:
  + create

Terraform will perform the following actions:

  # clickhouse_service.service123 will be created
  + resource "clickhouse_service" "service123" {
      + cloud_provider = "aws"
      + endpoints      = (known after apply)
      + id             = (known after apply)
      + idle_scaling   = true
      + ip_access      = [
          + {
              + description = "Anywhere"
              + source      = "0.0.0.0/0"
            },
        ]
      + last_updated   = (known after apply)
      + name           = "jai-terraform"
      + password       = (sensitive value)
      + region         = "us-east-2"
      + tier           = "development"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + CLICKHOUSE_HOST = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Type yes and hit enter

Side note: Notice it says password = (sensitive value) above. This is because we set sensitive = true for the password in the main.tf file.

7). It will take a couple of mins to create the service but eventually it should come up like:

  Enter a value: yes

clickhouse_service.service123: Creating...
clickhouse_service.service123: Still creating... [10s elapsed]
clickhouse_service.service123: Still creating... [20s elapsed]
clickhouse_service.service123: Still creating... [30s elapsed]
clickhouse_service.service123: Still creating... [40s elapsed]
clickhouse_service.service123: Still creating... [50s elapsed]
clickhouse_service.service123: Still creating... [1m0s elapsed]
clickhouse_service.service123: Still creating... [1m10s elapsed]
clickhouse_service.service123: Still creating... [1m20s elapsed]
clickhouse_service.service123: Still creating... [1m30s elapsed]
clickhouse_service.service123: Still creating... [1m40s elapsed]
clickhouse_service.service123: Creation complete after 1m41s [id=aa8d8d63-1878-4600-8470-630715af38ed]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

CLICKHOUSE_HOST = "h3ljlaqez6.us-east-2.aws.clickhouse.cloud"
➜  test

8). Check Cloud Console, you should be able to see the service created.

9). To clean up/destroy the service again, run terraform destroy -var-file=secret.tfvars

Something like:

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with
the following symbols:
  - destroy

Terraform will perform the following actions:

  # clickhouse_service.service123 will be destroyed
  - resource "clickhouse_service" "service123" {
      - cloud_provider = "aws" -> null
      - ............

Plan: 0 to add, 0 to change, 1 to destroy.

Changes to Outputs:
  - CLICKHOUSE_HOST = "h3ljlaqez6.us-east-2.aws.clickhouse.cloud" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value:

Type yes and hit enter

10).

clickhouse_service.service123: Destroying... [id=aa8d8d63-1878-4600-8470-630715af38ed]
clickhouse_service.service123: Still destroying... [id=aa8d8d63-1878-4600-8470-630715af38ed, 10s elapsed]
clickhouse_service.service123: Still destroying... [id=aa8d8d63-1878-4600-8470-630715af38ed, 20s elapsed]
clickhouse_service.service123: Destruction complete after 27s

Destroy complete! Resources: 1 destroyed.

And it should be gone from the Cloud Console.

More details about the Cloud API can be found here - https://clickhouse.com/docs/cloud/manage/api/api-overview

Overview​

Starting February 27, 2026, ClickHouse Cloud will begin collecting core dumps when server crashes occur. This is part of our commitment to improving service reliability for all our users.

Core dump collection helps us:

• Identify and understand what caused a crash
• Fix issues more quickly
• Continuously improve your service experience

What's collected​

When a crash occurs, core dumps capture a snapshot of the server's state at that moment. We want to be transparent that this may include sensitive information that was in memory, such as:

• Connection credentials
• Encryption keys
• Query strings
• Other data in memory at the time of the crash

How we protect your data​

We take the security of this data seriously:

• Regional Storage: All data stays in the same region as your service
• Enhanced Security: We apply additional protections to all collected data
• Limited Retention: Data is kept only as long as needed for debugging, then securely deleted

Services automatically excluded​

Some services are automatically excluded from core dump collection:

• Services with HIPAA compliance requirements
• Services with PCI compliance requirements
• BYOC (Bring Your Own Cloud) services

How to opt out​

If you'd prefer not to participate in core dump collection, you can easily opt out:

1. Go to the ClickHouse Cloud Console
2. Select your service
3. Click on the Settings tab
4. Scroll to find "Share crash reports with ClickHouse"
5. Toggle the option off to opt out

ClickHouse uses two independent concepts for organizing data within parts:

• Part types (Wide vs Compact): How column data is stored within a part
• Storage formats (Full vs Packed): How the part's files are stored on disk

Part types: Wide vs Compact​

Part types determine how column data is organized within a data part.

When each type is used​

The part type is controlled by the following table settings:

• min_bytes_for_wide_part: Minimum bytes for a part to use Wide format
• min_rows_for_wide_part: Minimum rows for a part to use Wide format

If either the number of bytes or rows in a data part is less than the corresponding setting value, the part is stored in Compact format; otherwise, it uses Wide format.

Performance considerations​

Compact parts:

• Better ingestion performance
• Optimal when queries need all columns
• More efficient for small parts

Wide parts:

• More efficient for queries selecting only a subset of columns
• Better for large datasets with selective column access

Compact-to-wide merges are slower than wide-to-wide merges because ClickHouse uses vertical merge algorithms for compact-to-wide conversions, while using horizontal algorithms for compact-to-compact merges. If you want to force the use of wide parts regardless of size, you can set min_bytes_for_wide_part=0.

This can be useful in the following scenarios:

1. When you have tables with many columns (e.g. over 600 columns) and are making large inserts, setting this to 0 can help with performance
2. For optimizing memory usage of system tables like system.metric_log and system.text_log that are consuming excessive memory during merges
3. When dealing with tables that have high insert volumes and you want to optimize storage and merge behavior
4. When you want consistent part format behavior and don't want the overhead of format transitions based on size thresholds

It's worth noting that while setting this to 0 can improve certain performance characteristics, it may generate more GET requests to S3 storage due to the wide parts format.

Limitations​

Column size statistics are not calculated for compact parts, which can affect monitoring and optimization efforts. When querying system.parts_columns, compact parts show 0 for column_data_compressed_bytes and column_data_uncompressed_bytes. For more information see "Find counts and sizes of wide or compact parts".

Storage formats: Full vs Packed (ClickHouse Cloud)​

Storage formats determine how a part's files are physically stored on disk.

Full storage​

In Full storage, each part consists of multiple separate files stored individually on disk. This is the default and only option in open source ClickHouse.

Packed storage (ClickHouse Cloud only)​

In Packed storage, all part files are bundled into a single archive. This significantly reduces the number of file operations, which is critical for remote storage like S3 where each request has associated latency and cost.

Benefits of Packed storage:

• Fewer S3/object storage API calls
• Reduced metadata pressure on the coordination service
• Lower storage costs (full storage can be significantly more expensive)
• Better performance for small parts on remote storage

When Packed storage is used​

In ClickHouse Cloud, a part uses Packed storage if any of these conditions are true:

• Uncompressed bytes < min_bytes_for_full_part_storage
• Row count < min_rows_for_full_part_storage
• Merge level < min_level_for_full_part_storage

The min_level_for_full_part_storage setting can be used to optimize both performance and costs in ClickHouse Cloud environments, particularly for tables that receive continuous inserts. The setting is available starting in ClickHouse version 25.10 and works in conjunction with min_level_for_wide_part to provide comprehensive control over part storage strategies.

Changing it from the default value (0) could be considered in the following use cases:

• When tables receive regular data ingestion, initial parts will be merged away quickly, making it wasteful to store them in full part format initially
• Setting this parameter prevents expensive S3 PUT requests during inserts. For example, one analysis showed that inserts creating full parts averaged 31.3 PUT requests per insert, while those creating only packed parts averaged just 2.22 PUT requests per insert
• Insert operations become faster, especially for tables with many columns, since packed storage writes all data into one file rather than creating separate files for each column.

Recommended configuration:

Set min_level_for_full_part_storage = 2 for cloud deployments. This ensures that:

• Level 0 parts (initial inserts) use packed storage
• Level 1 parts continue using packed storage
• Only parts at level 2 and above use full storage format

Combining part types and storage formats​

These two concepts are orthogonal and you can have any combination, depending on if you are using ClickHouse Cloud or Open Source ClickHouse:

Querying part information​

You can inspect the part type and part storage type of existing parts using the system.parts table:

SELECT
    part_type,
    part_storage_type,
    max(level),
    count(),
    formatReadableSize(max(data_uncompressed_bytes)),
    formatReadableSize(min(data_uncompressed_bytes))
FROM system.parts
WHERE (database != 'system') AND active
GROUP BY
    1,
    2
ORDER BY
    1 ASC,
    2 ASC

You will see something like this:

   ┌─part_type─┬─part_storage_type─┬─max(level)─┬─count()─┬─formatReadab⋯sed_bytes))─┬─formatReadab⋯sed_bytes))─┐
1. │ Compact   │ Full              │      12688 │    2456 │ 1023.87 MiB              │ 23.78 MiB                │
2. │ Compact   │ Packed            │      97383 │   13748 │ 127.77 MiB               │ 1.00 B                   │
3. │ Wide      │ Full              │       7642 │    2000 │ 1.38 TiB                 │ 30.18 MiB                │
4. │ Wide      │ Packed            │         10 │     187 │ 110.01 MiB               │ 1.30 KiB                 │
   └───────────┴───────────────────┴────────────┴─────────┴──────────────────────────┴──────────────────────────┘

The following query can be used to count the number of parts by type:

SELECT
    table,
    part_type,
    count(*)
FROM system.parts
WHERE active
GROUP BY
    table,
    part_type
ORDER BY
    table ASC,
    part_type ASC

An example response is shown below:

┌─table───────────────────┬─part_type─┬─count()─┐
│ asynchronous_metric_log │ Compact   │       6 │
│ metric_log              │ Compact   │       1 │
│ otel_logs               │ Compact   │       5 │
│ otel_logs               │ Wide      │       2 │
│ part_log                │ Compact   │       2 │
│ query_log               │ Compact   │       5 │
│ session_log             │ Compact   │       2 │
│ text_log                │ Compact   │       7 │
│ trace_log               │ Compact   │       6 │
└─────────────────────────┴───────────┴─────────┘

Run the query below to query part size for wide and compact parts:

SELECT
    table,
    column,
    part_type,
    sum(rows),
    sum(column_data_compressed_bytes),
    sum(column_data_uncompressed_bytes)
FROM system.parts_columns
WHERE active
GROUP BY
    table,
    column,
    part_type
ORDER BY
    table ASC,
    column ASC,
    part_type ASC

An example response is shown below:

┌─table─────┬─column─────────────┬─part_type─┬─sum(rows)─┬─sum(column_data_compressed_bytes)─┬─sum(column_data_uncompressed_bytes)─┐
│ otel_logs │ Body               │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ Body               │ Wide      │  18900157 │                         316784170 │                          2807508947 │
│ otel_logs │ LogAttributes      │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ LogAttributes      │ Wide      │  18900157 │                         215812392 │                          3173566494 │
│ otel_logs │ ResourceAttributes │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ ResourceAttributes │ Wide      │  18900157 │                          94428129 │                          2258154988 │
│ otel_logs │ ServiceName        │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ ServiceName        │ Wide      │  18900157 │                             24726 │                            18973727 │
│ otel_logs │ SeverityNumber     │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ SeverityNumber     │ Wide      │  18900157 │                             51973 │                            75600628 │
│ otel_logs │ SeverityText       │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ SeverityText       │ Wide      │  18900157 │                             24726 │                            18973727 │
│ otel_logs │ SpanId             │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ SpanId             │ Wide      │  18900157 │                             13048 │                            18900157 │
│ otel_logs │ Timestamp          │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ Timestamp          │ Wide      │  18900157 │                          61225801 │                           151201256 │
│ otel_logs │ TraceFlags         │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ TraceFlags         │ Wide      │  18900157 │                             51973 │                            75600628 │
│ otel_logs │ TraceId            │ Compact   │   1564357 │                                 0 │                                   0 │
│ otel_logs │ TraceId            │ Wide      │  18900157 │                             13048 │                            18900157 │
└───────────┴────────────────────┴───────────┴───────────┴───────────────────────────────────┴─────────────────────────────────────┘

Prerequisites:

• Familiarity with ClickHouse config files
• A running instance of ClickHouse server
• (Optional) A running local Grafana instance

<!--
    OpenTelemetry log contains OpenTelemetry trace spans.

    NOTE: this table does not use standard schema with event_date and event_time!
-->
<opentelemetry_span_log>
    <!--
        The default table creation code is insufficient, this <engine> spec
        is a workaround. There is no 'event_time' for this log, but two times,
        start and finish. It is sorted by finish time, to avoid inserting
        data too far away in the past (probably we can sometimes insert a span
        that is seconds earlier than the last span in the table, due to a race
        between several spans inserted in parallel). This gives the spans a
        global order that we can use to e.g. retry insertion into some external
        system.
    -->
    <engine>
        engine MergeTree
        partition by toYYYYMM(finish_date)
        order by (finish_date, finish_time_us, trace_id)
    </engine>
    <database>system</database>
    <table>opentelemetry_span_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</opentelemetry_span_log>

Processing configuration file 'config.xml'.
There is no file 'config.xml', will use embedded config.

SET opentelemetry_trace_processors=1;

SHOW TABLES IN system

SET opentelemetry_start_trace_probability=1;

SELECT pow(number, 2) FROM numbers(10E4);

:) SELECT pow(number, 2) FROM numbers(10E4);

SELECT pow(number, 2)
FROM numbers(100000.)

--highlight-next-line
Query id: a9241258-a0c4-4776-a00b-e6a1d9bec4a1

WITH 'a9241258-a0c4-4776-a00b-e6a1d9bec4a1' AS my_query_id
SELECT
    concat(substring(hostName(), length(hostName()), 1), leftPad(greatest(attribute['clickhouse.thread_id'], attribute['thread_number']), 5, '0')) AS group,
    operation_name,
    start_time_us,
    finish_time_us,
    sipHash64(operation_name) AS color,
    attribute
FROM system.opentelemetry_span_log
WHERE (trace_id IN (
    SELECT trace_id
    FROM system.opentelemetry_span_log
    WHERE (attribute['clickhouse.query_id']) = my_query_id
)) AND (operation_name != 'query') AND (operation_name NOT LIKE 'Query%')
ORDER BY
    hostName() ASC,
    group ASC,
    parent_span_id ASC,
    start_time_us ASC
INTO OUTFILE 'trace.json'
FORMAT JSON
SETTINGS output_format_json_named_tuples_as_objects = 1

SELECT
    toString(trace_id) AS traceID,
    toString(span_id) AS spanID,
    if(toString(parent_span_id)='0', '', toString(parent_span_id)) AS parentSpanID,
    'ClickHouse' AS serviceName,
    operation_name AS operationName,
    start_time_us/1000000 AS startTime,
    (finish_time_us - start_time_us)/1000 AS duration,
    arrayMap(key -> map('key', key, 'value', attribute[key]), mapKeys(attribute)) AS serviceTags
FROM system.opentelemetry_span_log
WHERE trace_id = '68a14b27-a61f-596d-3746-2b03d2530e42' ORDER BY startTime ASC

From Google Chrome​

1. Open Developer Tools by pressing F12 or Ctrl + Shift + I (Windows/Linux) / Cmd + Option + I (Mac).
2. Click the "Network" tab.
3. Reload the page and reproduce the issue.
4. From Developer Tools, click the download button.

From Mozilla Firefox​

1. Open Developer Tools by pressing F12 or Ctrl + Shift + E (Windows/Linux) / Cmd + Option + E (Mac).
2. Click the "Network" tab.
3. Reload the page and reproduce the issue.
4. From Developer Tools, right-click in the request list and select "Save All As HAR".

From Microsoft Edge​

1. Open Developer Tools by pressing F12 or Ctrl + Shift + I (Windows/Linux) / Cmd + Option + I (Mac).
2. Click the "Network" tab.
3. Reload the page and reproduce the issue.
4. From Developer Tools, right-click in the network list and choose "Save all as HAR with content".

From Safari​

1. Enable Developer Tools (if not already enabled):
   • Go to Safari > Settings > Advanced.
   • Check "Show Develop menu in menu bar" at the bottom.
2. Click Develop > Show Web Inspector.
3. Click the "Network" tab.
4. Reload the page and reproduce the issue.
5. From Developer Tools, click the "Export" button.

Sending the .HAR file​

1. Rename the file to something short and descriptive (e.g., login-issue.har).
2. Compress the file (optional but recommended).
3. Attach it to your support case or email it to your assigned support contact.

Memory limit exceeded for query​

As a new user, ClickHouse can often seem like magic - every query is super fast, even on the largest datasets and most ambitious queries. Invariably though, real-world usage tests even the limits of ClickHouse. Queries exceeding memory can be the result of a number of causes. Most commonly, we see large joins or aggregations on high cardinality fields. If performance is critical, and these queries are required, we often recommend users simply scale up - something ClickHouse Cloud does automatically and effortlessly to ensure your queries remain responsive. We appreciate, however, that in self-managed scenarios, this is sometimes not trivial, and maybe optimal performance is not even required. Users, in this case, have a few options.

Aggregations​

For memory-intensive aggregations or sorting scenarios, users can use the settings max_bytes_before_external_group_by and max_bytes_before_external_sort respectively. The former of which is discussed extensively here.

In summary, this ensures any aggregations can “spill” out to disk if a memory threshold is exceeded. This will invariably impact query performance but will help ensure queries do not OOM. The latter sorting setting helps address similar issues with memory-intensive sorts. This can be particularly important in distributed environments where a coordinating node receives sorted responses from child shards. In this case, the coordinating server can be asked to sort a dataset larger than its available memory. With max_bytes_before_external_sort, sorting can be allowed to spill over to disk. This setting is also helpful for cases where the user has an ORDER BY after a GROUP BY with a LIMIT, especially in cases where the query is distributed.

Joins​

For joins, users can select different JOIN algorithms, which can assist in lowering the required memory. By default, joins use the hash join, which offers the most completeness with respect to features and often the best performance. This algorithm loads the right-hand table of the JOIN into an in-memory hash table, against which the left-hand table is then evaluated. To minimize memory, users should thus place the smaller table on the right side. This approach still has limitations in memory-bound cases, however. In these cases, partial_merge join can be enabled via the join_algorithm setting. This derivative of the sort-merge algorithm, first sorts the right table into blocks and creates a min-max index for them. It then sorts parts of the left table by the join key and joins them over the right table. The min-max index is used to skip unneeded right table blocks. This is less memory-intensive at the expense of performance. Taking this concept further, the full_sorting_merge algorithm allows a JOIN to be performed when the right-hand side is very large and doesn't fit into memory and lookups are impossible, e.g. a complex subquery. In this case, both the right and left side are sorted on disk if they do not fit in memory, allowing large tables to be joined.

Since 20.3, ClickHouse has supported an auto value for the join_algorithm setting. This instructs ClickHouse to apply an adaptive join approach, where the hash-join algorithm is preferred until memory limits are violated, at which point the partial_merge algorithm is attempted. Finally, concerning joins, we encourage readers to be aware of the behavior of distributed joins and how to minimize their memory consumption. More information can be found here.

OPTIMIZE FINAL is a DDL command that physically and permanently reorganizes and optimizes data on disk. It physically merges data parts in MergeTree tables, performing data deduplication in the process by removing duplicate rows from storage.

FINAL is a query-time modifier that provides deduplicated results without changing the structure of the stored data. It works by performing merge logic at read-time. It is temporary, only affecting the current query result.

Users are often advised to avoid using OPTIMIZE FINAL, as it has a significant performance overhead, however they should not confuse the two. It is often necessary to use FINAL to get back results without duplicates, especially when using table engines like ReplacingMergeTree which may contain duplicate rows which have not been replaced during the eventual, background merge process.

The table below summarises the key differences:

When to use each​

Use OPTIMIZE FINAL when:

• You want to permanently improve query performance
• You can afford the one-time optimization cost
• You're doing periodic table maintenance
• You want to physically clean up duplicate data

Use FINAL when:

• You need deduplicated results immediately
• You can't wait for or don't want permanent optimization
• You only occasionally need deduplicated data
• You're working with frequently changing data

Both are valuable tools, but they serve different purposes in ClickHouse's deduplication strategy.

In this knowledgebase article, we will walk you through how you can set up a custom DNS alias for your ClickHouse Cloud instance through the use of a reverse proxy such as Nginx for ClickHouse native client.

Create a self-signed certificate​

Create a self-signed certificate with the domain name of your choice. In this example we will use a domain name xyz-customdomain.com and create a certificate called MyCertificate.crt. Refer to "Create SSL certificates" for further details.

Add the certificate to /etc/clickhouse-client/config.xml:

<clickhouse>
    <openSSL>
        <client>
            <loadDefaultCAFile>false</loadDefaultCAFile>
            # highlight-next-line
            <caConfig>/etc/ssl/certs/MyCertificate.crt</caConfig>
            <cacheSessions>true</cacheSessions>
            <disableProtocols>sslv2,sslv3</disableProtocols>
            <preferServerCiphers>true</preferServerCiphers>
            <invalidCertificateHandler>
                <name>RejectCertificateHandler</name>
            </invalidCertificateHandler>
        </client>
    </openSSL>
</clickhouse>

Update Nginx configuration​

Add the following in your nginx.conf file:

proxy_ssl_name xyz.us-west-2.aws.clickhouse.cloud;
proxy_ssl_server_name on;

stream {
    upstream stream_backend {
         server xyz.us-west-2.aws.clickhouse.cloud:9440;
    }

    server {
        listen                9440 ssl;
        proxy_pass            stream_backend;

        ssl_certificate       /etc/ssl/certs/MyCertificate.crt;
        ssl_certificate_key   /etc/ssl/certs/MyKey.key;
        ssl_protocols         SSLv3 TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers           HIGH:!aNULL:!MD5;
        ssl_session_cache     shared:SSL:20m;
        ssl_session_timeout   4h;
        ssl_handshake_timeout 30s;
	proxy_ssl on;
	proxy_ssl_trusted_certificate /etc/ssl/certs/isrgrootx1.pem;
	proxy_ssl_session_reuse on;
        proxy_ssl_verify on;
    #highlight-next-line
	proxy_ssl_name xyz.us-west-2.aws.clickhouse.cloud;
    #highlight-next-line
	proxy_ssl_server_name on;
    }
}

Where isrgrootx1.pem is the root certificate for ClickHouse Cloud which you can download here.

Update hosts file​

Add the following to your /etc/hosts file on the Nginx server:

127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost6 localhost6.localdomain6
10.X.Y.Z  xyz-customdomain.com

Where 10.X.Y.Z is the IP address of your specific Nginx box.

Connect to Cloud using alias​

You are now ready to connect using your custom alias:

clickhouse-client --host xyz.customdomain.com --secure --password 'xxxxxxx'
ClickHouse client version 23.12.1.428 (official build).
Connecting to xyz.customdomain.com:9440 as user default.
Connected to ClickHouse server version 23.9.2.

clickhouse-cloud :)