Skip to main content

Database Branches

PBS Knowledge uses TerminusDB, which supports Git-like branching for data versioning and testing.

Overview​

What Are Branches?​

Database branches allow:

  • Creating snapshots of data
  • Testing changes without affecting production
  • Rolling back to previous states
  • Parallel development of features

Branch Structure​

main (production)
├── test (testing environment)
├── feature-x (feature development)
└── backup-2024-01-15 (point-in-time backup)

Current Setup​

Main Branch​

The main branch:

  • Contains production data
  • Is used by all regular operations
  • Should never be deleted
  • Changes tracked automatically

Other Branches​

Additional branches may exist for:

  • Testing new features
  • Development environments
  • Point-in-time backups
  • Data migration staging

Working with Branches​

Viewing Branches​

  1. Go to Admin → System → Database
  2. See all branches
  3. View branch status
  4. Check current active branch

Creating a Branch​

caution

Branch creation requires careful consideration of data size and system resources.

  1. Go to Admin → Database → Branches
  2. Click Create Branch
  3. Enter:
    • Branch name
    • Source branch (usually main)
    • Description
  4. Create branch

Switching Branches​

For testing or development:

  1. Set TERMINUSDB_BRANCH environment variable
  2. Restart the application
  3. Application uses specified branch
warning

Never switch production to a non-main branch without careful planning.

Branch Operations​

Merge​

Merge changes from one branch to another:

  1. Select source branch
  2. Select target branch
  3. Preview changes
  4. Resolve conflicts if any
  5. Execute merge

Diff​

Compare branches:

  1. Select two branches
  2. View differences
  3. See added/modified/deleted documents
  4. Export diff report

Delete​

Remove a branch:

  1. Select branch to delete
  2. Confirm deletion
  3. Branch and all data are removed
danger

Deleted branches cannot be recovered. Always ensure data is backed up or merged before deletion.

Use Cases​

Testing Schema Changes​

Before applying schema changes:

  1. Create test branch from main
  2. Apply schema changes to test branch
  3. Validate changes work correctly
  4. Merge to main if successful
  5. Delete test branch

Data Migration​

For major data migrations:

  1. Create migration branch
  2. Run migration scripts
  3. Validate data integrity
  4. Switch production to new branch
  5. Keep old branch as backup

Development Environment​

For development:

  1. Create dev branch periodically
  2. Developers work against dev branch
  3. Test changes safely
  4. Never affects production

Backup Integration​

Branch Backups​

Branches can serve as backups:

  • Create dated branch (e.g., backup-2024-01-15)
  • Provides point-in-time snapshot
  • Can restore by merging back
  • More flexible than file backups

Automated Backups​

Configure automatic branch creation:

  1. Set backup schedule
  2. Define retention policy
  3. Old backup branches auto-deleted
  4. Most recent backups preserved

Best Practices​

Branch Naming​

Use clear, consistent naming:

  • test-{feature} for testing
  • backup-{date} for backups
  • dev-{username} for development
  • Avoid special characters

Branch Lifecycle​

  1. Create with clear purpose
  2. Document the branch
  3. Delete when no longer needed
  4. Don't let branches accumulate

Data Integrity​

  • Always test merges carefully
  • Back up before major operations
  • Validate after branch operations
  • Monitor disk usage

Troubleshooting​

Branch Creation Failed​

  1. Check available disk space
  2. Verify user permissions
  3. Check database connectivity
  4. Review error logs

Merge Conflicts​

  1. Review conflicting documents
  2. Decide which version to keep
  3. Manually resolve if needed
  4. Document resolution decisions

Performance Issues​

If branches cause slowdowns:

  1. Limit number of active branches
  2. Delete unused branches
  3. Monitor database size
  4. Consider compaction

Limitations​

Current Limitations​

In TerminusDB v11.2:

  • Branch creation can be slow for large databases
  • Some operations require exclusive access
  • Merge conflict resolution is limited

Recommendations​

  • Keep branch count low
  • Use branches for specific purposes
  • Prefer main branch for normal operations
  • Test branch operations in development first