Skip to main content

​
Goal

GitOps for database CI/CD brings the same rigor and automation used in application development to database schema management. Database schema changes are equivalent to API changes in microservices - they define contracts between services, and misalignment can break production systems. By treating databases as dependencies that require versioning, compatibility management, and progressive rollout strategies, schema changes gain the same safety and predictability as application code.

​
Why Database Schema Changes Matter

Database schema changes are fundamentally similar to API changes:
  • They define contracts between services
  • Breaking changes can cause application failures
  • They require versioning and compatibility considerations
  • They benefit from progressive rollout and feature flagging
Bytebase enables database-as-code workflows, allowing you to manage database changes through your version control system (VCS) with the same process and confidence as application code.

​
Core Capabilities

​
Database-as-Code Workflow

  • Unified CI/CD Pipeline - Integrate database changes seamlessly into your existing CI/CD workflows
  • Version Control Integration - Manage schema changes alongside application code in your VCS
  • Automated Change Detection - Intelligently detect and apply only necessary changes, ensuring idempotency
  • Progressive Deployment - Roll out changes across environments (development → staging → production) with configurable automation and approval gates

​
Enterprise-Grade Safety

  • SQL Review and Validation - Automatic policy enforcement during pull requests
  • Rollback Capabilities - Support for safe schema rollbacks when needed
  • Multi-Region Support - Deploy to isolated regional databases with separate or unified Bytebase deployments
  • Batch Operations - Apply changes across multiple databases consistently

​
GitOps Workflow

Bytebase GitOps follows a streamlined 3-stage pipeline: 
Develop → Review (PR/MR) → Release (Bytebase)

​
1. Develop

Developers create SQL files in feature branches following your team’s Git workflow (GitHub Flow, GitLab Flow, trunk-based, etc.). What happens:
  • Write SQL migration or schema files
  • Follow naming conventions for proper versioning
  • Test changes locally when possible
  • Commit to version control

​
2. Review (Pull Request / Merge Request)

When developers open a pull/merge request, automated validation ensures changes meet your organization’s standards. What happens:
  • Automated SQL Review - Validates syntax and enforces policies
  • Risk Assessment - Identifies high-risk operations
  • Schema Compatibility - Checks for breaking changes
  • Team Review - Human review of schema changes alongside code

​
3. Release (Bytebase)

After PR/MR approval and merge, Bytebase orchestrates the deployment. This single stage encompasses Plan → Rollout → Revision tracking, all managed within Bytebase. What happens in Bytebase:
  1. Release Creation - Immutable package of SQL files linked to VCS commit
  2. Plan Generation - Defines deployment strategy and target databases
  3. Rollout Execution - Creates and executes tasks across environments
  4. Revision Tracking - Records applied migrations to prevent duplicates
The Release stage in Bytebase involves several coordinated steps:
  • Plan: Defines which databases to target and rollout strategy
  • Rollout: Executes the plan, creating stages for progressive deployment
  • Revision: Tracks which migrations have been applied to each database
For detailed information about these components, see:
  • Plan creation and targeting strategies
  • Rollout execution and approval workflows
  • Revision-based idempotency
These topics are covered in detail within each workflow documentation.
Key Principle: Bytebase automatically detects previously applied changes by checking revision history and skips them, ensuring safe re-deployment and idempotent operations across all environments.

​
Two Workflow Approaches

Bytebase supports two complementary approaches for managing database schema changes. Choose the one that fits your team’s needs, or use both for different scenarios.

​
Migration-Based Workflow

The imperative approach where you write incremental change scripts that describe how to modify the schema. 
-- migrations/001__create_users.sql
CREATE TABLE users (id INT PRIMARY KEY, name TEXT);

-- migrations/002__add_email.sql
ALTER TABLE users ADD COLUMN email TEXT;
Best for:
  • Teams familiar with traditional database migration tools
  • Complex changes requiring specific execution order
  • Data migrations (INSERT, UPDATE, DELETE operations)
  • All supported databases (MySQL, PostgreSQL, SQL Server, etc.)
  • Situations requiring fine-grained control over each change
How it works: Each migration file contains explicit DDL/DML statements. Files execute sequentially based on version numbers. Bytebase tracks which versions have been applied to prevent re-execution.

Migration-Based Workflow Guide

Complete guide to migration-based approach with examples and best practices

​
State-Based Workflow (SDL)

The declarative approach where you define the desired end-state of your database schema, and Bytebase automatically generates the migration DDL. 
-- schema/public.sql (complete desired state)
CREATE TABLE public.users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT
);
Best for:
  • Teams adopting infrastructure-as-code principles
  • Pure schema changes (DDL only, no data operations)
  • Simplified Git diffs showing schema evolution
  • PostgreSQL databases (currently)
  • Reducing complexity around migration ordering
How it works: You maintain the complete schema definition. Bytebase compares your desired state with the current database state and automatically generates the necessary ALTER/DROP statements to reach the desired state.

State-Based Workflow Guide

Complete guide to state-based (SDL) approach with validation rules and examples

​
Choosing Between Workflows

AspectMigration-BasedState-Based (SDL)
ApproachImperative (how to change)Declarative (desired end state)
FilesMultiple migration scriptsSingle schema definition per module
Git HistoryShows individual changesShows current state + diffs
OperationsDDL + DMLDDL only
Data Changes✅ Supported❌ Not supported
Database SupportAll databasesPostgreSQL only (currently)
Learning CurveFamiliar to DBAsFamiliar to DevOps/IaC users
ControlExplicit control over each stepAutomatic diff generation
RollbackWrite reverse migrationDefine previous state
Can I use both? Yes! You can use state-based workflow for schema structure and migration-based workflow for data operations in the same project.

​
Next Steps

Migration-Based Workflow

Traditional approach with incremental changes

State-Based Workflow (SDL)

Modern declarative schema management

Installation

Set up VCS integration and runners

Best Practices

Production-ready workflow patterns