> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/tutorials/gitops-github-workflow), [GitLab CI](/tutorials/gitops-gitlab-workflow), [Azure DevOps](/tutorials/gitops-azure-devops-workflow), or [Bitbucket](/tutorials/gitops-bitbucket-workflow) tutorial.

## Before you start

Prepare the employee sample using the [UI tutorial setup](/tutorials/first-schema-change#step-1-setup-bytebase). 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](/gitops/installation) and configure authentication through CI secrets or [workload identity](/administration/workload-identity/github-actions). 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](/tutorials/first-schema-change). 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`:

```sql theme={null}
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:

```bash theme={null}
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](/gitops/migration-based-workflow/sql-review-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:

```bash theme={null}
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](/concepts/release), a [Plan](/concepts/plan) referencing it, and a [Rollout](/concepts/rollout). It runs unfinished stages through the selected Test stage and waits for them. Retain the output and Plan link for verification or recovery.

<Warning>
  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.
</Warning>

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

```sql theme={null}
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](/gitops/migration-based-workflow/release) for pipeline examples.

## Try the interactive demo

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

<iframe width="100%" height="580" src="https://www.bytebase.com/demo/gitops/demo" title="Bytebase GitOps database change walkthrough" frameborder="0" style={{ marginLeft: '-2rem' }} />

[Open the demo in a full page](https://www.bytebase.com/demo/gitops/).