How to Enable Encryption in ClickHouse

Galaxy Glossary

How do I enable encryption in ClickHouse?

Secures ClickHouse data in transit and at rest by configuring TLS and encrypted disks.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Description

Example H2

Example H3

Why enable encryption in ClickHouse?

Encryption defends sensitive analytics data against network sniffing and disk theft. By configuring TLS you protect client-server traffic. By storing tables on encrypted disks you safeguard data at rest, including backups.

How to enable TLS for client connections?

Step 1 — Generate certificates

Use OpenSSL or your PKI to create a server key, certificate, and CA bundle. Place the files under /etc/clickhouse-server/certs/ with strict 600 permissions.

Step 2 — Update server configuration

Add a <tcp_port_secure>9000</tcp_port_secure> section inside config.xml and reference the certificate paths. Disable plaintext port if compliance demands.

Step 3 — Connect with TLS from clients

Set protocol=tcp_secure or use clickhouse-client --secure --host db.example.com --port 9000.Libraries usually expose use_ssl=true parameters.

How to encrypt data at rest?

Create an encrypted disk

Add a disk entry of type encrypted inside storage_configuration, supply the path to the master key file, and specify the underlying volume.

Create a storage policy

Define a policy that points hot data to the encrypted disk, e.g. EncryptedPolicy.

Create tables using encrypted policy

Reference the policy in CREATE TABLE. All parts, mutations, and merges stay encrypted transparently.

When should I use encryption?

Enable TLS whenever clients connect over public or shared networks. Use encrypted disks when storing personal data such as customer emails or when regulatory frameworks (GDPR, HIPAA) apply.

Best practices for encrypted ClickHouse deployments

Rotate certificates yearly, monitor expiry, keep master keys in a dedicated KMS, disable insecure cipher suites, and test backup restores regularly.

Why How to Enable Encryption in ClickHouse is important

How to Enable Encryption in ClickHouse Example Usage


clickhouse-client --secure --query "
SELECT o.id, c.email, o.total_amount
FROM Orders o
JOIN Customers c ON c.id = o.customer_id
WHERE o.order_date >= today() - 7
ORDER BY o.total_amount DESC
LIMIT 10;"

How to Enable Encryption in ClickHouse Syntax


# Server config for TLS
<tcp_port_secure>9000</tcp_port_secure>
<tls>
    <certificateFile>/etc/clickhouse-server/certs/server.crt</certificateFile>
    <privateKeyFile>/etc/clickhouse-server/certs/server.key</privateKeyFile>
    <caConfig>/etc/clickhouse-server/certs/ca.crt</caConfig>
</tls>

# Storage policy with encrypted disk
<storage_configuration>
    <disks>
        <local_encrypted>
            <type>encrypted</type>
            <path>/var/lib/clickhouse/encrypted/</path>
            <disk>default</disk>
            <key>aes:/etc/clickhouse-server/keys/master.key</key>
        </local_encrypted>
    </disks>
    <policies>
        <EncryptedPolicy>
            <volumes>
                <main>
                    <disk>local_encrypted</disk>
                </main>
            </volumes>
        </EncryptedPolicy>
    </policies>
</storage_configuration>

-- Create table on encrypted disk
CREATE TABLE Customers
(
    id UInt32,
    name String,
    email String,
    created_at DateTime
)
ENGINE = MergeTree()
ORDER BY id
SETTINGS storage_policy = 'EncryptedPolicy';

Common Mistakes

Restart skipped after editing config.xml. ClickHouse only reads TLS and disk settings at startup, so changes remain inactive until a full service restart.
Storing the master key inside the encrypted disk. If the disk fails to mount you lose the key. Keep keys on a separate, access-controlled path or external KMS.