Your 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:3.0.1

   Bytebase starts successfully if you see following message.

   ██████╗ ██╗   ██╗████████╗███████╗██████╗  █████╗ ███████╗███████╗
   ██╔══██╗╚██╗ ██╔╝╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝
   ██████╔╝ ╚████╔╝    ██║   █████╗  ██████╔╝███████║███████╗█████╗
   ██╔══██╗  ╚██╔╝     ██║   ██╔══╝  ██╔══██╗██╔══██║╚════██║██╔══╝
   ██████╔╝   ██║      ██║   ███████╗██████╔╝██║  ██║███████║███████╗
   ╚═════╝    ╚═╝      ╚═╝   ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝
   
   Version 3.0.1 has started on port 8080 🚀

   Now you have Bytebase running in Docker.

   

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

4. You can click your avatar on top right and Quickstart from the dropdown menu.

Step 2 - One Issue with Two Stages#

1. Click My Issues on the left sidebar, and click the issue SAM-101 which is created by default.

2. The issue is waiting to rollout. There's a pipeline consisting of two stages:

   1. Test Stage: apply to database hr_test on Test Sample instance
   2. Prod Stage: apply to database hr_prod on Prod Sample instance

   Test stage is active by default.

   

3. Click Prod Stage to switch to it, and you will see the two stages share the same SQL but to different databases. You may also notice there's a warning sign for SQL review on the Prod stage. That's because when the issue is created, Bytebase will run task checks automatically.

4. Click the warning sign to see the details. If you wonder why only Prod stage has the warning sign, it's because by default SQL Review is only configured for Prod environment.

   

Step 3 - Roll out on Test Stage#

1. Switch back to Test Stage and click Rollout. Click Rollout on the confirmation dialog.

2. When the SQL is applied, there will be a checkmark on the Test Stage. Click View change and you'll see the change history diff.

   

Step 4 - Roll out on Prod Stage#

There are two ways to roll out on Prod Stage regarding the SQL review result.

1. If you are confident with the SQL, you can click Rollout directly. Tick Rollout anyway, and click Rollout on the confirmation dialog.

2. Another way is to edit SQL. Click Edit on top of SQL block, add NOT NULL. It will be like:

   ALTER TABLE employee ADD COLUMN IF NOT EXISTS email TEXT NOT NULL DEFAULT '';

   Click Save, the checks will be run again. This time the SQL review will pass. The issue will roll out and become Done.

   

   You may go to Environments to alter whether it rolls out automatically.

   

Next Step#

Now you have successfully performed your first schema change, the core workflow in Bytebase. If you want to try manual review during rollout, please continue to Deploy Schema Migration with Rollout Policy.