Bytebase offers a database-as-code workflow, enabling you to manage database changes directly through your version control system (VCS). Bytebase GitOps workflow is built upon the Bytebase API. It provides the ultimate flexibility to customize the GitOps workflow to integrate with your CI/CD pipeline.

​
Capabilities

Bytebase GitOps integration provides two core capabilities:

​
Versioned Database Migrations

  • Database-as-code workflow - Manage database changes through your VCS just like application code
  • Schema and data changes - Support for both DDL (CREATE/ALTER/DROP tables, indexes) and DML (INSERT/UPDATE/DELETE) operations
  • Change detection - Automatically detects and skips already applied migrations, ensuring idempotency
  • Progressive deployments - Automated rollout across environments (test → staging → production)
  • Multi-database support - Apply changes across multiple databases with batch operations

​
SQL Review

  • Automated validation - Automatically check SQL files against configurable review policies
  • Quality and compliance checks - Validate for performance issues, security concerns, and best practices
  • PR integration - Review results posted directly as pull request comments
  • Merge protection - Block merges when critical issues are detected
  • Database-specific rules - Tailored validation for different database engines

​
GitOps Workflow

​
1. Development Phase

Developers create SQL migration files in their feature branches:
  • Schema changes (DDL): 202501150900_add_user_table.sql
  • Data changes (DML): 202501150901_seed_initial_data_dml.sql
Filenames must conform to the versioning format.

​
2. Review Phase (Pull Request)

  • SQL review runs automatically on the PR
  • Validates changes against configured policies
  • No release created yet - only validation

​
3. Release Creation (Merge)

When the PR is merged to main:
  • GitOps integration automatically creates a new release
  • All SQL files from the merge are packaged together
  • Release is assigned a unique identifier
  • Linked to the merge commit for traceability

​
4. Progressive Deployment

The release follows your configured deployment pipeline:
  • Test Environment: Automatic deployment after creation
  • Staging Environment: May require manual approval
  • Production Environment: Typically requires explicit approval
  • Each deployment is tracked with timing and status
Important: When deploying a release, Bytebase automatically detects which migrations have already been applied to the target database and skips them. This ensures safe re-deployment and allows the same release to be deployed multiple times without errors.

​
Requirements

​
Filename Requirements

To ensure proper version control and execution, your SQL migration filenames must follow a specific structure. Each filename consists of three main parts: a Version, a Description, and an optional Change Type Suffix. <Version>_<Description>_<Suffix>.sql

​
Versioning Format

Bytebase supports both semantic versioning and simple timestamp-based versions. The version number is crucial for ordering migrations correctly. The version must begin with a number. A v or V prefix is optional. Valid Version Examples:
  • 202501150900_add_user_table.sql
  • v1.2.3_description.sql
  • V2_add_users_table.sql
  • 1.0_initial_schema.sql

​
Change Type Suffixes

You can add a suffix to the filename to specify the change type. If the suffix is omitted, the file will be treated as the default DDL type. The suffix is added to the end of the filename, just before the .sql extension.
  • DDL (Default)
    • Used for standard schema changes (Data Definition Language). This is the default type used when no suffix is present.
    • Example: v1.0_create_table.sql
  • DML
    • Used for data manipulations (Data Manipulation Language).
    • Add the _dml suffix.
    • Example: v1.0_insert_data_dml.sql
  • Ghost
    • Used for schema changes performed using the gh-ost tool.
    • Add the _ghost suffix.
    • Example: v1.0_alter_table_ghost.sql

​
GitHub Actions

Tutorial: Database GitOps with GitHub Actions
To reach your self-hosted Bytebase from GitHub Actions, you can choose either options:
  1. Tunnel GitHub Actions using Cloudflare Zero Trust with Cloudflare Warp GitHub Actions.
  2. Use self-hosted runners.
Bytebase provides pre-built GitHub Actions to ease the GitHub integration.

​
Azure DevOps Pipeline

Tutorial: Database GitOps with Azure DevOps Pipeline

​
GitLab CI

Tutorial: Database GitOps with GitLab CI
If you’re using self-hosted GitLab in an internal network:
  1. You’ll need to manually load the bytebase/bytebase-action image into your internal Docker registry.
  2. Set the clone_url in GitLab Runner to avoid redirection to external addresses.

​
Bitbucket Pipelines

Tutorial: Database GitOps with Bitbucket Pipelines

​
API

If the pre-built GitHub Actions do not meet your needs or you want to integrate with other VCSs, you can use the Bytebase API to build your own GitOps workflow.