---
title: "HeliosDB-Lite v2.4.0-beta Changelog"
---

# 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](/docs/lite/getting-started/installation/) and the
> [CLI reference](/docs/lite/reference/cli/).

**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

```bash
# 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](#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:

```sql
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:

```sql
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:

```bash
heliosdb-lite repl --data-dir ./mydb
```

```sql
-- 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

4. **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

5. **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

6. **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

- Support: support@heliosdb.com
- Community: [Discord](https://discord.gg/yTykuUrFXc)
- Documentation: https://www.heliosdb.com/docs/lite/

## 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.