Steamline Database Schema Changes with Changelist

Changelist allows you to stage a set of ordered changes. Then at a later time, you can repeatedly apply them to the databases or export them as zip files to apply the changes offline.

This tutorial will instruct you on how to use Changelist to generate an issue that compiles all necessary schema changes sequentially.

The Changelist can include 3 change sources:

• Change history
• Branch diff
• Raw SQL

In the tutorial, we will prepare the Change history and Branch first and then compose a Changelist including all 3 sources.

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.1.0

   When the Terminal shows the following message, the execution is successful.

   ██████╗ ██╗   ██╗████████╗███████╗██████╗  █████╗ ███████╗███████╗
   ██╔══██╗╚██╗ ██╔╝╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝
   ██████╔╝ ╚████╔╝    ██║   █████╗  ██████╔╝███████║███████╗█████╗
   ██╔══██╗  ╚██╔╝     ██║   ██╔══╝  ██╔══██╗██╔══██║╚════██║██╔══╝
   ██████╔╝   ██║      ██║   ███████╗██████╔╝██║  ██║███████║███████╗
   ╚═════╝    ╚═╝      ╚═╝   ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝
   
   Version 3.1.0 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 the workspace.

   

4. Follow the Quikstart guide on the bottom to click around or dismiss it by now. You can click your avatar on top right and click Quickstart on the dropdown menu to reopen it later.

   

Step 2 - Create a Schema Change#

1. Click Select Project on the top left, and choose Sample Project.

2. Check hr_test and click Edit Schema.

3. Via Schema Editor, add a new column to table employee:

   • Name: type
   • Type: text
   • Default: contract
   • Not Null: checked Click Preview issue.

4. You'll be redirected to an issue preview, click Create, an issue will be created automatically. After automatic checks, the issue will be in Done state which means the schema change has been applied to Test environment.

5. Click View change on the issue, or click Change History on the left sidebar and choose. You'll see the schema change diff.

Step 3 - Create a Branch#

1. Within project Sample Project, click Branches on the left sidebar, and click + New Branch. Give it a Name, and choose Baseline version, Prod and hr_prod as Source. Click Create.

   

2. You'll be redirected to the branch page, click Edit, and add a new column to table employee:

   • Name: nickname
   • Type: text
   • Default: empty string
   • Not Null: checked Click Save.

Step 4 - Create a Changelist#

1. Within the project Sample Project, click Changelists on the left sidebar, and click + New Changelist. Give it a Name, and click Add. A changelist will be created.

2. Within the changelist, click + to add changes.

   

3. There're three types of change sources: Change History, Branch and Raw SQL.

   

4. You have already prepared two in the previous steps. Let's add them to the list along with another of raw SQL.

   ALTER TABLE "public"."employee"
   ADD COLUMN "city" text NOT NULL DEFAULT '';

   Reorder them like this.

   

5. After clicking Apply to databases, choose hr_test and click Next. You'll be redirected to the issue page. These changes are listed as tasks, 1 per each change source and ordered accordingly. Click Create to apply them to Prod environment. These tasks will be executed in order. If any of them fails, the rest will be blocked.

   

Summary#

Now that you've learned how to effectively manage database schema changes using Bytebase Changelist, you can leverage this along with Bytebase's other features to streamline your database development process.