From 713ed22ea81df2cf4871c1d4ff9af2836fee9125 Mon Sep 17 00:00:00 2001 From: Garrett Thomas Date: Fri, 26 Jun 2026 14:49:59 -0700 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20BYOB=20restore=20=E2=80=94=20docume?= =?UTF-8?q?nt=20restore=5Faccess=5Fentities=5Fwith=5Fcurrent=5Fgrants=20(2?= =?UTF-8?q?6.4+)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03_backup_restore_using_commands.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md index 5873b911d3c..17c6e71344e 100644 --- a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md +++ b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md @@ -177,6 +177,31 @@ where `uuid` is a unique identifier, used to identify the backup. +```sql +RESTORE ALL +FROM S3( + 'https://testchbackups.s3.amazonaws.com/', + '', + '' +) +SETTINGS restore_access_entities_with_current_grants = 1 +``` + +:::note Restoring users and roles requires ClickHouse 26.4 or later +The `restore_access_entities_with_current_grants` setting is available from ClickHouse Cloud version **26.4** (build **26.4.1.1942** or later). +You can check the version your service is running with: + +```sql +SELECT version() +``` + +When enabled, restored users and roles have their grants limited to what the restoring user is allowed to grant +(the same semantics as [`GRANT CURRENT GRANTS`](/sql-reference/statements/grant)), instead of the `RESTORE` +failing with `ACCESS_DENIED` when the backup contains more permissions than the restoring user can grant. + +On versions earlier than 26.4, omit the setting and exclude the access entities from the restore instead, so that +the `RESTORE` does not fail (note that your users and roles will not be restored in this case): + ```sql RESTORE ALL EXCEPT TABLES system.users, system.roles FROM S3( @@ -185,6 +210,7 @@ FROM S3( '' ) ``` +::: From 8d793494db9523945e9e0a29e850ae7bbc306b64 Mon Sep 17 00:00:00 2001 From: Garrett Thomas Date: Fri, 26 Jun 2026 14:53:07 -0700 Subject: [PATCH 2/5] docs: drop redundant pre-26.4 RESTORE ALL EXCEPT example, keep inline note Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03_backup_restore_using_commands.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md index 17c6e71344e..e2fddf1bed7 100644 --- a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md +++ b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md @@ -199,17 +199,7 @@ When enabled, restored users and roles have their grants limited to what the res (the same semantics as [`GRANT CURRENT GRANTS`](/sql-reference/statements/grant)), instead of the `RESTORE` failing with `ACCESS_DENIED` when the backup contains more permissions than the restoring user can grant. -On versions earlier than 26.4, omit the setting and exclude the access entities from the restore instead, so that -the `RESTORE` does not fail (note that your users and roles will not be restored in this case): - -```sql -RESTORE ALL EXCEPT TABLES system.users, system.roles -FROM S3( - 'https://testchbackups.s3.amazonaws.com/', - '', - '' -) -``` +On versions earlier than 26.4, omit the setting and exclude the access entities from the restore instead by using `RESTORE ALL EXCEPT TABLES system.users, system.roles` (note that your users and roles will not be restored in this case). ::: From 7e43eb00b74c2b8e451d823c31f76ae10e32b7c9 Mon Sep 17 00:00:00 2001 From: Garrett Thomas Date: Fri, 26 Jun 2026 14:53:49 -0700 Subject: [PATCH 3/5] docs: remove pre-26.4 EXCEPT fallback sentence from BYOB restore note Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03_backup_restore_using_commands.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md index e2fddf1bed7..8432903f995 100644 --- a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md +++ b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md @@ -198,8 +198,6 @@ SELECT version() When enabled, restored users and roles have their grants limited to what the restoring user is allowed to grant (the same semantics as [`GRANT CURRENT GRANTS`](/sql-reference/statements/grant)), instead of the `RESTORE` failing with `ACCESS_DENIED` when the backup contains more permissions than the restoring user can grant. - -On versions earlier than 26.4, omit the setting and exclude the access entities from the restore instead by using `RESTORE ALL EXCEPT TABLES system.users, system.roles` (note that your users and roles will not be restored in this case). ::: From 70271a3c472d488f2e16374d3c05525ce191fecd Mon Sep 17 00:00:00 2001 From: Garrett Thomas Date: Fri, 26 Jun 2026 14:55:25 -0700 Subject: [PATCH 4/5] docs: un-admonition the version note and re-add short pre-26.4 line Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03_backup_restore_using_commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md index 8432903f995..45ae84fd07b 100644 --- a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md +++ b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md @@ -187,7 +187,6 @@ FROM S3( SETTINGS restore_access_entities_with_current_grants = 1 ``` -:::note Restoring users and roles requires ClickHouse 26.4 or later The `restore_access_entities_with_current_grants` setting is available from ClickHouse Cloud version **26.4** (build **26.4.1.1942** or later). You can check the version your service is running with: @@ -198,7 +197,8 @@ SELECT version() When enabled, restored users and roles have their grants limited to what the restoring user is allowed to grant (the same semantics as [`GRANT CURRENT GRANTS`](/sql-reference/statements/grant)), instead of the `RESTORE` failing with `ACCESS_DENIED` when the backup contains more permissions than the restoring user can grant. -::: + +On versions earlier than 26.4, omit the setting. From 41bcad644a040b41232319a70756ade292a0c0a5 Mon Sep 17 00:00:00 2001 From: Garrett Thomas Date: Fri, 26 Jun 2026 15:06:09 -0700 Subject: [PATCH 5/5] docs: name the setting explicitly in the 'when enabled' sentence Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03_backup_restore_using_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md index 45ae84fd07b..0f9cde2a162 100644 --- a/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md +++ b/docs/cloud/guides/backups/03_bring_your_own_backup/03_backup_restore_using_commands.md @@ -194,7 +194,7 @@ You can check the version your service is running with: SELECT version() ``` -When enabled, restored users and roles have their grants limited to what the restoring user is allowed to grant +When `restore_access_entities_with_current_grants` is enabled, restored users and roles have their grants limited to what the restoring user is allowed to grant (the same semantics as [`GRANT CURRENT GRANTS`](/sql-reference/statements/grant)), instead of the `RESTORE` failing with `ACCESS_DENIED` when the backup contains more permissions than the restoring user can grant.