🐣Your First Database Schema Change in 5 Minutes with Bytebase
Tags: database, schema, postgressql
Published: 2024-01-18 06:42:04

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

## Step 1 - Run via Docker

1. Install and start [Docker](https://www.docker.com/).
2. Open Terminal to run the command:

  ```text
  docker run --init \
    --name bytebase \
    --publish 8080:8080 \
    --volume ~/.bytebase/data:/var/opt/bytebase \
    bytebase/bytebase:2.13.1
 ```


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

  ```text
██████╗ ██╗   ██╗████████╗███████╗██████╗  █████╗ ███████╗███████╗
██╔══██╗╚██╗ ██╔╝╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝
██████╔╝ ╚████╔╝    ██║   █████╗  ██████╔╝███████║███████╗█████╗
██╔══██╗  ╚██╔╝     ██║   ██╔══╝  ██╔══██╗██╔══██║╚════██║██╔══╝
██████╔╝   ██║      ██║   ███████╗██████╔╝██║  ██║███████║███████╗
╚═════╝    ╚═╝      ╚═╝   ╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝

  Version 2.13.1 has started on port 8080 🚀

  ```

   Now you have Bytebase running in Docker.

   ![dk-bb-running](https://www.bytebase.com/content/docs/tutorials/first-schema-change/dk-bb-running.webp)

3. Open Bytebase in [localhost:8080](http://localhost:8080/), fill in the fields and click **Create admin account**. You'll be redirected to the workspace.

   ![bb-register](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-register.webp)

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.

   ![bb-first-workspace](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-first-workspace.webp)

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

   ![bb-my-issues](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-my-issues.webp)

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.

   ![bb-issue-test](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-issue-test.webp)

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. SQL review is one of them.

   ![bb-issue-prod](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-issue-prod.webp)

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. You can click the **Settings** (gear) on the top right, and click **Security & Policy** > **SQL Review** to have a look.

   ![bb-sql-review-not-null](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-sql-review-not-null.webp)

## Step 3 - Roll out on Test Stage

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

   ![bb-test-rollout](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-test-rollout.webp)

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

   ![bb-issue-test-done](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-issue-test-done.webp)

   ![issue-snapshot-diff](https://www.bytebase.com/content/docs/tutorials/first-schema-change/issue-snapshot-diff.webp)

## 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. Check the **Rollout anyway**, and click **Rollout** on the confirmation dialog.

   ![bb-issue-prod-anyway](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-issue-prod-anyway.webp)

2. Another way is to edit the SQL. Click **Edit** on top of the SQL, and add the `NOT NULL`. It will look like this:

   ```sql
   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 and it will roll out automatically. The issue will become `Done` as well.
   
   ![bb-issue-done](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-issue-done.webp)
   
   You may ask why it's rolling out automatically, it's because for **Community Plan**, the rollout policy is automatic if the SQL review passes. You may go to **Environments** to check.

   ![bb-env-automatic](https://www.bytebase.com/content/docs/tutorials/first-schema-change/bb-env-automatic.webp)

## Next Step

Now you have successfully performed your first schema change in Bytebase. It's the core part of Bytebase. You can continue to dig deeper by following [Deploy Schema Migration with Rollout Policy](https://www.bytebase.com/docs/tutorials/deploy-schema-migration/).