From 0e88bc4950c56709b97f9a4c5f600954299a5d7b Mon Sep 17 00:00:00 2001 From: Han Fei Date: Mon, 10 Aug 2026 14:05:04 +0200 Subject: [PATCH 1/2] Deprecate ALTER TABLE UNLOCK SNAPSHOT and SYSTEM UNLOCK SNAPSHOT FROM clause --- .../operations_/backup_restore/05_snapshot.md | 25 ++++++------------- 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/docs/operations_/backup_restore/05_snapshot.md b/docs/operations_/backup_restore/05_snapshot.md index 593d6675e07..4c0e2956956 100644 --- a/docs/operations_/backup_restore/05_snapshot.md +++ b/docs/operations_/backup_restore/05_snapshot.md @@ -82,30 +82,19 @@ SETTINGS snapshot_from_current_service = 1 Each snapshot holds locks in ClickHouse Keeper that prevent the referenced object storage files from being garbage collected. After a restore completes — or when a snapshot is no longer needed — unlock it to release those locks. -There are two forms: a system-level unlock that removes all locks for the snapshot at once, and a per-table unlock that removes the lock for a single table while leaving the rest of the snapshot intact. - -**System-level unlock** — removes all locks for the snapshot: +Unlock a snapshot with `SYSTEM UNLOCK SNAPSHOT`, which removes all locks for the snapshot at once: ```sql SYSTEM UNLOCK SNAPSHOT '' -FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY') ``` -**Per-table unlock** — removes the lock for one table only: - -```sql -ALTER TABLE mydb.events UNLOCK SNAPSHOT '' -FROM S3('https://my-bucket.s3.us-east-1.amazonaws.com/snapshots/events/', 'ACCESS_KEY_ID', 'SECRET_ACCESS_KEY') -``` +:::note The `FROM` clause is deprecated +`SYSTEM UNLOCK SNAPSHOT` no longer takes a `FROM ` clause. It is still accepted for backward compatibility but ignored: the unlock now only removes the snapshot's commit marker in ClickHouse Keeper, so it does not read the backup destination and succeeds even when the backup files are already gone. +::: -The `FROM` clause is optional when the snapshot destination was stored in Keeper at creation time (visible in the `info` column of `system.snapshot_locks`): - -```sql -SYSTEM UNLOCK SNAPSHOT '' - --- or per-table: -ALTER TABLE mydb.events UNLOCK SNAPSHOT '' -``` +:::note `ALTER TABLE ... UNLOCK SNAPSHOT` is deprecated +The per-table form `ALTER TABLE ... UNLOCK SNAPSHOT` is deprecated and now throws an error. Use `SYSTEM UNLOCK SNAPSHOT` instead. +::: After unlocking, the corresponding row disappears from `system.snapshot_locks`, and parts no longer referenced by other snapshots drop out of `system.snapshot_parts`. From 5a46ce33a9196a1bac2a57b33daa68e7e9229899 Mon Sep 17 00:00:00 2001 From: Han Fei Date: Mon, 10 Aug 2026 14:11:20 +0200 Subject: [PATCH 2/2] address comments --- docs/operations_/backup_restore/05_snapshot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operations_/backup_restore/05_snapshot.md b/docs/operations_/backup_restore/05_snapshot.md index 4c0e2956956..45610296fd1 100644 --- a/docs/operations_/backup_restore/05_snapshot.md +++ b/docs/operations_/backup_restore/05_snapshot.md @@ -89,7 +89,7 @@ SYSTEM UNLOCK SNAPSHOT '' ``` :::note The `FROM` clause is deprecated -`SYSTEM UNLOCK SNAPSHOT` no longer takes a `FROM ` clause. It is still accepted for backward compatibility but ignored: the unlock now only removes the snapshot's commit marker in ClickHouse Keeper, so it does not read the backup destination and succeeds even when the backup files are already gone. +`SYSTEM UNLOCK SNAPSHOT` no longer takes a `FROM ` clause. It's still accepted for backward compatibility but ignored. ::: :::note `ALTER TABLE ... UNLOCK SNAPSHOT` is deprecated