Skip to main content

Database Branching

Learn how to create instant database branches using ZFS snapshots and clones.

Overview​

Database branching allows you to create instant copies of your databases for testing, development, and experimentation without the time and space overhead of traditional database dumps.

How It Works​

StagDB uses ZFS technology to provide:

  • Snapshots: Point-in-time captures of database state
  • Clones: Writable copies that share storage with the original
  • Space Efficiency: Only changes are stored, not full copies

Creating Branches​

From Existing Database​

# Create a branch from running database
curl -X POST https://api.stagdb.com/v1/databases/main-db/branches \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature-branch",
    "description": "Testing new feature"
  }'

From Snapshot​

# Create branch from specific snapshot
curl -X POST https://api.stagdb.com/v1/snapshots/snap-12345/branches \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hotfix-branch"
  }'

Snapshots​

Creating Snapshots​

# Create snapshot
curl -X POST https://api.stagdb.com/v1/databases/main-db/snapshots \
  -H "Content-Type: application/json" \
  -d '{
    "name": "before-migration",
    "description": "Snapshot before schema migration"
  }'

Automatic Snapshots​

  • Scheduled snapshots (hourly, daily, weekly)
  • Event-triggered snapshots (before migrations, deployments)
  • Retention policies for cleanup

Managing Snapshots​

# List snapshots
curl https://api.stagdb.com/v1/databases/main-db/snapshots

# Delete snapshot
curl -X DELETE https://api.stagdb.com/v1/snapshots/snap-12345

Branch Operations​

Listing Branches​

# List all branches for a database
curl https://api.stagdb.com/v1/databases/main-db/branches

Merging Changes​

While you can't merge database branches like code, you can:

  • Export schema changes as SQL
  • Apply tested changes to parent database
  • Promote branch to become the main database

Cleaning Up Branches​

# Delete branch
curl -X DELETE https://api.stagdb.com/v1/databases/feature-branch

# Delete all branches for database
curl -X DELETE https://api.stagdb.com/v1/databases/main-db/branches

Use Cases​

Feature Development​

# 1. Create branch for feature work
curl -X POST https://api.stagdb.com/v1/databases/main-db/branches \
  -d '{"name": "user-authentication"}'

# 2. Work on feature with isolated data
# ... develop and test ...

# 3. Clean up when done
curl -X DELETE https://api.stagdb.com/v1/databases/user-authentication

Testing Migrations​

# 1. Create snapshot before migration
curl -X POST https://api.stagdb.com/v1/databases/prod-db/snapshots \
  -d '{"name": "pre-migration-v2.1"}'

# 2. Create branch for testing
curl -X POST https://api.stagdb.com/v1/snapshots/pre-migration-v2.1/branches \
  -d '{"name": "migration-test"}'

# 3. Test migration on branch
# ... run migration scripts ...

# 4. If successful, apply to main; if not, delete branch

QA Testing​

# Create fresh branch for each test run
for test in integration unit e2e; do
  curl -X POST https://api.stagdb.com/v1/databases/main-db/branches \
    -d "{\"name\": \"test-${test}\"}"
done

Performance Characteristics​

Space Efficiency​

  • Initial branch: Near-zero storage overhead
  • As data changes: Only deltas are stored
  • Shared blocks: Common data referenced once

Time Efficiency​

  • Branch creation: Seconds (regardless of database size)
  • Snapshot creation: Sub-second for most databases
  • No data copying required

Limitations​

  • ZFS pool size limits total storage
  • Many branches can impact I/O performance
  • Snapshot deletion can be slow for large databases

Best Practices​

Naming Conventions​

  • Use descriptive branch names: feature-user-auth
  • Include ticket numbers: bug-1234-fix
  • Add dates for temporary branches: test-2024-01-15

Lifecycle Management​

  • Delete branches when no longer needed
  • Set up automatic cleanup policies
  • Monitor storage usage

Testing Workflows​

  • Create branch before testing
  • Test in isolation
  • Clean up after testing
  • Document test procedures

Monitoring and Troubleshooting​

Storage Usage​

# Check ZFS pool usage
zpool list

# Check dataset usage
zfs list -t all

Performance Monitoring​

  • Monitor I/O patterns
  • Track snapshot creation time
  • Watch for storage fragmentation

Common Issues​

  • Slow snapshots: Check I/O load and ZFS settings
  • Storage full: Clean up old snapshots and branches
  • Performance degradation: Limit number of active branches