First Schema Change in 5 Minutes

In this tutorial, you’ll use the default sample databases to get familiar with the product in the quickest way.

Step 1 - Run via Docker

1. Install and start Docker.

2. Open Terminal to run the command:

   docker run --rm --init \
     --name bytebase \
     --publish 8080:8080 --pull always \
     --volume ~/.bytebase/data:/var/opt/bytebase \
     bytebase/bytebase:latest
   

   

3. Open Bytebase in localhost:8080, fill in the fields and click Create admin account. You’ll be redirected to Workspace.

Step 2 - Configure the SQL Review

1. Navigate to CI/CD > SQL Review in the left menu. Click + New SQL Review to create a new SQL review.

2. Choose Sample Template which has 20 enabled rules and click Confirm and add. Attach the SQL review to Environment Prod and click Confirm.

3. You’ll see the SQL review is created.

Step 3 - Create a Plan

1. Navigate to CI/CD > Plans in the left menu and click + New Plan.

2. Select Schema Migration (DDL) as the change type.

3. Select the databases where changes will be applied:

   • hr_test on Test Sample instance
   • hr_prod on Prod Sample instance Click Confirm to proceed.

4. Add the SQL statement:

   ALTER TABLE public.employee ADD COLUMN IF NOT EXISTS nickname TEXT;
   

   Click Create to create the plan.

5. The plan will be in Draft status. You may see SQL review warnings, especially for the production environment. This is because Bytebase automatically runs configured checks.

Step 4 - Review and Approve

1. To fix the SQL review warning, edit the SQL to add NOT NULL DEFAULT '':

   ALTER TABLE public.employee ADD COLUMN IF NOT EXISTS nickname TEXT NOT NULL DEFAULT '';
   

   Click Save to update the plan. The checks will run again and should pass.

2. Click Ready for Review and then Confirm to submit the plan for approval.

3. The plan has no approval required.

Step 4 - Deploy the Changes

1. Navigate to the Rollout section. You’ll see the deployment is ready for both Test and Prod environments.

2. Click Run for the Test stage first and then if it’s successful, click Run for the Prod stage.

3. When all rollouts are successfully executed, the issue will be marked as Done.

Next Step

Now you have successfully performed your first schema change, the core workflow in Bytebase. Next:

• If you want to move changes between environments, follow How to Move Schema Change from Test to Prod
• If you want to rollout manually, follow Deploy Schema Change with Rollout Policy.
• If you want to assign approvers before the rollout, follow Database Change with Risk-Based Approval Flow