Skip to main content
A Release is an immutable package of database change files saved in a Bytebase project. It records their SQL contents, migration versions where applicable, and optional source links such as a commit or pull request. A Plan references the Release to use those files for a change. For example, a Release can contain the migrations that add nickname and work-email columns to the sample employee table. The same Release can supply the files for deployment to Test and Prod, preserving the inputs across environments.

​
Release versus Plan

A Release answers which files to use. A Plan specifies the work and its targets and tracks the change through deployment. The Release has no deployment targets of its own and can be referenced by multiple Plans. A UI Plan can also use SQL directly, without a Release. Creating a Release saves the files. Execution happens through a Plan’s Rollout, where each target has its own task results.

​
What the files describe

A Release uses one of two change models:
  • Versioned migrations describe changes to execute in order, such as creating a table and then adding a column. Bytebase records applied versions separately for each database and skips versions already applied there.
  • Declarative schema definitions describe the desired schema. Bytebase compares them with each target’s schema to generate the required changes. Different starting schemas can produce different SQL.
See migration-based workflows and state-based workflows for file conventions, supported engines, and limitations.

​
Create a Release

An integration creates a Release through the API. In the documented GitOps workflow, CI checks the files during pull-request review; after merge, the deployment job uses bytebase-action rollout to create the Release, a Plan referencing it, and the Rollout. Release contents cannot be edited. Correct unapplied files in a new Release. If a migration has already run, add a new migration version to make the next change rather than editing the applied file.

​
Deploy the same files across environments

A Plan that targets both Test and Prod can deploy the Release to Test first, then continue to Prod. The promotion job reuses the same Plan and Release. One Plan references an immutable Release and targets both hr_test and hr_prod, with Test and Prod stages in its Rollout This is one way to organize promotion. A workflow can also use separate Plans referencing the same Release. When continuing an existing Plan with --plan, the command uses its recorded targets; it does not add Prod to a Test-only Plan. See GitOps release and promotion.

​
Inspect a Release

Open your project’s CI/CD → Releases and select a Release to inspect its files, versions, and source links. Follow the Plan link from the deployment job to see which targets used those files and their execution results. Active Releases appear in the normal list. Archived Releases are retained and can be restored. These states describe the Release’s availability, not whether it has been deployed. Follow the GitOps tutorial for a complete example, or GitOps troubleshooting to investigate a failed check or deployment job.