---
title: "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`
**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

```toml
# Cargo.toml
[dependencies]
heliosdb-nano = { version = "4", features = ["sync-experimental"] }
```

```bash
# Build with experimental sync
cargo build --features sync-experimental

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

### API Example (Incomplete)

```rust
#[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:
- [Contributing Guide](https://www.heliosdb.com/docs/nano/developer/contributing/) - How to contribute
- [GitHub Issues](https://github.com/HeliosDatabase/HeliosDB-Nano/issues) - Tagged with `sync-experimental`

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

- **Bug Reports**: [GitHub Issues](https://github.com/HeliosDatabase/HeliosDB-Nano/issues)
- **Feature Requests**: [Discord](https://discord.gg/yTykuUrFXc)
- **Security Issues**: security@heliosdb.com

---

**Maintainer**: HeliosDB Team
**License**: Apache 2.0