---
title: "Database Branching: Git for Your Data"
description: "How zero-cost copy-on-write branching at the storage layer changes the way teams develop, test, and deploy schema changes."
date: 2025-12-20
updated: 2025-12-20
tag: "Feature"
canonical: https://www.heliosdb.com/blog/database-branching-git-for-your-data.html
---

# Database Branching: Git for Your Data

What if you could branch your database like you branch your code? Create an isolated copy in milliseconds, run migrations, test destructive operations, then merge or discard — all without touching production data. That's exactly what HeliosDB's database branching does, and today we're diving into how it works at the storage layer.

## Why Database Branching?

Every developer has experienced the pain of testing schema migrations against production data. You write the migration, test it against a small dev dataset, cross your fingers, and deploy. If it fails or performs badly, you roll back and try again. This cycle is slow, risky, and fundamentally broken.

Database branching solves this by bringing the Git workflow to your data. Create a branch, run your migration, validate the results with real data volumes, measure performance, and only then merge to production. The branch is a true copy-on-write snapshot — it takes milliseconds to create regardless of database size, and it only consumes storage for the data that actually changes.

## Copy-on-Write Architecture

HeliosDB implements branching at the storage layer using a copy-on-write (COW) mechanism built on our LSM-tree engine. When you create a branch, we don't copy any data. Instead, we create a new branch metadata entry that shares the same underlying SSTables:

```
-- Create a branch (instant, regardless of data size)
CREATE BRANCH staging FROM main;

-- Work on the branch
USE BRANCH staging;
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
UPDATE users SET phone = '555-0100' WHERE id = 1;

-- The 'main' branch is completely unaffected
USE BRANCH main;
SELECT * FROM users;  -- No 'phone' column here

-- Merge when ready
MERGE BRANCH staging INTO main;
```

## Branch Storage Model

Under the hood, each branch is identified by a globally unique `u64` branch ID with a timestamp-based snapshot ID. Branch data is stored with the prefix `bdata:` and branch metadata with `branch:meta:`. The branch registry lives at `branch:registry`.

```
Storage layout:
  branch:meta:{branch_id}       -- Branch metadata (name, parent, state, timestamp)
  branch:children:{branch_id}   -- Child branch tracking
  branch:registry                -- Global branch registry
  bdata:{branch_id}:{key}       -- Branch-specific data (COW writes)
  git:commit:{commit_id}        -- Git-like commit history
  git:ddl:{branch_id}           -- DDL change history per branch
```

When a write occurs on a branch, only the modified pages are written to the branch's data prefix. Reads first check the branch's data, then fall through to the parent branch, then to main. This layered approach means branches share unmodified data and only consume storage proportional to their changes.

## Branch States and Lifecycle

Branches follow a simple lifecycle with three states:

```
pub enum BranchState {
    Active,                                    // Writable, accepting changes
    Merged { into_branch: u64, timestamp: u64 },  // Merged into parent
    Dropped { at_timestamp: u64 },             // Dropped, pending cleanup
}
```

## Merge Strategies

When merging branches, conflicts can arise if the same key was modified on both branches. HeliosDB supports four merge strategies:

```
MERGE BRANCH staging INTO main USING STRATEGY auto;    -- Prefer source on conflict
MERGE BRANCH staging INTO main USING STRATEGY manual;  -- Fail on any conflict
MERGE BRANCH staging INTO main USING STRATEGY theirs;  -- Always prefer source
MERGE BRANCH staging INTO main USING STRATEGY ours;    -- Always prefer target
```

## Real-World Use Cases

**Schema Migration Testing:** Branch production, run your migration, validate queries, measure performance, merge or discard. No risk to production data.

**A/B Testing:** Create branches with different schema designs or data configurations. Route traffic to each branch and compare results. HeliosDB Nano has native support for branch-based A/B testing.

**Feature Development:** Each developer gets their own branch with full production data. Develop and test against real data volumes without coordinating access to shared staging environments.

**Data Recovery:** Branches combined with time-travel queries let you access any point in your database history. Made a mistake? Create a branch from the pre-mistake timestamp and recover the data.

## Branch Replication

For distributed deployments, HeliosDB Lite includes a branch replicator that synchronizes selected branches to remote servers:

```
Replication Architecture:
  LOCAL DATABASE                 REMOTE SERVER
  ├─ main                        ├─ analytics (synced)
  ├─ analytics ──────────────►   └─ reporting (synced)
  ├─ reporting ──────────────►
  └─ development (local only)
```

Sync state progresses through: NotConfigured → Connecting → InitialSync → Streaming. The replicator tracks lag as the difference between local and remote positions.

## Performance

Branch creation is constant-time — it takes the same milliseconds whether your database is 1 MB or 1 TB. The COW mechanism means you only pay storage costs for data that actually changes on the branch. In practice, a branch for schema migration testing typically consumes less than 1% of the original database size.