Skip to content
HeliosDB HeliosDB Lite

HeliosDB-Lite v2.4.0-beta Changelog

Note (current distribution): HeliosDB Lite is distributed to licensed customers as a source distribution that builds the heliosdb-lite binary. Upgrade steps on this page use that binary, SQL and build options; see Installation and the CLI reference.

Base Version: v2.3.1

Overview

This beta release consolidates branching, time-travel, and materialized view features with critical type safety corrections and stability improvements. While core database functionality is stable, this is a beta release with known limitations that need resolution before production use.

What’s Included in Beta

Stable Features

  1. Core Database Engine

    • PostgreSQL-compatible SQL execution
    • ACID transactions with MVCC
    • RocksDB-based storage
    • Write-Ahead Logging (WAL)
    • Snapshot isolation

  2. Branching, Time-Travel & Materialized Views

    • Database branching (CREATE/DROP/MERGE BRANCH)
    • Time-travel queries (AS OF TIMESTAMP/TRANSACTION/SCN)
    • Materialized views (CREATE/REFRESH/DROP)
    • System views (pg_database_branches, pg_mv_staleness)
    • Enhanced REPL with meta-commands

  3. Vector Search

    • HNSW indexing
    • Vector similarity search
    • Distance metrics (L2, cosine, dot product)

  4. Security

    • Transparent data encryption (TDE)
    • PostgreSQL authentication (MD5, SCRAM-SHA-256)
    • SSL/TLS support

  5. Compression

    • FSST string compression
    • ALP numeric compression
    • Columnar compression (Apache Arrow)

Known Limitations

  1. Sync Protocol Disabled

    • Reason: Type incompatibilities with v2.3.0 features
    • Impact: No distributed replication in this beta
    • Resolution: Planned for v2.4.0 stable

  2. Performance

    • MV refresh scheduler may be CPU-intensive under high load
    • Vector quantization needs additional testing
    • Branch merge performance not fully optimized

  3. Documentation

    • Some advanced features lack complete examples
    • Migration guide from v2.3.1 incomplete
    • System view schemas need better documentation

Changes from v2.3.1

Type Safety Corrections

Storage Layer

  • Fixed: MV refresh scheduler priority queue ordering (min-heap → max-heap)
  • Fixed: MV delta log ID generation type consistency
  • Fixed: Incremental refresh storage reference type
  • Fixed: Branching snapshot resolution lifetime annotations

SQL Executor

  • Fixed: Executor function signatures with explicit lifetimes
  • Fixed: Materialized view metadata handling
  • Fixed: System view query execution paths

Protocol Layer

  • Fixed: Sync protocol type mismatches (disabled for beta)
  • Fixed: PostgreSQL message handler type consistency
  • Fixed: SSL/TLS certificate lifetime annotations

New Features

Materialized Views (Complete)

  • CPU-aware auto-refresh scheduling
  • Incremental refresh support
  • Staleness tracking
  • System views for monitoring
  • Priority-based refresh queue

Database Branching (Complete)

  • CREATE BRANCH with AS OF clauses
  • DROP BRANCH with IF EXISTS
  • MERGE BRANCH with conflict detection
  • Branch metadata and options
  • System view for branch introspection

Time-Travel Queries (Complete)

  • AS OF TIMESTAMP ‘YYYY-MM-DD HH:MM:SS’
  • AS OF TRANSACTION txn_id
  • AS OF SCN scn_number
  • Snapshot resolution and validation

System Views (Complete)

  • pg_database_branches: Branch metadata and lineage
  • pg_mv_staleness: MV refresh status and priority
  • pg_vector_index_stats: Vector index metrics
  • PostgreSQL-compatible system catalogs

Performance Improvements

  • MV Scheduler: CPU-aware refresh throttling
  • Branch Operations: Optimized snapshot resolution
  • Vector Search: Improved HNSW index build time
  • Compression: FSST encoder sampling improvements

Bug Fixes

  1. Priority Queue Ordering (Critical)

    • Fixed the MV refresh scheduler using wrong heap order
    • Impact: MVs refreshed in wrong priority order
    • Resolution: Changed to max-heap (highest priority first)

  2. Delta Type Deprecation

    • Replaced the MV delta type enum with a new operation type
    • Deprecated old enum with migration warning

Breaking Changes

API Changes

  1. MV delta types renamed - Embedded API change (licensed source distribution); the old names are deprecated and emit a migration warning. SQL is unchanged.

  2. MV refresh priority - Priority interpretation changed: higher priority values are now refreshed first.

Feature Flags

  1. Sync Protocol - Enabled by default in v2.3.0; now disabled by default and opt-in at build time with cargo build --release --features sync-experimental (not recommended for this beta).

Installation

HeliosDB-Lite is available to licensed customers as a source distribution (contact sales@heliosdb.com); it is not published on crates.io.

Build from Source

Terminal window
# Unpack the source distribution, then:
cd heliosdb-lite
cargo build --release
export PATH="$PWD/target/release:$PATH"


# With the experimental sync protocol (not recommended)
# cargo build --release --features sync-experimental

Migration from v2.3.1

Step 1: Back Up and Build

Stop every process that has the data directory open, copy the directory, then build v2.4.0-beta from the source distribution (see Installation). The data format is unchanged.

Step 2: Review Materialized View Priorities

If you set materialized view refresh priorities, note that priority interpretation changed: previously a lower number meant higher priority; now a higher number means higher priority. In current builds the priority is set per view:

ALTER MATERIALIZED VIEW sales_summary SET (priority = 9);

Step 3: Disable Sync Protocol

The sync protocol is no longer built by default. Either rebuild with --features sync-experimental (not recommended for this beta), or use branching for point-in-time copies instead:

CREATE BRANCH backup_branch FROM main AS OF NOW;

Step 4: Test Thoroughly

Open your data with the new binary and check the features this release changed:

Terminal window
heliosdb-lite repl --data-dir ./mydb
-- Branches and their lineage
SELECT * FROM pg_database_branches();


-- Materialized view refresh status
SELECT * FROM pg_mv_staleness();


-- Time-travel
SELECT * FROM orders AS OF TIMESTAMP '2025-01-15 10:30:00';

Known Issues

Critical Issues

None - all critical bugs from v2.3.1 are resolved.

High Priority Issues

  1. Compression Issues

    • Impact: Advanced compression features may not work correctly
    • Workaround: Use default compression (no-op or zstd)
    • ETA: Fix in v2.4.0-rc1

  2. Vector Quantization Issues

    • Impact: Quantized vector search unreliable
    • Workaround: Use standard HNSW without quantization
    • ETA: Fix in v2.4.0-rc1

  3. Audit Log Issues

    • Impact: Audit logging may miss some events
    • Workaround: None (audit log still works for most cases)
    • ETA: Fix in v2.4.0-rc1

Medium Priority Issues

  1. System View Issue

    • Impact: pg_v2_3_views_schemas may return incomplete data
    • Workaround: Use individual system views directly
    • ETA: Fix in v2.4.0-rc1

  2. Transaction Version Parsing

    • Impact: Some edge cases in MVCC version parsing
    • Workaround: None (rarely triggered)
    • ETA: Fix in v2.4.0-rc1

Low Priority Issues

  1. Documentation Gaps
    • Impact: Some advanced features lack examples
    • Areas: System views, branch merging, MV scheduling
    • ETA: Complete in v2.4.0-rc1

Not Included in Beta

Features Disabled

  1. Sync/Replication Protocol
    • Reason: Type incompatibilities
    • Alternative: Use branching for backup/restore
    • Planned: v2.5.0 or later

Features Not Yet Implemented

  1. Distributed Query Execution
  2. Multi-Master Replication
  3. Cross-Branch Queries
  4. MV Incremental Refresh (partial implementation)
  5. Branch Merge with Complex Conflict Resolution

Upgrade Recommendations

Who Should Upgrade?

Should Upgrade:

  • Development and testing environments
  • Projects needing branching, MVs, or time-travel
  • Projects doing beta testing
  • Non-critical applications

Should NOT Upgrade:

  • Production systems with strict uptime requirements
  • Applications using sync/replication protocol
  • Mission-critical financial/healthcare applications

Upgrade Path

  1. Test in Development First

    • Set up v2.4.0-beta in dev environment
    • Run full test suite with your data
    • Verify branching, MVs, and time-travel work for your use case

  2. Validate Critical Paths

    • Test your most important queries
    • Verify backup/restore works
    • Check performance benchmarks

  3. Plan Rollback Strategy

    • Keep v2.3.1 backups
    • Document rollback procedure
    • Test rollback process

  4. Staged Rollout

    • Start with non-critical services
    • Monitor for issues
    • Gradually expand to more systems

Support and Feedback

Reporting Issues

Please report beta issues to support@heliosdb.com with:

  • HeliosDB-Lite version: 2.4.0-beta
  • Rust version
  • Operating system
  • Minimal reproduction case
  • Cargo test output (if applicable)

Beta Testing Checklist

Help us improve v2.4.0 by testing:

  • Branching, MVs, and time-travel
  • Migration from v2.3.1
  • Performance benchmarks
  • Edge cases in your use case
  • Documentation accuracy
  • API ergonomics

Contact

Acknowledgments

Thank you to all contributors and beta testers!

** BETA NOTICE**: This is a beta release. While suitable for development and testing, it is not recommended for production use until v2.4.0 stable is released. Known issues and limitations are documented above.