Change a Database with GitOps

Follow a sample migration from pull-request checks to deployment and verification.

Add a nickname column to the built-in employee table through Git and CI. This provider-neutral walkthrough explains the migration and resulting Bytebase resources. For a complete pipeline configuration, use the GitHub Actions, GitLab CI, Azure DevOps, or Bitbucket tutorial.

Before you start

Prepare the employee sample using the UI tutorial setup. In Cloud, create the sample from your project’s Instances → Connect instance → Use sample instance instead. The examples call the project HR and database hr_test; substitute your own names. Use a repository and CI runner that can reach Bytebase. A hosted runner cannot reach Bytebase through your laptop’s localhost.

Install a compatible action image and configure authentication through CI secrets or workload identity. The templates below run inside that image. Replace every angle-bracket placeholder with your deployment’s value; keep credentials in the CI secret store.

This is the same nickname change as First Schema Change in 5 Minutes. Use one workflow to apply it; if it already exists, inspect the completed change or use a fresh sample database.

1. Add the migration

Create migrations/V1_add_employee_nickname.sql:

ALTER TABLE public.employee
  ADD COLUMN IF NOT EXISTS nickname TEXT NOT NULL DEFAULT '';

Use the next unused version if your repository already has migrations. Open a pull request. Keep applied migrations unchanged; later changes belong in new files.

2. Check the pull request

Configure the review job to run:

bytebase-action check \
  --url "<bytebase_url>" \
  --project "projects/<project_id>" \
  --targets "<database_resource_name>" \
  --file-pattern "migrations/*.sql" \
  --check-release=FAIL_ON_ERROR \
  --output "bytebase-check.json"

Copy the database resource name from hr_test in Bytebase. A project instance uses projects/<project_id>/instances/<instance_id>/databases/<database_name>; a workspace instance uses instances/<instance_id>/databases/<database_name>. Cloud sample databases have generated names beginning with bb_sample_, rather than hr_test.

CI supplies BYTEBASE_ACCESS_TOKEN, or BYTEBASE_SERVICE_ACCOUNT and BYTEBASE_SERVICE_ACCOUNT_SECRET. Retain the output JSON even on failure. Fix errors and assess warnings before merging. FAIL_ON_WARNING also fails on warnings; the default SKIP reports findings without failing the job. See SQL Review in CI.

Require both SQL Review and repository review before merge. Release-based Plans use those gates rather than a Bytebase Issue or UI Plan checks.

3. Merge and deploy

After merge, the deployment job runs:

bytebase-action rollout \
  --url "<bytebase_url>" \
  --project "projects/<project_id>" \
  --targets "<database_resource_name>" \
  --file-pattern "migrations/*.sql" \
  --target-stage "environments/<test_environment_id>" \
  --output "bytebase-result.json"

This creates a Release, a Plan referencing it, and a Rollout. It runs unfinished stages through the selected Test stage and waits for them. Retain the output and Plan link for verification or recovery.

Confirm the logs show the intended stage. The command can exit successfully when no stages exist or the requested stage is missing. Without --target-stage, it prepares the Rollout and returns; automatic rollout policies may still start tasks independently.

4. Verify the change

Open the Plan link from CI and inspect the Test task for hr_test. Confirm execution succeeded, then open SQL Editor for that database and run:

SELECT emp_no, first_name, last_name, nickname
FROM public.employee
ORDER BY emp_no
LIMIT 5;

The new nickname column contains an empty string for each employee, as specified by DEFAULT ''.

The database’s Changelog records execution; Revision tracks applied migration versions. If deployment fails, inspect the existing Plan and failed task before retrying.

For Test-to-Prod promotion, include both databases when creating the Plan, then reuse its returned name with --plan. Continuing a Test-only Plan does not add Prod. See Release and promotion for pipeline examples.

Interactive demo

Follow a pull request through checks, release creation, and deployment, without any setup.