Your First Schema Change in 5 Minutes

Estimated: 5 mins

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.

  2. Open Terminal to run the command:

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

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

    β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•—   β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—  β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
    β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β•šβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•”β•β•šβ•β•β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•”β•β•β•β•β•
    β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β• β•šβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•    β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—  β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
    β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—  β•šβ–ˆβ–ˆβ•”β•     β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ•”β•β•β•  β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•‘β•šβ•β•β•β•β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•
    β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•   β–ˆβ–ˆβ•‘      β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘  β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
    β•šβ•β•β•β•β•β•    β•šβ•β•      β•šβ•β•   β•šβ•β•β•β•β•β•β•β•šβ•β•β•β•β•β• β•šβ•β•  β•šβ•β•β•šβ•β•β•β•β•β•β•β•šβ•β•β•β•β•β•β•
    
    Version 2.15.0 has started on port 8080 πŸš€

    Now you have Bytebase running in Docker.

    dk-bb-running

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

    bb-register

  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

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

  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

  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

  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

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

  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

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

    bb-issue-prod-anyway

  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:

    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

    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

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.

Edit this page on GitHub

Subscribe toΒ Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.