Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 15 additions & 25 deletions docs/change-database/plan.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Deploy to `Test` first, then `Prod` after success.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
64 changes: 17 additions & 47 deletions docs/get-started/step-by-step/change-schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 0 additions & 6 deletions docs/tutorials/sql-review-gui.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down