Skip to content
HeliosDB HeliosDB Full

HeliosDB Lite Documentation

HeliosDB Lite Documentation

This directory contains documentation for HeliosDB Lite, a lightweight variant of HeliosDB that was developed and later moved to a standalone repository.

Status

HeliosDB Lite has been moved to a standalone repository (November 15, 2025, commit f67b159)

  • Location: /home/claude/HeliosDB-Lite
  • Status: v1.0.0 MVP Complete (100% feature parity for core functionality)
  • Workspace Impact: Reduced from 185 to 184 crates

Reasons for Separation

  1. Independent Release Cycle - Lite can be versioned and released separately from Full
  2. Standalone Compilation - No workspace dependencies, faster build times
  3. Simplified Distribution - Single binary distribution without full database overhead
  4. Clear Separation of Concerns - Distinct product positioning (lite vs full)

Documentation Structure

This directory preserves the Phase 3 Compatibility Plan documentation that defines how HeliosDB Lite integrates with HeliosDB Full.

/planning - Implementation Plans and Specifications

Contains the complete implementation roadmap for Lite→Full compatibility:

  1. HELIOSDB_LITE_PHASE3_QUICK_START.md - One-page quick reference
  2. HELIOSDB_LITE_PHASE3_COMPATIBILITY_README.md - Master index and overview
  3. HELIOSDB_LITE_PHASE3_IMPLEMENTATION_SUMMARY.md - Complete checklist and timeline
  4. HELIOSDB_LITE_PHASE3_FULL_IMPLEMENTATION_GUIDE.md - Complete implementation roadmap
  5. HELIOSDB_LITE_SQL_WRAPPER_SPECIFICATION.md - SQL syntax layer (P0 Critical)
  6. HELIOSDB_LITE_PRODUCT_QUANTIZATION_IMPLEMENTATION.md - PQ implementation (P0 Critical)
  7. HELIOSDB_LITE_INCREMENTAL_MVS_DISTRIBUTED.md - Distributed incremental MVs (P1 High)

/analysis - Compatibility Analysis and Evaluation

Contains detailed feature-by-feature compatibility analysis:

  1. HELIOSDB_LITE_COMPATIBILITY_MODEL.md - Unidirectional compatibility model
  2. HELIOSDB_LITE_COMPATIBILITY_SUMMARY.md - Quick reference compatibility matrix
  3. HELIOSDB_LITE_PHASE3_HELIOSDB_FULL_COMPATIBILITY_ANALYSIS.md - Detailed analysis
  4. HELIOSDB_LITE_HYBRID_STORAGE_EVALUATION.md - Why NOT to implement hybrid storage

/reference - Master Index

  1. HELIOSDB_LITE_PHASE3_INDEX.md - Master documentation index for all Lite Phase 3 docs

Compatibility Model

Unidirectional Compatibility: Lite → Full only

  • HeliosDB Lite → Full: Seamless upgrade path (required)
  • ❌ HeliosDB Full → Lite: Not required (no downgrade path)

This means HeliosDB Full can have features that Lite doesn’t have, simplifying implementation.

Key Features Covered

P0 - Critical Path (5-7 weeks)

  • SQL Wrapper Layer - Branching, time-travel, MV, vector SQL syntax
  • Product Quantization - 8-16x memory reduction for vector indexes

P1 - High Priority (6-8 weeks)

  • Distributed Incremental MVs - Cross-node refresh coordination
  • FSST + ALP Compression - DuckDB-compatible string and float compression

P3 - Do NOT Implement

  • Hybrid Storage - Full’s HCC v2 is superior (15x vs 5x compression)

Timeline

  • Critical Path: 5-7 weeks (P0 features)
  • High Priority: 6-8 weeks (P1 features)
  • Total: 12-20 weeks for full compatibility
  • Beta Testing: 3 weeks
  • Production Release: Week 20

Success Criteria

  1. 100% of Lite dumps import without loss
  2. All Lite SQL syntax works in Full
  3. All Lite features enhanced in Full
  4. Full ≥ Lite on all benchmarks
  5. All Lite→Full migration tests pass
  6. Beta tested with real users

Historical Context

HeliosDB Lite was developed as part of the HeliosDB workspace from November 2025. The crate reached v1.0.0 MVP status with:

  • Complete SQL parser and executor
  • PostgreSQL wire protocol compatibility
  • Transaction support (MVCC)
  • Vector indexing with HNSW
  • Encryption and compression
  • Audit logging
  • Network security

After achieving production-ready status, it was separated into a standalone repository to enable independent development and distribution.

Migration to Standalone Repository

Date: November 15, 2025 Commit: f67b159 Reason: Independent release cycle, simplified distribution Status: Complete and production-ready Location: /home/claude/HeliosDB-Lite

All source code, tests, and standalone build configuration were moved to the separate repository. This directory preserves the compatibility planning documentation for future reference.

Last Updated: November 17, 2025 Documentation Status: Complete and organized per DOCUMENTATION_INDEX.md guidelines