Skip to content
HeliosDB HeliosDB Nano

Experimental Features in HeliosDB Nano

Experimental Features in HeliosDB Nano

Overview

This document describes experimental features in HeliosDB Nano that are not operationally hardened but available for testing and development.

⚠️ WARNING: Experimental features may have incomplete implementations, missing tests, breaking API changes, or be removed entirely in future releases. Do NOT use in production.

sync-experimental: Sync/Replication Module

Feature Flag: sync-experimental Target Completion: v2.2.0 (Estimated: Q1 2026)

Description

Multi-node synchronization and replication system for HeliosDB Nano, enabling:

  • Offline-first mobile/edge applications
  • Multi-node eventual consistency
  • Bidirectional sync with conflict resolution
  • HTTP/gRPC-based change propagation

Completed Components:

  • ✅ JWT Authentication System (100%) - operationally hardened with 15 tests
  • ✅ Vector Clock Conflict Detection (100%) - Full causality tracking
  • ✅ Offline Queue (100%) - RocksDB-backed persistent storage
  • ✅ Delta Compression (100%) - Binary diff/patch framework
  • ✅ Message Protocol (100%) - Complete message types
  • ✅ Conflict Resolution (90%) - Last-write-wins, custom resolvers
  • ✅ Sync Server (75%) - Auth complete, storage hooks missing
  • ✅ Sync Client (70%) - Logic complete, network layer stubbed

Missing Components:

  • ❌ Storage Engine Integration (CDC hooks)
  • ❌ HTTP/gRPC Transport Layer
  • ❌ Change Log Queries
  • ❌ Delta Application to Database
  • ❌ End-to-End Integration Tests

Code Statistics:

  • Total Lines: 2,380
  • Tests: 15 passing (auth module only)
  • TODO Markers: 8

How to Enable

Cargo.toml
[dependencies]
heliosdb-nano = { version = "2.1", features = ["sync-experimental"] }
Terminal window
# Build with experimental sync
cargo build --features sync-experimental


# Run tests (limited to completed components)
cargo test --features sync-experimental

API Example (Incomplete)

#[cfg(feature = "sync-experimental")]
use heliosdb_nano::sync::{SyncClient, SyncConfig};


#[cfg(feature = "sync-experimental")]
fn example_sync() -> Result<(), Box<dyn std::error::Error>> {
    // Create sync client
    let config = SyncConfig {
        server_url: "https://sync.example.com".to_string(),
        auth_token: "jwt-token-here".to_string(),
        offline_queue_path: "./offline_queue".to_string(),
    };


    let client = SyncClient::new(config)?;


    // Sync database (NOT IMPLEMENTED YET)
    // client.sync()?;


    Ok(())
}

Known Issues

  1. No Network Transport: HTTP/gRPC layer is stubbed
  2. No Storage Integration: CDC hooks not implemented
  3. Incomplete Tests: Only auth module fully tested
  4. API Instability: Module structure may change
  5. Performance Unvalidated: No benchmarks yet

Roadmap to Production

v2.2.0 (Target: Q1 2026):

  1. Implement HTTP/gRPC transport (1 week)
  2. Add storage engine CDC hooks (1 week)
  3. Complete change log queries (3 days)
  4. Implement delta application (3 days)
  5. Add end-to-end integration tests (1 week)
  6. Performance benchmarking (3 days)
  7. Security audit (1 week)

Estimated Effort: 4-5 weeks total

Alternatives

If you need sync/replication now, consider:

  1. Application-Level Sync: Implement in your application layer
  2. PostgreSQL Logical Replication: Use when in PostgreSQL-compatible mode
  3. Third-Party Tools: CouchDB, RxDB, WatermelonDB for mobile sync
  4. Wait for v2.2.0: operationally hardened sync module planned for Q1 2026

Contributing

Contributions to complete this module are welcome! See:

References

Future Experimental Features

simd: SIMD-Accelerated Operations

Target: v2.3.0

SIMD-optimized vector operations for 2-5x performance improvement.

gpu-acceleration: GPU-Accelerated Training

Target: v3.0.0

GPU-based vector quantization training for 10-100x speedup.

Stability Promise

Stable Features (operationally hardened):

  • Core SQL database
  • Vector search with HNSW
  • Encryption (TDE)
  • PostgreSQL wire protocol
  • Compression (ALP/FSST)
  • Time-travel queries
  • Database branching
  • Materialized views

Experimental Features (NOT operationally hardened):

  • Sync/replication module

Deprecated Features (To Be Removed):

  • None currently

Questions or Feedback?

Maintainer: HeliosDB Team License: Apache 2.0