Skip to content
HeliosDB 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 Status: experimental; an operationally hardened sync module is planned

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 = "4", 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 the auth module has full test coverage
  4. API Instability: Module structure may change
  5. Performance Unvalidated: No benchmarks yet

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 the hardened sync module: it is planned

Contributing

Contributions to complete this module are welcome. See:

References

  • Code: /src/sync/ directory
  • Tests: /tests/sync_*_tests.rs (auth only)

Planned Experimental Features

simd: SIMD-Accelerated Operations

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

gpu-acceleration: GPU-Accelerated Training

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