First Schema Change in 5 Minutes

Learn Bytebase’s schema change workflow using sample databases.

Configuring SQL Review requires policy-management permission. Custom approval flows require Enterprise.

Step 1 - Setup Bytebase

1. Ensure Docker is running, then start the Bytebase container:

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

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

   

3. During workspace setup, choose the built-in sample data.

   

Keep Enable sample databases selected during setup. Use the project created there and its hr_test database on Sample Project Instance in Test.

Step 2 - Configure SQL Review

1. Navigate to CI/CD > SQL Review and click + Create SQL review.

2. Name the policy, select Sample Template, and click Next. Confirm the PostgreSQL rule Enforce “NOT NULL” constraints on columns is set to Warning, click Create, and attach the policy to Test.

Step 3 - Create a Plan

1. Open the sample project, then navigate to CI/CD > Plans and click + New Plan.

2. Select hr_test on Sample Project Instance in Test, then click Confirm.

3. Add this SQL statement (or use Schema Editor for visual design):

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

   Click Create.

4. The plan is then in Draft status. Any SQL review warnings appear because Bytebase automatically checks against your configured policy. Click warnings for details.

   The NOT NULL rule reports that nickname allows null values.

Step 4 - Review and Approve

1. Fix the warning by adding NOT NULL DEFAULT '':

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

   Click Save. The checks rerun and pass.

2. Click Ready for Review to submit the Plan. Its linked Issue records review and approval; the Plan continues to track the change.

3. If approval is required, wait for the reviewer identified in Review. Otherwise, review completes automatically.

   

Step 5 - Deploy Changes

1. In the Deploy section, the Test deployment is ready after review and checks are satisfied.

2. Click Run for Test, choose Run immediately, and confirm.

3. Once complete, the Plan is marked Deployed.

   

Next Steps

You’ve completed your first schema change. Continue with:

• Move Schema Changes from Test to Prod - for environment transitions
• Deploy with Rollout Policy - for manual rollouts
• Custom Approval Flow - for adding approvers