diff --git a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-done.webp b/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-done.webp
deleted file mode 100644
index c101b73e9..000000000
Binary files a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-done.webp and /dev/null differ
diff --git a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-prod.webp b/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-prod.webp
deleted file mode 100644
index c10557acd..000000000
Binary files a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-add-email-prod.webp and /dev/null differ
diff --git a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-rollout-anyway.webp b/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-rollout-anyway.webp
deleted file mode 100644
index f7040b070..000000000
Binary files a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-issue-rollout-anyway.webp and /dev/null differ
diff --git a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-sync-rollback-done.webp b/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-sync-rollback-done.webp
deleted file mode 100644
index deebba129..000000000
Binary files a/mintlify/content/docs/tutorials/how-to-synchronize-database-schemas/bb-sync-rollback-done.webp and /dev/null differ
diff --git a/mintlify/tutorials/how-to-synchronize-database-schemas.mdx b/mintlify/tutorials/how-to-synchronize-database-schemas.mdx
index 7ecd9537b..ed59b8257 100644
--- a/mintlify/tutorials/how-to-synchronize-database-schemas.mdx
+++ b/mintlify/tutorials/how-to-synchronize-database-schemas.mdx
@@ -1,7 +1,7 @@
---
title: How to Synchronize Database Schemas
author: Adela
-updated_at: 2024/02/29 18:00
+updated_at: 2025/08/11 18:00
feature_image: /content/docs/tutorials/how-to-synchronize-database-schemas/workflow.webp
tags: Tutorial
integrations: General
@@ -10,29 +10,28 @@ level: Beginner
estimated_time: '10 mins'
---
-import TerminalDockerRunVolume from '/snippets/install/terminal-docker-run-volume.mdx';
+import PreparationWithSampleData from '/snippets/tutorials/preparation-with-sample-data.mdx';
-This tutorial will walk you through the typical use cases for **database schema synchronization** in Bytebase with **pure UI operations**.
+Database schema synchronization ensures consistency across multiple databases by replicating schema changes from a source to target databases. This eliminates manual SQL writing and reduces deployment errors.
-The **Sync Schema** feature in Bytebase supports copying a specific schema version from one database to multiple others. Without it, developers have to write SQL statements cautiously and apply them manually. Additionally, this feature may also be used for rollback purpose.
+Bytebase's **Sync Schema** feature enables:
+- Replicating schemas to new databases
+- Synchronizing changes across environments (dev → staging → prod)
+- Rolling back to previous schema versions
-## Preparation
+This tutorial demonstrates three common synchronization scenarios using the Bytebase UI.
-Make sure you installed [Docker](https://www.docker.com/).
+## Start Bytebase with sample data
-1. Copy and paste the commands to start one Bytebase via Docker.
+
-
+## Case 1 - Sync schema to a new database
-1. Register and sign in **Bytebase Console**.
+Use this when setting up a new environment or scaling out your database infrastructure.
-## Case 1 - Sync Schema to a New Database
+1. In `Sample Project`, navigate to **Database > Databases**. You'll see `hr_test` (Test) and `hr_prod` (Prod) databases.
-When you set up a new environment or find the current database is nearing capacity, it becomes necessary to establish a new database and synchronize the schema from the original database.
-
-1. Go into `Sample Project`, there are two databases `hr_test` on `Test` environment and `hr_prod` on `Prod` environment. Let's create another one on `Prod`.
-
-2. Click **New DB**, fill in the form as follows and click **Create**:
+1. Click **+ New DB** and configure:
- **Name**: `hr_prod_2`
- **Environment**: `Prod`
@@ -40,68 +39,77 @@ When you set up a new environment or find the current database is nearing capaci
- **Database owner name**: `bbsample`
-3. An issue will be created and executed automatically, and the database `hr_prod_2` will be ready when the issue is `Done`.
+1. Click **Create**. An issue is created and executed automatically. Wait for it to complete.
-4. Within the project, click **Sync Schema**, choose `hr_prod` as the source schema, and click **Next**.
+1. Click **Sync Schema** in the left sidebar. Select `hr_prod` as the source and click **Next**.
-5. You may select as many target databases as you like to sync to. Here we select all (including the source) and click **Select**.
+1. Select `hr_prod_2` as the target database and click **Select**.
-6. Bytebase will calculate the schema differences between the source and target databases, and generate the suggested DDL statements. Click **Preview Issue**.
+1. Review the calculated schema differences and generated DDL statements. Click **Preview Issue**.
-7. An issue with the generated DDL is created automatically. Click **Rollout** ignoring the SQL review warning. After the issue execution is `Done`, the schema synchronization is completed.
- 
+1. Click **Create**, then **Ready for Review**. Navigate to **Rollout** and click **Run**. The schema is now synchronized to the new database.
+
+## Case 2 - Sync schema from one to many
+
+Use this for:
-## Case 2 - Sync Schema from One to Many
+- Promoting changes across environments (dev → staging → prod)
+- Multi-tenant SaaS deployments
+- Multi-region database synchronization
-During the product release process, for different environments, such as dev, staging and prod, you'll need to do schema synchronization. Furthermore, for the prod environment, databases with identical schemas, such as SaaS, and multi-region game deployment, you may also need to sync the schema to multiple databases at the same time.
+1. Navigate to **CI/CD > Plans** and click **+ New Plan**.
-1. Within the project, select `hr_test` and click **Edit Schema**. With the help of Schema Editor, add a new column `email` as follows and click **Preview issue**:
+1. Select **Schema Migration** and choose only `hr_test` as the target database.
+1. Use the **Schema Editor** to add a new column:
- **Name**: `email`
- **Type**: `text`
- **Default**: `Empty string`
- - **Not Null**: `checked`
+ - **Not Null**: checked
-2. An issue is created and executed automatically. After it's `Done`, the new column `email` is added.
- 
+1. Click **Create**, then **Ready for Review**. Go to **Rollout** and click **Run**. Wait for completion.
-3. Within the project, click **Sync Schema**, choose `hr_test` as the source schema and click **Next**.
+1. Click **Sync Schema** in the left sidebar. Select `hr_test` as the source and click **Next**.
-4. Select `hr_prod` and `hr_prod_2` as the target databases. Schema differences are calculated and the suggested DDL statements are generated. Click **Preview issue**.
+1. Select both `hr_prod` and `hr_prod_2` as targets. Review the schema differences and click **Preview issue**.
-5. An issue with the generated DDL is created automatically. Because two databases need to be synced, there're two task blocks. After they execute one by one, the issue is `Done`, and `email` is added.
- 
+1. Click **Create**, then **Ready for Review**. Navigate to **Rollout** and click **Run** for each stage. The `email` column is now synchronized to both production databases.
-## Case 3 - Rollback to Previous Schema Versions
+## Case 3 - Rollback to previous schema versions
-In Bytebase **Community Plan**, you can choose the latest history version; In **Pro Plan** or **Enterprise Plan**, you can choose an arbitrary schema version from the full migration history. Which means you can roll back to any previous schema version.
+Use schema synchronization to roll back databases to any previous version from their migration history.
-1. After upgrading to **Enterprise Plan**, go into `Sample Project`, click **Sync Schema** and select `hr_test` as the source schema. When you choose the schema version, you will see the following prompt. That's because we haven't assigned the enterprise license to database instances.
- 
+1. Navigate to **Sync Schema** and select `hr_test` as the source database.
-1. Click on the lock sign, select both two instances, and click **Confirm**.
- 
-
-1. After the license is assigned, you can choose the schema version freely, we'll choose the previous version and click **Next**.
+1. Select a previous schema version from the dropdown and click **Next**.
-1. Choose the same database `hr_test` as the target, and click **Select**.
+1. Select `hr_test` itself as the target (rolling back the same database) and click **Select**.
-1. Bytebase will calculate the schema differences between the source and target databases, and generate the suggested DDL statements. Here means if you want to roll back to the previous version, you'll need to delete this line. Click **Preview Issue**.
+1. Review the rollback changes. The DDL will show what needs to be removed or modified. Click **Preview Issue**.
-1. Click **Create**, an issue with the generated DDL is created and rollout automatically. After the issue execution is `Done`, the schema rolls back to the previous version.
- 
+1. Click **Create**, then **Ready for Review**. Navigate to **Rollout** and click **Run**. The schema successfully rolls back to the selected version.
## Summary
-Is the experience smooth? Or do you encounter any problems? Feel free to join our [Discord Group](https://discord.gg/huyw7gRsyA) to talk about it!
+You've learned how to:
+
+- Synchronize schemas to new databases
+- Propagate changes across multiple environments
+- Roll back to previous schema versions
+
+## Next steps
+
+- Learn about [batch changes](/change-database/batch-change/)
+- Explore [GitOps integration](/vcs-integration/overview/)
+- Join our [Discord community](https://discord.gg/huyw7gRsyA) for support