Bytebase Cheat Sheet

Overview

Bytebase is a database DevOps platform that provides a web-based interface for managing database schema changes, access control, data masking, and SQL reviews. It brings the same review and approval workflows used in code deployments to database changes, enabling teams to track, review, and safely deploy schema modifications across development, staging, and production environments.

Bytebase supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, TiDB, ClickHouse, MongoDB, Redis, Snowflake, and other databases. It features an integrated SQL editor, automatic schema drift detection, GitOps integration, custom approval workflows, and a SQL review policy engine that catches risky changes before they reach production.

Installation

Docker (Recommended)

# Quick start with Docker
docker run --init -d \
  --name bytebase \
  --publish 8080:8080 \
  --volume bytebase-data:/var/opt/bytebase \
  bytebase/bytebase:latest

# With external PostgreSQL metadata store
docker run --init -d \
  --name bytebase \
  --publish 8080:8080 \
  --volume bytebase-data:/var/opt/bytebase \
  -e PG_URL="postgresql://user:password@host:5432/bytebase" \
  bytebase/bytebase:latest

# Access at http://localhost:8080

Docker Compose

version: "3"
services:
  bytebase:
    image: bytebase/bytebase:latest
    init: true
    ports:
      - "8080:8080"
    volumes:
      - bytebase-data:/var/opt/bytebase
    environment:
      PG_URL: "postgresql://bytebase:password@postgres:5432/bytebase"
    depends_on:
      - postgres
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: bytebase
      POSTGRES_USER: bytebase
      POSTGRES_PASSWORD: password
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  bytebase-data:
  pgdata:

Kubernetes

# Helm chart installation
helm repo add bytebase https://bytebase.github.io/bytebase
helm repo update
helm install bytebase bytebase/bytebase \
  --set "bytebase.option.port"=8080 \
  --set "bytebase.option.pg"="postgresql://user:pass@host:5432/bytebase"

Core Concepts

Key Terminology

Concept	Description
Project	Logical grouping of databases and team members
Environment	Deployment stage (Dev, Staging, Production)
Instance	A database server connection
Database	A specific database on an instance
Issue	A change request with review workflow
Sheet	Saved SQL statements
SQL Review	Automated policy checks on SQL changes
Changelist	Ordered set of changes to deploy

Workflow Steps

1. Create an Issue (schema change request)
2. Write the SQL migration
3. SQL Review engine checks for policy violations
4. Designated reviewers approve the change
5. Change is deployed to target environment
6. Bytebase records the change in history
7. Schema drift detection monitors for out-of-band changes

Schema Change Management

Creating a Change Issue

# Via Web UI:
1. Navigate to your project
2. Click "New Issue"
3. Select change type:
   - Schema Change (DDL)
   - Data Change (DML)
   - Database Creation
4. Select target database(s)
5. Write or paste the SQL
6. Submit for review

# Multi-environment deployment:
1. Create issue targeting multiple environments
2. SQL is rolled out sequentially: Dev → Staging → Production
3. Each stage requires approval before proceeding

SQL Examples

-- Schema change: Add a table
CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id),
    total DECIMAL(10,2) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);

-- Schema change: Alter a table
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
ALTER TABLE users ADD COLUMN last_login TIMESTAMP;

-- Data change: Seed data
INSERT INTO roles (name, description) VALUES
  ('admin', 'Full system access'),
  ('editor', 'Content management'),
  ('viewer', 'Read-only access');

Configuration

Environment Setup

# Create environments in Settings > Environments:
1. Development — No approval required, auto-rollout
2. Staging — Requires 1 reviewer approval
3. Production — Requires 2 reviewer approvals, manual rollout

# Environment tiers:
- Development: Fast iteration, minimal restrictions
- Staging: Pre-production validation, review required
- Production: Strict controls, full approval workflow

Database Instance Configuration

# Add a database instance:
1. Go to Instances
2. Click "Add Instance"
3. Configure:
   - Instance name
   - Database engine (PostgreSQL, MySQL, etc.)
   - Host and port
   - Authentication credentials
   - Environment assignment
   - SSL/TLS settings

SQL Review Policies

# Configure in Settings > SQL Review

Common rules:
- Require table naming convention (snake_case)
- Require column naming convention
- Disallow DROP TABLE without IF EXISTS
- Require index for foreign keys
- Limit column count per table
- Require NOT NULL for new columns
- Disallow SELECT * in production
- Require WHERE clause in UPDATE/DELETE
- Limit transaction size

GitOps Integration

# Connect with GitHub/GitLab:
1. Settings > GitOps
2. Connect your VCS provider
3. Configure repository mapping:
   - Repository: org/repo
   - Branch: main
   - Directory: db/migrations/
4. Bytebase watches for new migration files
5. Creates issues automatically from commits

Advanced Usage

Custom Approval Workflows

# Configure in Settings > Custom Approval

Example production workflow:
1. SQL Review (automated) — must pass all rules
2. DBA Review — database team member approves
3. Tech Lead Review — engineering lead approves
4. Deploy — manual trigger required

# Risk-based routing:
- Low risk (add column): 1 approval
- Medium risk (alter column): 2 approvals
- High risk (drop table): 3 approvals + DBA

Data Masking

# Configure data masking policies:
1. Settings > Data Masking
2. Define sensitive columns:
   - users.email → Partial mask (a***@example.com)
   - users.ssn → Full mask (***-**-****)
   - orders.total → No mask for admin role
3. Masking applies in SQL Editor queries
4. Different roles see different masking levels

SQL Editor

# Built-in SQL editor features:
- Execute queries against any connected database
- Auto-complete for tables, columns, functions
- Query history and saved sheets
- Result export (CSV, JSON)
- Admin mode for DDL operations
- Read-only mode for non-admin users
- Data masking applied automatically

API Integration

# Bytebase API (v1)
# List projects
curl "http://localhost:8080/v1/projects" \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN"

# Create an issue
curl -X POST "http://localhost:8080/v1/projects/my-project/issues" \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add phone column to users",
    "type": "DATABASE_CHANGE",
    "assignee": "users/dba@example.com"
  }'

# Get database schema
curl "http://localhost:8080/v1/instances/my-instance/databases/mydb/schema" \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN"

Schema Drift Detection

# Bytebase automatically detects out-of-band schema changes:
1. Periodically compares actual schema vs. recorded state
2. Alerts when drift is detected
3. Shows diff of unexpected changes
4. Options: accept drift or rollback

# Configure in instance settings:
- Check interval: 1 hour (default)
- Notification: Email or webhook
- Auto-resolve: Mark as acknowledged

Troubleshooting

Issue	Solution
Cannot connect to database instance	Verify host, port, credentials; check firewall and network rules
SQL Review false positives	Customize review rules in Settings; add exceptions for specific patterns
Migration stuck in pending	Check approval requirements; verify all reviewers have approved
Schema drift detected	Review diff in Bytebase; decide to accept or rollback manual changes
GitOps not triggering	Verify webhook configuration; check branch and directory mapping
Slow schema sync	Reduce sync frequency; optimize database connection pooling
Data masking not applying	Verify masking policy covers the column; check user role assignments
Docker container crashes	Check logs: docker logs bytebase; ensure sufficient memory allocation
Rollback needed	Create a new issue with reverse SQL; Bytebase tracks the change chain