Tutorial: First Schema Change in 5 Minutes

 For a typical change workflow, a developer first submits the SQL statement for DBA to review. After review is approved, the SQL statement will then be applied to the corresponding database. For a single change, this step would normally be repeated for each environment (e.g. integration, staging, prod). There are 2 typical workflows employed by the team to deal with database schema changes (DDL) and data changes (DML). UI workflow and GitOps workflow (GitOps).

​
UI workflow

Classic SQL Review workflow where the developer submits a SQL review ticket directly from Bytebase and waits for the assigned DBA or peer developer to review. Bytebase applies the SQL change after review approved. Issue detail interface

​
GitOps Workflow

Aka Database-as-Code. Database migration scripts are stored in a git repository. To make schema changes, a developer would create a migration script and submit for review in the corresponding VCS such as GitLab. After the script is approved and merged into the configured branch, Bytebase will automatically kicks off the task to apply the new schema change. workflow-vcs

​
Core Concepts

​
Issue

Issue adds the collaboration such as approval, comment, and notification to the database change process. An issue is often created via the UI workflow. On the other hand, an issue may not be created via the GitOps workflow since the GitOps workflow may only need the rollout without further human intervention.

​
Release

A release is a deployable unit that encapsulates a set of SQL statements.

​
Rollout

To roll out the changes, Bytebase creates a multi-stage rollout pipeline from you project deployment config setting. The changes are pushed to databases stage by stage.

​
Revision

Revision records the versioned changes applied to a database. You can get a database from version A to version B by replaying the revisions between A and B. When applying a release to a database, the changes with a version present in the revision are skipped so that the same changes are not applied twice.

​
Changelog

Changelog records all changes applied to a database, whether they are versioned or not, successfully applied or not. This includes change database issues created on Bytebase UI or rollout via Bytebase APIs, but NOT changes from Bytebase SQL Editor or other external database tools. Changelog offers you insights into the database schema evolution.

​
Review Center

You can create a review-only ticket. Go to a particular project and click Review Center. review-center If there are review errors, then you won’t be able to create the rollout. review-center-error review-center-block-creation

​
Rollout Time

If you want to roll out changes during non-business hours, you can set a rollout time. rollout-time

​
Rollout Process

​
Execution Order

Database rollout is organized into stages. Each stage can contain multiple tasks. Each task contains one or more SQL statements to be executed. rollout-process-order Tasks run in the following order:
  • Tasks from the late stage must wait until all the tasks from the previous stage reach to the end state.
  • For tasks belong to the same stage:
    • Tasks changing the same database run sequentially. A failed task will not block the following task.
    • Tasks changing different databases run concurrently.

​
Task Detail

You can check the running/completed task details. rollout-detail-button The logs shows how Bytebase runs SQL statements. rollout-detail-log
If you initiate the change from Edit Schema (DDL), Bytebase will take the schema snapshot before and after the change.
The sessions view shows all active sessions (PostgreSQL only). rollout-detail-session

​
Migration Types

Bytebase records the migration history with the migration type information.

​
Schema Migration

Schema migration is the migration type for DDL statements.

​
Data Migration

Data migration is the migration type for DML statements.

​
Baseline Migration

Baseline migration instructs Bytebase to use the latest live schema as the source of truth. This is normally used when schema drift occurs and Bytebase needs to re-establish the baseline based on the latest live schema.