diff --git a/docs/change-database/plan.mdx b/docs/change-database/plan.mdx index 61a735036..5f6f23ac2 100644 --- a/docs/change-database/plan.mdx +++ b/docs/change-database/plan.mdx @@ -2,42 +2,32 @@ title: Plan --- -A **Plan** is the core component of Bytebase’s CI/CD pipeline. It defines a series of schema or data changes to be applied to one or more databases. +A **Plan** is the core component of Bytebase’s CI/CD pipeline. It defines a series of schema or data changes to be applied to one or more databases. It can be converted into an **Issue** for review and deployment. -### 1. Create a New Plan -In your project, go to **CI/CD** > **Plans** in the left menu and click **New Plan**. +### 1. Create Plan -![new-plan](/content/docs/change-database/plan/bb-new-plan.webp) +In your project, navigate to **CI/CD** > **Plans** and click **+ New Plan**. -### 2. Choose the Change Type -Select either **Schema Migration (DDL)** or **Data Migration (DML)**. After adding the first change, you can continue to add more. +### 2. Select Databases -![plan-change-type](/content/docs/change-database/plan/bb-plan-change-type.webp) +Choose one or moretarget databases and click **Confirm**. -### 3. Select Target Databases -Choose one or more databases where the changes will be applied. Click **Confirm** to proceed. +### 3. Add Changes -![plan-targets](/content/docs/change-database/plan/bb-plan-targets.webp) +Add SQL statements (multiple allowed by clicking **+ Add Change**) and click **Create**. The plan will be in `Draft` status with automatic SQL review. -### 4. Add Changes -Fill in the SQL statement. You can add multiple changes to the same plan. Once done, click **Create**. +![bb-plan-warning-detail](/content/docs/change-database/plan/bb-plan-warning-detail.webp) -![plan-add-change](/content/docs/change-database/plan/bb-plan-add-change.webp) -![plan-2-change](/content/docs/change-database/plan/bb-plan-2-change.webp) +### 4. Submit for Review (Enterprise) -### 5. Submit for Review -The plan starts in a `draft` state. Click **Ready for Review** to submit it for approval. +Fix the warning, and click **Ready for Review**. The plan will be converted into an issue and await approval. Approval follows [configured rules](/change-database/approval). -![plan-draft](/content/docs/change-database/plan/bb-plan-draft.webp) +![plan-approval](/content/docs/change-database/plan/bb-plan-approval.webp) -### 6. Approve and Roll Out -Once approved, go to the **Rollout** section to begin deployment. +### 5. Deploy -![plan-approval](/content/docs/change-database/plan/bb-plan-approval.webp) -![plan-ready-rollout](/content/docs/change-database/plan/bb-plan-ready-rollout.webp) +After approval, go to the **Rollout** section to deploy changes. You may configure the rollout policy to `Automatic` in the [environment](/change-database/environment-policy/rollout-policy). -### 7. Deploy to Environments -First, deploy to the `Test` environment. If successful, proceed to deploy to `Prod`. +![bb-issue-2-targets-to-rollout](/content/docs/change-database/plan/bb-issue-2-targets-to-rollout.webp) -![plan-rollout-test](/content/docs/change-database/plan/bb-plan-rollout-test.webp) -![plan-rollout-prod](/content/docs/change-database/plan/bb-plan-rollout-prod.webp) \ No newline at end of file +Deploy to `Test` first, then `Prod` after success. \ No newline at end of file diff --git a/docs/content/docs/change-database/plan/bb-issue-2-targets-to-rollout.webp b/docs/content/docs/change-database/plan/bb-issue-2-targets-to-rollout.webp new file mode 100644 index 000000000..ded2714e7 Binary files /dev/null and b/docs/content/docs/change-database/plan/bb-issue-2-targets-to-rollout.webp differ diff --git a/docs/content/docs/change-database/plan/bb-new-plan.webp b/docs/content/docs/change-database/plan/bb-new-plan.webp deleted file mode 100644 index c0b66215e..000000000 Binary files a/docs/content/docs/change-database/plan/bb-new-plan.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-2-change.webp b/docs/content/docs/change-database/plan/bb-plan-2-change.webp deleted file mode 100644 index 1eb11d275..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-2-change.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-add-change.webp b/docs/content/docs/change-database/plan/bb-plan-add-change.webp deleted file mode 100644 index ccb4eea6c..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-add-change.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-change-type.webp b/docs/content/docs/change-database/plan/bb-plan-change-type.webp deleted file mode 100644 index 4aa5adbcf..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-change-type.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-draft.webp b/docs/content/docs/change-database/plan/bb-plan-draft.webp deleted file mode 100644 index d2e487995..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-draft.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-ready-rollout.webp b/docs/content/docs/change-database/plan/bb-plan-ready-rollout.webp deleted file mode 100644 index bcd8970be..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-ready-rollout.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-rollout-prod.webp b/docs/content/docs/change-database/plan/bb-plan-rollout-prod.webp deleted file mode 100644 index 35b0379c4..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-rollout-prod.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-rollout-test.webp b/docs/content/docs/change-database/plan/bb-plan-rollout-test.webp deleted file mode 100644 index a06878765..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-rollout-test.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-targets.webp b/docs/content/docs/change-database/plan/bb-plan-targets.webp deleted file mode 100644 index 86ebd11a5..000000000 Binary files a/docs/content/docs/change-database/plan/bb-plan-targets.webp and /dev/null differ diff --git a/docs/content/docs/change-database/plan/bb-plan-warning-detail.webp b/docs/content/docs/change-database/plan/bb-plan-warning-detail.webp new file mode 100644 index 000000000..ca45bac19 Binary files /dev/null and b/docs/content/docs/change-database/plan/bb-plan-warning-detail.webp differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-2-targets-to-rollout.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-2-targets-to-rollout.webp new file mode 100644 index 000000000..ded2714e7 Binary files /dev/null and b/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-2-targets-to-rollout.webp differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-done.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-done.webp deleted file mode 100644 index 8334d7957..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-done.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-approve.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-approve.webp deleted file mode 100644 index 1b968e0dd..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-approve.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-rollout.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-rollout.webp deleted file mode 100644 index 5ea2d56a2..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-issue-to-rollout.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create-warning.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create-warning.webp deleted file mode 100644 index 81f64399d..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create-warning.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create.webp deleted file mode 100644 index 39a57a572..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-checks-warning.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-checks-warning.webp deleted file mode 100644 index 272b7d4f3..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-checks-warning.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-passed.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-passed.webp deleted file mode 100644 index 9fa3d6580..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-passed.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-warning.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-warning.webp deleted file mode 100644 index db996d444..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-warning.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-ready-for-review.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-ready-for-review.webp deleted file mode 100644 index 21bf5f831..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-ready-for-review.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-warning-detail.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-warning-detail.webp new file mode 100644 index 000000000..ca45bac19 Binary files /dev/null and b/docs/content/docs/get-started/step-by-step/change-schema/bb-plan-warning-detail.webp differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-rollout-to-run.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-rollout-to-run.webp deleted file mode 100644 index 2ad782142..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-rollout-to-run.webp and /dev/null differ diff --git a/docs/content/docs/get-started/step-by-step/change-schema/bb-run-rollout.webp b/docs/content/docs/get-started/step-by-step/change-schema/bb-run-rollout.webp deleted file mode 100644 index 29f312bd1..000000000 Binary files a/docs/content/docs/get-started/step-by-step/change-schema/bb-run-rollout.webp and /dev/null differ diff --git a/docs/get-started/step-by-step/change-schema.mdx b/docs/get-started/step-by-step/change-schema.mdx index 94f40c70a..bd8436786 100644 --- a/docs/get-started/step-by-step/change-schema.mdx +++ b/docs/get-started/step-by-step/change-schema.mdx @@ -2,70 +2,40 @@ title: 'Step 6: Change Schema' --- -**Issue** serves as the starting point for managing database changes, including `Schema Change (DDL)` and `Data Change (DML)`. These changes follow a structured workflow: **Plan**, **Review**, **Approve**, and **Rollout**. For actions like `Database Creation`, the workflow might be simpler, omitting some steps. +Database changes follow four stages: **Plan**, **Review**, **Approve**, and **Rollout**. Plans become Issues when submitted for review. -## Initiate an Issue with a Plan +## Create a Plan -1. Navigate to **CI/CD** > **Plans** in your project menu and click **+ New Plan**. +1. Navigate to **CI/CD** > **Plans** and click **+ New Plan**. - ![new-plan](/content/docs/change-database/plan/bb-new-plan.webp) +1. Select target databases and click **Confirm**. -1. Choose either **Schema Migration (DDL)** or **Data Migration (DML)**. In this example, we select **Schema Migration (DDL)**. After adding the first change, you can continue to add more changes within the same plan. +1. Add your SQL statement or use **Schema Editor** for visual design. - ![plan-change-type](/content/docs/change-database/plan/bb-plan-change-type.webp) +## Create Issue & Run SQL Review -1. Select one or more databases where the changes will be applied. Click **Confirm** to proceed. +1. Click **Create** and the plan will be in `Draft` status with automatic SQL review. - ![plan-targets](/content/docs/change-database/plan/bb-plan-targets.webp) + ![bb-plan-warning-detail](/content/docs/get-started/step-by-step/change-schema/bb-plan-warning-detail.webp) -1. If only **one** database is selected, you can use the **Schema Editor** to visually design the schema. +1. Fix any warnings and click **Ready for Review** to convert the plan into an issue and await approval. - ![new-plan-schema-editor](/content/docs/change-database/schema-editor/bb-new-plan-schema-editor.webp) +## Approve (Enterprise) -## Review the Issue +1. Issue awaits approval per [configured rules](/change-database/approval). Approvers click **Approve**. -1. After clicking **Confirm**, you will be directed to the **Plan** page. Before clicking **Create**, you may choose to **Run checks** to execute the [configured SQL review](/sql-review/review-policy). +## Deploy - ![plan-before-create-warning](/content/docs/get-started/step-by-step/change-schema/bb-plan-before-create-warning.webp) +1. Click **Run** to deploy manually, or configure automatic rollout in environment settings. -1. Once you click **Create**, the plan will enter `Draft` status. You may still encounter warnings. Address these warnings first. + ![bb-issue-2-targets-to-rollout](/content/docs/get-started/step-by-step/change-schema/bb-issue-2-targets-to-rollout.webp) - ![plan-draft-warning](/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-warning.webp) - - ![plan-draft-passed](/content/docs/get-started/step-by-step/change-schema/bb-plan-draft-passed.webp) - -1. Click **Ready for Review** and then click **Confirm**. - - ![plan-ready-for-review](/content/docs/get-started/step-by-step/change-schema/bb-plan-ready-for-review.webp) - -## Approve the Issue - -1. The issue will await approval. The approval process is automatically matched by the [custom approval](/change-database/approval). - - ![issue-to-approve](/content/docs/get-started/step-by-step/change-schema/bb-issue-to-approve.webp) - -1. Click **Approve** to authorize the plan by the designated approvers. - -## Deploy the Issue - -1. Once all approvals are secured, the rollout is ready to be executed. - - ![issue-to-rollout](/content/docs/get-started/step-by-step/change-schema/bb-issue-to-rollout.webp) - -1. Click **Run** to deploy the issue. - - ![rollout-to-run](/content/docs/get-started/step-by-step/change-schema/bb-rollout-to-run.webp) - - ![run-rollout](/content/docs/get-started/step-by-step/change-schema/bb-run-rollout.webp) - -1. When all rollouts are successfully executed, the issue will be marked as `Done`. - - ![issue-done](/content/docs/get-started/step-by-step/change-schema/bb-issue-done.webp) +1. Issue marked `Done` when complete. ## Summary -An issue lifecycle: Plan -> Review -> Approve -> Rollout. +Plan → Review → Approve → Rollout ![issue-lifecycle](/content/docs/get-started/step-by-step/change-schema/issue-lifecycle.webp) -Refer to [Database Change Workflow](/change-database/change-workflow/) for more details. +See [Database Change Workflow](/change-database/change-workflow/) for details. diff --git a/docs/tutorials/sql-review-gui.mdx b/docs/tutorials/sql-review-gui.mdx index e4d7bee31..5e78b0afc 100644 --- a/docs/tutorials/sql-review-gui.mdx +++ b/docs/tutorials/sql-review-gui.mdx @@ -46,12 +46,6 @@ Make sure you have [Docker](https://www.docker.com/) installed, and if you don 1. Go to `Sample Project`, navigate to **CI/CD** > **Plans** and click **+ New Plan**. - ![new-plan](/content/docs/change-database/plan/bb-new-plan.webp) - -1. Select **Schema Migration (DDL)** as the change type. - - ![plan-change-type](/content/docs/change-database/plan/bb-plan-change-type.webp) - 1. Select `hr_prod` database as the target since the default SQL Review policy is attached to the `Prod` environment. Click **Confirm** to proceed. You can use the **Schema Editor** to visually design the schema, here we'll intentionally uncheck **Not Null** for `nickname` column. 1. The plan will be in `Draft` status. SQL Review will run automatically, and you'll see violations against our defined rules marked in orange as `warning`.