HeliosDB Database Branching: Lite vs Full Comparison

Version: 1.0 Updated: December 16, 2025 Purpose: Feature comparison for database branching between HeliosDB Lite and Full editions

Overview

HeliosDB Full is a superset of HeliosDB Lite. All branching features available in Lite work identically in Full, with Full providing additional enterprise and distributed capabilities.

┌─────────────────────────────────────────────────────────────────────────┐
│                    HeliosDB Branching Architecture                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────┐   ┌─────────────────────────────┐  │
│  │       HeliosDB Lite             │   │       HeliosDB Full         │  │
│  │   (Single-Node, Embedded)       │   │   (Distributed, Cloud)      │  │
│  ├─────────────────────────────────┤   ├─────────────────────────────┤  │
│  │ • Copy-on-write branches        │   │ • All Lite features         │  │
│  │ • Instant creation (<10ms)      │   │ • Multi-node distribution   │  │
│  │ • Hierarchical branching        │   │ • Storage/Compute separation│  │
│  │ • Data isolation                │   │ • Cross-region replication  │  │
│  │ • Time-travel (AS OF)           │   │ • Advanced conflict resolution│ │
│  │ • MVCC integration              │   │ • Delta SSTable compaction  │  │
│  │ • Local embeddings              │   │ • Branch-level permissions  │  │
│  └─────────────────────────────────┘   │ • Enterprise MV refresh     │  │
│                                        │ • GPU-accelerated merges    │  │
│                                        └─────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

REPL Command Comparison

Common Commands (Both Editions)

Command	Syntax	Description
`\branches`	`\branches [pattern]`	List all database branches
`\use`	`\use <branch>`	Switch to a specific branch
`\show branch`	`\show branch`	Show current branch info
`\snapshots`	`\snapshots [table]`	List time-travel snapshots

Branch Management Commands

Command	Lite	Full	Notes
`\branch info <name>`	Yes	Yes	Full shows storage_node, compute_endpoint
`\branch tree`	Yes	Yes	Full shows distributed topology
`\branch create`	Yes	Yes	Full supports `--at=SCN` syntax
`\branch delete`	Yes	Yes	Full supports `CASCADE` for child branches
`\branch merge`	Yes	Yes	Full has more conflict strategies
`\branch diff`	No	Yes	Full only: Compare branch data
`\branch stats`	No	Yes	Full only: Delta SSTables, page counts

Time-Travel Commands

Command	Lite	Full	Notes
`\scn`	Yes	Yes	Show current SCN
`\lsn`	Yes	Yes	Show current LSN
`\timeline`	Yes	Yes	Full shows distributed timeline
`\retention`	No	Yes	Full only: Retention policies
`\flashback`	No	Yes	Full only: Flashback table/database
`\row_history`	No	Yes	Full only: Row version history

Materialized View Commands (Full Only)

Command	Lite	Full	Description
`\dmv`	No	Yes	List materialized views
`\dmv staleness`	No	Yes	Show MV staleness
`\dmv refresh`	No	Yes	Trigger manual refresh
`\dmv deps`	No	Yes	Show MV dependencies
`\dmv config`	No	Yes	Show auto-refresh config

SQL Syntax Comparison

Branch Creation

Lite:

CREATE DATABASE BRANCH dev FROM main AS OF NOW;
CREATE DATABASE BRANCH feature FROM dev AS OF TIMESTAMP '2025-01-01 10:00:00';
CREATE DATABASE BRANCH snapshot FROM main AS OF TRANSACTION 12345;

Full (Additional Options):

-- All Lite syntax works, plus:
CREATE DATABASE BRANCH dev FROM main AS OF NOW
  WITH (storage_node = 'node-us-east-1', compute_endpoint = 'default');

-- SCN-based branching (Oracle compatibility)
CREATE DATABASE BRANCH branch_scn FROM main AS OF SCN 50000;

-- Distributed branch with replication factor
CREATE DATABASE BRANCH prod_backup FROM main AS OF NOW
  WITH (replication_factor = 3, regions = ['us-east-1', 'eu-west-1', 'ap-southeast-1']);

Branch Switching

Both Editions:

USE BRANCH dev;
USE DATABASE BRANCH staging;

-- Or via REPL
\use dev

Branch Merging

Lite:

MERGE DATABASE BRANCH dev INTO main;
MERGE DATABASE BRANCH dev INTO main WITH (conflict_resolution = 'branch_wins');

Full (Additional Strategies):

-- All Lite syntax works, plus:
MERGE DATABASE BRANCH dev INTO main WITH (
  conflict_resolution = 'three_way',
  auto_resolve_schema = true,
  preserve_timestamps = true
);

-- Dry-run merge (preview conflicts)
MERGE DATABASE BRANCH dev INTO main WITH (dry_run = true);

-- GPU-accelerated merge for large branches
MERGE DATABASE BRANCH analytics INTO main WITH (use_gpu = true);

Branch Deletion

Lite:

DROP DATABASE BRANCH dev;
DROP DATABASE BRANCH IF EXISTS old-feature;

Full (Additional Options):

-- All Lite syntax works, plus:
DROP DATABASE BRANCH dev CASCADE;  -- Delete children first
DROP DATABASE BRANCH dev WITH (archive = true);  -- Archive before delete

System Views Comparison

Common Views (Both Editions)

-- List branches
SELECT * FROM pg_database_branches();
-- Returns: branch_name, branch_id, parent_id, created_at, status

Full Edition Extended Views

-- Extended branch info (Full only)
SELECT * FROM heliosdb_branches;
-- Returns: name, state, parent_name, creation_lsn, current_lsn,
--          storage_node, compute_endpoint, created_at, depth

-- Branch statistics (Full only)
SELECT * FROM heliosdb_branch_stats WHERE branch_name = 'dev';
-- Returns: memtable_size, delta_sstable_count, delta_sstable_size,
--          page_count, total_writes, total_reads

-- Branch diff function (Full only)
SELECT * FROM heliosdb_branch_diff('dev', 'main');

-- Retention policies (Full only)
SELECT * FROM heliosdb_retention_policies;

-- Timeline view (Full only)
SELECT * FROM heliosdb_timeline ORDER BY lsn DESC LIMIT 50;

Architecture Differences

HeliosDB Lite

┌─────────────────────────────────────┐
│          Single Process             │
├─────────────────────────────────────┤
│  ┌─────────┐  ┌─────────────────┐  │
│  │  REPL   │  │  Branch Manager │  │
│  └────┬────┘  └────────┬────────┘  │
│       │                │            │
│  ┌────▼────────────────▼────────┐  │
│  │      Copy-on-Write Store     │  │
│  │   data:<branch_id>:<key>     │  │
│  └──────────────────────────────┘  │
│                │                    │
│  ┌─────────────▼─────────────────┐ │
│  │     Local Storage (RocksDB)   │ │
│  └───────────────────────────────┘ │
└─────────────────────────────────────┘

Key Characteristics:

Single-node, embedded database
In-process branch management
Local storage only
Ideal for development, testing, edge deployment
Branch creation: <10ms

HeliosDB Full

┌─────────────────────────────────────────────────────────────────────────┐
│                        Distributed Architecture                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                  │
│  │ Compute Node │  │ Compute Node │  │ Compute Node │                  │
│  │   (REPL)     │  │   (REPL)     │  │   (REPL)     │                  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                  │
│         │                 │                 │                           │
│  ┌──────▼─────────────────▼─────────────────▼───────┐                  │
│  │              Branch Coordination Layer            │                  │
│  │  • Distributed consensus for branch operations    │                  │
│  │  • Cross-region branch synchronization           │                  │
│  │  • Conflict resolution coordinator               │                  │
│  └──────────────────────┬───────────────────────────┘                  │
│                         │                                               │
│  ┌──────────────────────▼───────────────────────────┐                  │
│  │              Storage Layer (Separated)            │                  │
│  ├───────────────┬───────────────┬──────────────────┤                  │
│  │ Storage Node  │ Storage Node  │  Storage Node    │                  │
│  │  (us-east-1)  │  (eu-west-1)  │  (ap-southeast)  │                  │
│  │  Delta SSTs   │  Delta SSTs   │  Delta SSTs      │                  │
│  └───────────────┴───────────────┴──────────────────┘                  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Key Characteristics:

Storage/compute separation
Multi-region replication
Distributed branch coordination
Advanced conflict resolution
Delta SSTable compaction
Branch-level access control
GPU-accelerated merges
Branch creation: <555μs (sub-millisecond)

Feature Matrix

Feature	Lite	Full	Notes
Core Branching
Copy-on-write branches	Yes	Yes
Instant creation	<10ms	<555μs	Full optimized for cloud
Hierarchical branches	Yes	Yes
Branch isolation	Yes	Yes
Time-Travel
AS OF NOW	Yes	Yes
AS OF TIMESTAMP	Yes	Yes
AS OF TRANSACTION	Yes	Yes
AS OF SCN	Yes	Yes	Oracle compatibility
Point-in-time recovery	Yes	Yes
Operations
Create branch	Yes	Yes
Delete branch	Yes	Yes
Merge branch	Yes	Yes
Branch diff	No	Yes	Full only
Flashback	No	Yes	Full only
Row history	No	Yes	Full only
Distribution
Multi-node	No	Yes	Full only
Cross-region	No	Yes	Full only
Storage separation	No	Yes	Full only
Advanced
Three-way merge	No	Yes	Full only
GPU acceleration	No	Yes	Full only
Branch permissions	Basic	RBAC	Full has ABAC
Retention policies	Manual	Auto	Full has GC
Materialized views	No	Yes	Full only
Delta compaction	No	Yes	Full only

Migration: Lite to Full

Branch Data Migration

# Export branches from Lite
heliosdb-lite export --include-branches --output backup.tar.gz

# Import to Full
heliosdb import backup.tar.gz --target-cluster prod

REPL Command Compatibility

All Lite REPL commands work identically in Full:

# These work in both editions
\branches
\use dev
\show branch
\branch create feature --from=main
\branch delete old-branch
\branch merge dev main

Full provides additional commands that enhance (not replace) Lite functionality.

Use Case Recommendations

Use HeliosDB Lite When:

Development/Testing: Local development with branch isolation
Edge Deployment: Single-node embedded database
CI/CD Pipelines: Ephemeral test databases
Prototyping: Quick schema experimentation
Resource Constrained: Limited memory/CPU environments

Use HeliosDB Full When:

Production Workloads: High availability requirements
Multi-Region: Geographic distribution needed
Large Scale: Terabytes of data
Enterprise: Branch-level RBAC/ABAC required
Analytics: Materialized views with auto-refresh
Compliance: Audit logging, retention policies

Quick Reference

Lite REPL Session

$ heliosdb-lite repl --memory

heliosdb [main] > CREATE TABLE users (id INT, name TEXT);
Query OK

heliosdb [main] > \branch create dev --from=main
Created branch dev from main in 8.5ms

heliosdb [main] > \use dev
Switched to branch 'dev' with data isolation enabled.

heliosdb [dev] > INSERT INTO users VALUES (1, 'Alice');
Query OK, 1 row affected

heliosdb [dev] > \show branch
Branch: dev (ID: 1)
  State: Active

heliosdb [dev] > \use main
heliosdb [main] > SELECT * FROM users;
(0 rows)  -- Isolation working!

Full REPL Session

$ heliosdb-cli --cluster prod-us-east

heliosdb [main] > \branches
Database Branches:
────────────────────────────────────────────────────────────────
Name                 State        Current LSN     Storage Node
────────────────────────────────────────────────────────────────
main                 Active       0/16B3D8        node-us-east-1
dev                  Active       0/16B3E0        node-us-east-1
staging              ReadOnly     0/16B3D0        node-eu-west-1

heliosdb [main] > \branch create feature/auth --from=dev --at=NOW
Created branch feature/auth from dev in 0.42ms
  Data isolation: enabled
  Storage node: node-us-east-1
  Use: \use feature/auth to switch

heliosdb [main] > \branch stats dev
Branch Stats: dev
────────────────────────────────────
  Memtable Size:      1048576 bytes
  Delta SSTables:     3
  Delta Size:         524288 bytes
  Page Count:         128
  Total Writes:       15234
  Total Reads:        89012

heliosdb [main] > \branch diff dev main
Diff: dev vs main
────────────────────────────────────────────────────────────────
  Tables modified: 3
  Rows inserted:   1,523
  Rows updated:    234
  Rows deleted:    12

Conclusion

HeliosDB Full is a complete superset of Lite. Developers can:

Start with Lite for development and testing
Deploy to Full for production without code changes
Use identical REPL commands across both editions
Leverage Full-only features as needs grow

The branching model is consistent across editions, ensuring a seamless development-to-production workflow.

For more information, see: