How to back up a ClickHouse Docker container (2026)
ClickHouse needs a consistent dump before it touches restic. Dockstash runs `clickhouse-client --query "BACKUP DATABASE default TO Disk('backups', 'snapshot')"` inside the container, captures the output, and stores it encrypted off-site — it never copies /var/lib/clickhouse live, because the native BACKUP statement freezes table parts consistently, because ClickHouse merges and mutates parts in the background where a raw copy would tear.
What Dockstash detects
| Env keys detected | CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_DB |
|---|---|
| Default port | 8123 |
| Live data paths (never copied live) | /var/lib/clickhouse |
| Example images | clickhouse/clickhouse-server:24, clickhouse/clickhouse-server, yandex/clickhouse-server |
The dump command
clickhouse-client --query "BACKUP DATABASE default TO Disk('backups', 'snapshot')"The restore command
clickhouse-client --query "RESTORE DATABASE default FROM Disk('backups', 'snapshot')"the native BACKUP statement freezes table parts consistently, because ClickHouse merges and mutates parts in the background where a raw copy would tear.
Gotchas to avoid
- Never restic the live /var/lib/clickhouse/store directory — parts are merged and mutated in the background, so a raw copy is inconsistent.
- The BACKUP/RESTORE SQL requires a configured backup disk in the server config; without it, use the clickhouse-backup tool which freezes parts via hardlinks.
- Large MergeTree tables produce large backups; incremental restic dedup helps but the initial BACKUP can be sizeable.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Frequently asked questions
What is the correct way to back up ClickHouse?
Use the native BACKUP statement (BACKUP DATABASE ... TO Disk(...)) or the clickhouse-backup tool. Both produce a consistent snapshot of table parts. Dockstash then restics the resulting backup directory.
Can I copy /var/lib/clickhouse instead?
No. ClickHouse continuously merges and mutates parts in the background, so a live directory copy is inconsistent. The BACKUP statement or clickhouse-backup freeze the parts safely.
BACKUP statement or clickhouse-backup — which should I use?
The native BACKUP statement is simplest when a backup disk is configured. clickhouse-backup is handy for freezing parts via hardlinks and shipping them, especially on older versions. Dockstash supports either output.
Are ClickHouse backups incremental?
The BACKUP statement supports incremental backups against a base, and restic adds its own deduplication on top, so repeated snapshots stay compact.