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.
After PR/MR approval and merge, your CI/CD pipeline triggers Bytebase to create a release and deploy the migrations.
How Releases Work
A Release is an immutable package containing all your SQL migration files:
- Linked to VCS commit for full traceability
- Files validated and stored with SHA256 checksums
- Can be deployed to multiple environments
- Supports progressive rollout strategies
Inside Bytebase, the release triggers:
- Plan Generation - Defines target databases and rollout strategy
- Rollout Execution - Creates tasks for each database
- Revision Tracking - Records applied migrations to prevent duplicates
CI/CD Integration Examples
GitHub Actions
GitLab CI
Azure DevOps
Bitbucket Pipelines
# .github/workflows/release.yml
name: Database Release
on:
push:
branches: [main]
paths:
- 'migrations/**'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Create Bytebase Release
uses: bytebase/sql-review-action@v1
with:
command: rollout
bytebase-url: ${{ secrets.BYTEBASE_URL }}
bytebase-token: ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_TOKEN }}
file-pattern: 'migrations/**/*.sql'
project: projects/my-project
targets: instances/prod/databases/mydb
# .gitlab-ci.yml
rollout:
image: bytebase/bytebase-action:latest
stage: deploy
only:
- main
script:
- |
bytebase-action rollout \
--url $BYTEBASE_URL \
--service-account $BYTEBASE_SERVICE_ACCOUNT \
--service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
--file-pattern "migrations/**/*.sql" \
--project projects/my-project \
--targets instances/prod/databases/mydb
# azure-pipelines.yml
trigger:
branches:
include:
- main
paths:
include:
- migrations/**
jobs:
- job: Release
pool:
vmImage: 'ubuntu-latest'
steps:
- task: Docker@2
inputs:
command: run
arguments: >
-e BYTEBASE_URL=$(BYTEBASE_URL)
-e BYTEBASE_SERVICE_ACCOUNT=$(BYTEBASE_SERVICE_ACCOUNT)
-e BYTEBASE_SERVICE_ACCOUNT_SECRET=$(BYTEBASE_SERVICE_ACCOUNT_SECRET)
-v $(System.DefaultWorkingDirectory):/workspace
bytebase/bytebase-action
rollout
--file-pattern "/workspace/migrations/**/*.sql"
--project projects/my-project
--targets instances/prod/databases/mydb
# bitbucket-pipelines.yml
pipelines:
branches:
main:
- step:
name: Database Release
image: bytebase/bytebase-action:latest
deployment: production
script:
- |
bytebase-action rollout \
--url $BYTEBASE_URL \
--service-account $BYTEBASE_SERVICE_ACCOUNT \
--service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
--file-pattern "migrations/**/*.sql" \
--project projects/my-project \
--targets instances/prod/databases/mydb
Deployment Strategies
Progressive rollout across environments:
# Deploy to dev, then staging, then production
targets: >
instances/dev/databases/mydb,
instances/staging/databases/mydb,
instances/prod/databases/mydb
# Deploy to entire production fleet
targets: projects/my-project/databaseGroups/production-fleet
Database Groups
Manage database fleets with groups
Idempotency Guarantee
Bytebase tracks which migration versions have been applied to each database via the revision system. When creating a release:
- Check revisions - Query which versions already exist
- Skip applied - Migrations with matching versions are skipped
- Execute new - Only unapplied versions are executed
- Record success - Create revision only on successful completion
This ensures:
- ✅ Safe to run the same release multiple times
- ✅ Migrations never double-execute
- ✅ Environment parity (dev migrations auto-skip in prod)
Next Steps
Limitations
Understand constraints and considerations
Best Practices
Production-ready workflow patterns
