Guide: migrating from OSS to Cloud using BACKUP/RESTORE commands #4663

Blargian · 2025-10-29T08:41:58Z

Summary

Adds a guide on how to migrate from OSS to Cloud using BACKUP/RESTORE commands.

Also splits out the guide on how to set up an S3 bucket and IAM role into it's own page instead of a snippet and updates the images. The previous one is quite outdated.

Backup and restore docs are improved here: #4049

Checklist

Delete items not relevant to your PR
URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/index.mdx

vercel · 2025-10-29T08:42:02Z

@Blargian is attempting to deploy a commit to the ClickHouse Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2025-10-29T14:27:08Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
clickhouse-docs	Ready	Preview	Jan 7, 2026 11:24am
clickhouse-docs-ru	Error		Jan 7, 2026 11:24am
clickhouse-docs-zh	Error		Jan 7, 2026 11:24am

docs/_snippets/_S3_authentication_and_bucket.md

docs/cloud/guides/data_sources/02_accessing-s3-data-securely.md

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

dhtclk · 2025-11-17T17:07:58Z

Hey Shaun - I've reviewed this and think we need to do some rewording and restructuring to align with docs standards for new or updated guides. A few things I'm thinking:

Writing style updates (Google style guide - conversational tone, contractions)
Better organization/flow in a few sections
Using vertical stepper for the main steps

Happy to discuss or pair on this.

Blargian · 2026-01-07T12:55:23Z

Preview link: https://clickhouse-docs-mbdg1rmcu-clickhouse.vercel.app/docs/cloud/migration/oss-to-cloud-backup-restore

mneedham · 2026-01-07T13:49:11Z

docs/integrations/data-ingestion/s3/creating-an-s3-iam-role-and-bucket.md

+            "Principal": {
+                "AWS": "arn:aws:iam::782985192762:user/docs-s3-user"
+            },
+            "Action": "s3:*",


Do you think it's worth mentioning that the bucket policy makes it possible to do all actions on the bucket?

mneedham · 2026-01-07T13:50:59Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+
+## Overview {#overview-migration-approaches}
+
+There are two primary methods to migrate from self-managed ClickHouse (OSS) to ClickHouse Cloud:


Maybe say 'migrate data'

mneedham · 2026-01-07T13:52:53Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+:::
+
+## OSS preparation {#oss-setup}
+


Let's add a sentence explaining what we're doing, something like:

We'll first spin up a ClickHouse cluster using a Docker Compose configuration from our examples repository.

And then continue with the instructions

Perhaps we can also put something that says they can ignore spinning up the ClickHouse cluster if they already have one running themselves?

mneedham · 2026-01-07T13:55:57Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+### Create sample data {#create-sample-data}
+
+For this guide, we'll use the New York taxi dataset as sample data.
+Follow the first two steps of the [New York taxi data guide](/getting-started/example-datasets/nyc-taxi) to create the table and load data.


I found this a bit confusing as I thought I should go to that guide but actually we include the instructions below, so let's explain that. Something like:

We're going to follow the first two steps of the [New York taxi data guide](/getting-started/example-datasets/nyc-taxi) to create the table and load data. Those steps are included below for your convenience

mneedham · 2026-01-07T14:00:39Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+
+In the `CREATE TABLE` DDL statement we specified the table engine type as `MergeTree`, however
+ClickHouse Cloud works with [`SharedMergeTree`](/cloud/reference/shared-merge-tree). When restoring a backup, ClickHouse automatically converts `ReplicatedMergeTree` to `SharedMergeTree`.
+However, you'll need to convert any `MergeTree` tables to `ReplicatedMergeTree` before backing them up.


Let's move this whole explanation to be just below the DDL statement.

I'm also wondering why did we create the table as MergeTree only to then convert it to replicated in the following section? If people are using a cluster, would they usually be having their tables as ReplicatedMergeTree anyway?

If so then maybe we can include the explanation of how to convert a table from MergeTree to ReplicatedMergeTree as a mini guide that we link to rather than having it inline this one?

mneedham · 2026-01-07T14:03:40Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+#highlight-end                            
+                ]
+            },
+            "Action": "s3:*",


Do they need to this set to all actions?

mneedham · 2026-01-07T14:05:01Z

docs/cloud/onboard/02_migrate/01_migration_guides/07_OSS_to_Cloud/02_oss_to_cloud_backups.md

+- Quotas
+- User-defined functions
+
+If you're using a different CSP, you can use the `TO S3()` (for both AWS and GCP) and `TO AzureBlobStorage()` syntax.


Maybe spell out CSP (cloud service provider) - not sure if the acronymn is super well know to end users.

mneedham · 2026-01-07T14:08:27Z

docs/cloud/guides/data_sources/02_accessing-s3-data-securely.md


-This article demonstrates how to leverage role-based access to authenticate with Amazon Simple Storage Service (S3) and access your data securely from ClickHouse Cloud.
+This guide demonstrates how ClickHouse Cloud customers can leverage role-based access to authenticate with Amazon Simple Storage Service (S3) and access their data securely.
+Before diving into the setup for secure S3 access, it is important to understand how this works. Below is an overview of how ClickHouse services can access private S3 buckets by assuming into a role within customers' AWS account.


I think we don't need into

Below is an overview of how ClickHouse services can access private S3 buckets by assuming into a role within customers' AWS account.

becomes

Below is an overview of how ClickHouse services can access private S3 buckets by assuming a role within customers' AWS account.

Blargian added 5 commits October 28, 2025 12:36

update IAM and S3 bucket steps to 2025

23ab174

add first draft of OSS to Cloud with backup/restore page

c5500de

edit

df734d8

edits

b2743ea

update IAM and S3 bucket steps to 2025

77a328d

Blargian requested review from a team as code owners October 29, 2025 08:41

Blargian added 6 commits October 29, 2025 11:51

fix typo

f463387

add anchors

a31cd21

Update creating-an-s3-iam-role-and-bucket.md

55ff192

override link

794d22d

fix sed_links

bf436e6

fix sed script

4e354e0

vercel bot deployed to Preview – clickhouse-docs October 29, 2025 14:39 View deployment

dhtclk requested changes Nov 17, 2025

View reviewed changes

Blargian added 3 commits December 1, 2025 14:55

incorporate review feedback

c2c1c1c

incorporate review feedback

f6a2a0c

merge main and resolve conflicts

7e4bb10

vercel bot had a problem deploying to Preview – clickhouse-docs-jp December 1, 2025 14:15 Failure

vercel bot had a problem deploying to Preview – clickhouse-docs-ru December 1, 2025 14:15 Failure

vercel bot had a problem deploying to Preview – clickhouse-docs-zh December 1, 2025 14:16 Failure

vercel bot deployed to Preview – clickhouse-docs December 1, 2025 14:20 View deployment

Blargian requested a review from dhtclk December 11, 2025 13:33

Blargian added the waiting for feedback label Dec 12, 2025

Merge branch 'main' into oss_to_cloud_with_commands_guide

dee64a9

vercel bot deployed to Preview – clickhouse-docs January 7, 2026 11:24 View deployment

mneedham reviewed Jan 7, 2026

View reviewed changes


		## Overview {#overview-migration-approaches}

		There are two primary methods to migrate from self-managed ClickHouse (OSS) to ClickHouse Cloud:

Guide: migrating from OSS to Cloud using BACKUP/RESTORE commands #4663

Are you sure you want to change the base?

Guide: migrating from OSS to Cloud using BACKUP/RESTORE commands #4663

Uh oh!

Conversation

Blargian commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Uh oh!

vercel bot commented Oct 29, 2025

Uh oh!

vercel bot commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dhtclk commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Blargian commented Jan 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Blargian commented Oct 29, 2025 •

edited

Loading

vercel bot commented Oct 29, 2025 •

edited

Loading

dhtclk commented Nov 17, 2025 •

edited

Loading