ClickHouse

ClickHouse is an open-source column-oriented database for real-time analytics. It answers aggregations over billions of rows in seconds.

Overview

Each instance is a ClickHouse server managed by the Altinity Operator for ClickHouse, scheduled on storage-optimised nodes. You reach it two ways, both through TLS: the HTTPS interface, which almost every client library uses, and the native protocol, which clickhouse-client and native drivers use. The instance starts with a user called app.

ClickHouse at a glance, from the engine catalogue

Status	Available
Category	Analytics
Versions	26.8, 26.3, 25.3 (newest is the default)
Protocol and port	HTTPS on 8443; also native on 9440
Runtime	Operator-backed (Altinity Operator for ClickHouse)
Backups	clickhouse-backup
Point-in-time recovery	No
Pause	Not supported
Free plan	No, paid plans only
Features	Read replicas, High availability (standby)
Licence	Apache-2.0

When to use it

• Product and event analytics, log and trace analytics, and real-time dashboards.
• Large aggregations, funnels and time-bucketed reports over append-heavy data.

ClickHouse is not a transactional database: row-by-row updates, deletes and single-row inserts are expensive. Keep application state in PostgreSQL or MySQL and stream events into ClickHouse.

Create an instance

Portal

1. Open the portal and choose New instance.
2. Pick ClickHouse and a version (26.8, 26.3, 25.3).
3. Choose a size and region. Secure placement is listed only after your organization has signed the BAA.
4. Check the hourly price and monthly estimate, then confirm. The Connect tab fills in when the instance is ready.

CLI

shell

zb instances create --engine clickhouse --engine-version 26.8 \
  --size s1 --region us-east --name clickhouse-demo --wait

# Reveal the credentials once and store them in your secret manager
zb instances credentials reveal clickhouse-demo

API

shell

curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/projects/$ZB_PROJECT/instances \
  -H "Authorization: Bearer $ZB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "engine": "clickhouse",
  "engine_version": "26.8",
  "size": "s1",
  "region": "us-east",
  "name": "clickhouse-demo"
}'

The response is 201 with the instance in status requested, or 202 when a team approval policy applies. See the REST API reference.

Connect

Endpoint and credentials

How a ClickHouse instance is reached: host, ports, TLS and credentials

Host	ch-<id>.<region>.databasezy.com, for example ch-7f3k.us-east.databasezy.com
Port 8443	HTTPS interface
Port 9440	native protocol over TLS for clickhouse-client and native drivers
TLS	Required on every port; plaintext is refused. Verify the server: https:// (or the driver's TLS flag) with normal certificate verification; the certificate is publicly trusted.
Credentials	Username app and a generated password, presented as HTTP Basic (or X-ClickHouse-User/Key headers); user and password on the native port. Shown once at creation; reveal or rotate it from the Connect tab.

Most drivers (clickhouse-connect for Python, @clickhouse/client for Node, the JDBC driver, Grafana and BI tools) use the HTTPS interface (port 8443) with HTTP Basic credentials. clickhouse-client and clickhouse-go in native mode use the native port 9440 with --secure or the driver’s TLS option.

Drivers and clients

ClickHouse listens on port 8443 (HTTPS interface); port 9440 (native protocol over TLS for clickhouse-client and native drivers). Versions: 26.8, 26.3, 25.3. Replace the example host with the one on your instance's Connect tab; credentials are shown once at creation.

Connection URI

https://ch-7f3k.us-east.databasezy.com:8443

Python

analytics.py

import os
import clickhouse_connect

client = clickhouse_connect.get_client(
    host="ch-7f3k.us-east.databasezy.com",
    port=8443,
    secure=True,               # HTTPS with certificate verification
    username="app",
    password=os.environ["ZB_PASSWORD"],
)
print(client.query("select version()").result_rows)

Tested with: ClickHouse 26.8 · clickhouse-connect 0.8 (HTTPS)

Node

analytics.js

import { createClient } from "@clickhouse/client";

const client = createClient({
  url: "https://ch-7f3k.us-east.databasezy.com:8443",
  username: "app",
  password: process.env.ZB_PASSWORD,
});

const rs = await client.query({ query: "select version() as v", format: "JSONEachRow" });
console.log(await rs.json());
await client.close();

Tested with: ClickHouse 26.8 · @clickhouse/client 1.x (HTTPS)

HTTP / curl

shell

# HTTPS interface
curl -sS -u app:$ZB_PASSWORD "https://ch-7f3k.us-east.databasezy.com:8443/" --data-binary "select version()"

# Native protocol over TLS
clickhouse-client --host ch-7f3k.us-east.databasezy.com --port 9440 --secure --user app --ask-password

Tested with: ClickHouse 26.8 · curl 8 · clickhouse-client 25.3

Insert in batches (thousands of rows per insert), or turn on async_insert=1 for many small writers; one insert per row creates many small parts and slows the server down.

See Connecting to Databasezy for the CA bundle, the IP allow-list and credential rotation, which work the same for every engine.

Migrate in

Where you can migrate a ClickHouse database from, how, and whether continuous sync is available

Source	How	Continuous sync	Guide status
Aiven	Connection string	No	Coming soon · phase 2
Self-hosted server	Connection string, Local tools (zb migrate --from local)	No	Available
Local files and dumps	File upload, Local tools (zb migrate --from local)	No	Available
Another Databasezy instance	Instance to instance	No	Coming soon · phase 2

ClickHouse sources are copied table by table with INSERT ... SELECT. Files load from your machine with clickhouse-client, which streams them over the native port:

shell

clickhouse-client --host ch-7f3k.us-east.databasezy.com --port 9440 --secure --user app --ask-password \
--query "INSERT INTO events FORMAT Parquet" < events.parquet

How migrations work explains preflight, verification and cutover, and engine conversions covers moves between compatible engines.

Backups and restore

Every backup is a full clickhouse-backup of the server’s data parts, taken from the first replica and uploaded to object storage; there are no incremental backups yet, so a backup copies all data each time. Users, roles and grants you create with SQL are not part of the backup.

ClickHouse backups use clickhouse-backup. They run inside the instance's namespace, stream straight to the cell's object storage and are checksummed on upload. How often they run and how long they are kept follows your plan's backup policy. A backup is always taken before a resize or a version upgrade.

Point-in-time recovery is not available for ClickHouse. A restore returns the data as of a scheduled or manual backup. Restores create a new instance by default and leave the original untouched; an in-place restore asks you to type the instance name and takes a pre-change backup first.

shell

zb backups create clickhouse-demo --label before-release      # manual snapshot
zb backups list clickhouse-demo
zb backups restore clickhouse-demo <backup-id> --name clickhouse-demo-restore

Pause and scale to zero

ClickHouse cannot be paused. A running instance bills compute for every hour it exists, so resize it down or delete it (backups are kept per your plan) when you do not need it.

See Pause and resume for schedules, wake times and billing while paused.

ClickHouse keeps background merges and caches warm, so it runs continuously. Resize down for quiet periods instead.

Limits, versions and lifecycle

Versions and lifecycle

• Supported versions: 26.8 , 26.3 , 25.3 . New instances default to 26.8; pick another at creation with --engine-version or in the portal.
• Minor and patch releases are applied for you in the maintenance window, always after a pre-change backup.
• New majors are added within 60 days of the upstream release. A major reaches end of life on Databasezy six months after upstream ends support, with notices 90, 30 and 7 days ahead.
• Moving between supported releases happens in place with a rolling restart, after a pre-change backup. Downgrades are refused; restore a backup into a new instance instead.

ClickHouse offers its long-term-support releases (March and August, each supported for a year). An in-place upgrade moves at most one year ahead, so going from 25.3 to 26.8 goes through 26.3.

High availability

With --ha, the instance runs two or more replicas (--replicas adds more, up to four extra) and a three-node ClickHouse Keeper ensemble. Both the HTTPS and the native endpoint spread connections over all replicas, and every replica accepts reads and writes. Only replicated tables are copied between replicas, so create them on the whole cluster with a replicated engine:

SQL

CREATE TABLE events ON CLUSTER main
(
  ts DateTime,
  user_id UInt64,
  event LowCardinality(String)
)
ENGINE = ReplicatedMergeTree
ORDER BY (user_id, ts);

A table created without ON CLUSTER main, or with plain MergeTree, exists on one replica only, and queries that land on another replica do not see it. Each replica and each Keeper node runs on its own node.

Sizes and limits

ClickHouse is not offered on the Free plan; it runs on the paid sizes below. The size sets the CPU, memory, storage ceiling and connection limit; the gateway refuses connections over the limit with a protocol error. Storage grows in steps up to the ceiling, and you can resize at any time.

Sizes available for ClickHouse: vCPU, memory, storage ceiling, connection limit and monthly price

Size	vCPU	Memory	Max storage	Max connections	≈ $ / month
s0	0.25	1 GiB	20 GB	60	$10
s1	0.5	2 GiB	50 GB	100	$15
s2	1	4 GiB	200 GB	200	$60
m2	2	8 GiB	500 GB	400	$110
m4	4	16 GiB	1 TB	800	$210
l8	8	32 GiB	4 TB	1,500	$410
l16	16	64 GiB	8 TB	3,000	$960
xl32	32	128 GiB	16 TB	5,000	$1,870

Full details, including hourly prices and burst CPU, are in the size catalogue; plan quotas are in limits and quotas.

Table functions and engines that reach outside services (s3, url, remote, Kafka) need outbound network access from the instance, which is restricted by default. Memory per query follows the size; heavy GROUP BY and JOIN queries on small sizes may need max_bytes_before_external_group_by or a larger size.

Licence

Databasezy runs ClickHouse under the Apache-2.0 licence, as listed in the engine catalogue. Your data and schemas are yours whatever the server's licence; the licence governs the server software we run.

ClickHouse is Apache-2.0. ClickHouse Cloud features (SharedMergeTree, compute-compute separation) are not part of the open-source server and are not included.

Security

• TLS on every connection. TLS 1.2 is the minimum and TLS 1.3 is preferred; plaintext is never offered. Verify the server, not just the encryption: use HTTPS with certificate verification. See TLS and the CA bundle.
• IP allow-list. The gateway checks the client address before authentication, on every plan. Manage it under Network → Allow-list in the portal or with PUT /v1/orgs/{org}/instances/{id}/network.
• Credentials. Generated inside the cell, shown once, never stored by the control plane. Rotate them with an overlap window so nothing breaks.
• Secure hosting. Secure placement (HIPAA-ready) is a per-instance option once your organization has signed the BAA: dedicated nodes, customer-managed keys and immutable backups. See Secure hosting and the BAA.
• Staff access. Databasezy staff cannot read your data without a grant you issue. See data confidentiality.

FAQ

Why can’t I pause ClickHouse?

The engine catalogue marks ClickHouse as not pausable, so an instance runs, and bills compute, until you resize or delete it.

HTTPS or native protocol?

Use HTTPS with the official Python and Node clients and most tools. Use the native port for clickhouse-client and native-mode drivers; both reach the same data.

Is ClickHouse on the Free plan?

No. It is a paid-plan engine.