Changelog

Changelog

All notable changes to HeliosDB Lite will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[3.1.0] - 2025-12-08 - Multi-User ACID In-Memory Mode

Highlights

HeliosDB-Lite v3.1.0 introduces comprehensive multi-user ACID transaction support for in-memory mode with user-triggered persistence:

• Multi-User Sessions: Concurrent user sessions with independent transaction contexts
• Advanced Locking: Deadlock detection, configurable timeouts, three lock modes
• Isolation Levels: READ COMMITTED, REPEATABLE READ, SERIALIZABLE
• Dump/Restore: Manual and automated backup/restore with compression
• Resource Quotas: Per-user memory limits, connection limits, timeouts
• 100% Backward Compatible: All v3.0.0 code works without changes

Added

Session Management

• SessionManager: Multi-user session coordination with per-user contexts
• Session Lifecycle: Create, authenticate, timeout, and cleanup sessions
• Session Statistics: Track transactions, queries, memory usage per session
• User Authentication: Trust, password, and SCRAM-SHA-256 auth methods
• Resource Quotas: Per-user memory limits, connection limits, transaction timeouts
• Session Monitoring: pg_stat_activity system view for active sessions

Lock Management

• LockManager: Advanced lock acquisition with deadlock detection
• Lock Modes: Shared (S), Exclusive (X), Update (U) locks
• Deadlock Detection: Wait-for graph based cycle detection
• Lock Timeout: Configurable timeout with exponential backoff
• Lock Statistics: Track lock acquisition time, contention, deadlocks

Transaction Isolation Levels

• READ COMMITTED: Fresh snapshot per statement, no dirty reads
• REPEATABLE READ: Consistent snapshot throughout transaction
• SERIALIZABLE: Full serializability with conflict detection
• Per-Session Configuration: Set isolation level per session or transaction
• SQL Support: BEGIN TRANSACTION ISOLATION LEVEL ... syntax

Dump/Restore System

• DumpManager: Export/import database to portable dump files
• Full Dumps: Complete database snapshot with schema and data
• Incremental Dumps: Append-mode dumps with LSN tracking
• Compression: zstd (default), lz4, or no compression
• Selective Dumps: Dump specific tables only
• Dump History: Track dump operations with pg_stat_dump_history view
• Dirty State Tracking: Track uncommitted changes, warn on shutdown
• Automated Scheduling: Cron-style scheduled dumps via configuration

CLI Commands

• heliosdb-lite dump: Dump in-memory database to file
  • Options: --output, --compress, --tables, --append, --verbose
• heliosdb-lite restore: Restore from dump file
  • Options: --input, --mode, --tables, --on-conflict, --verbose
• heliosdb-lite status: Show database status and statistics
  • Options: --format (text/json)
• Enhanced start command: Multi-user session support
• Enhanced repl command: Session-aware interactive shell

Configuration Sections

• [session]: Session timeout, max sessions per user, default isolation level
• [locks]: Lock timeout, deadlock detection interval
• [dump]: Automated dump scheduling, compression settings, retention
• [resource_quotas]: Memory limits, connection limits, query timeouts

API

• SessionManager API: create_session(), destroy_session(), begin_transaction(), commit_transaction(), rollback_transaction()
• LockManager API: acquire_lock(), release_lock(), detect_deadlock()
• DumpManager API: dump(), restore(), verify_dump(), list_dumps()
• Transaction API: set_isolation_level(), get_isolation_level()
• DirtyTracker API: is_dirty(), get_dirty_bytes(), clear_dirty_since_lsn()

System Views

• pg_stat_activity: Active session monitoring
• pg_locks: Lock information and wait states
• pg_stat_dump_history: Dump operation history

Documentation

• User Guides: In-memory mode guide, dump/restore procedures
• Reference: CLI v3.1 reference, configuration v3.1 reference
• API Documentation: Session management API, lock manager API, dump API
• Architecture: Multi-user transactions architecture with diagrams
• Migration Guide: v3.0 to v3.1 migration guide

Changed

Performance Improvements

• Lock-free concurrent session management using DashMap (10-100x faster)
• Optimized lock acquisition with adaptive backoff
• Batch dump operations (10,000 rows per batch)
• Streaming restore for large dumps (no full load in memory)
• Early lock release in commit path
• Read-heavy optimization with MVCC snapshots (no read locks)

Behavior Changes (Non-Breaking)

• In-memory mode now warns on shutdown if dirty state exists
• Sessions automatically cleaned up after timeout (default: 1 hour)
• Lock timeouts default to 30 seconds (configurable)
• Dumps default to zstd compression (3x-5x reduction)

Fixed

None (all fixes from v3.0.0 included)

Deprecated

None

Removed

None

Breaking Changes

None. v3.1.0 is 100% backward compatible with v3.0.0.

Security

• Argon2 password hashing for user authentication
• Per-user resource quotas prevent resource exhaustion
• Session timeouts prevent abandoned connections
• Audit logging for session creation/destruction
• Dirty state tracking prevents data loss on shutdown

Migration

From v3.0.0 to v3.1.0:

• No code changes required
• Existing applications work without modification
• New features are opt-in
• Configuration file backward compatible
• See MIGRATION_v3.0_to_v3.1.md for details

Known Limitations

1. Session Management: Optional feature, not required for single-user apps
2. Dump Format: .heliodump files not compatible with v3.0.0
3. In-Memory Only: Dump/restore primarily for in-memory mode (persistent mode has WAL)
4. No Distributed Transactions: Single-node transactions only

Performance Metrics

Metric	Target	Achieved
Concurrent Sessions	10,000+	10,000+
Transaction Latency (p99)	<5ms	1-5ms
Lock Acquisition	<1ms	0.05-1ms
Dump Throughput	>100MB/s	66-100MB/s
Restore Throughput	>100MB/s	40-66MB/s

Testing

• 50+ new integration tests for session management
• 30+ unit tests for lock manager
• 25+ tests for dump/restore
• 100% backward compatibility tests passing
• Performance benchmarks for all new features

---

[3.0.0] - 2025-12-06 - GA Release

Highlights

HeliosDB-Lite v3.0.0 is the first General Availability release, featuring:

• Production-Ready Build: Zero non-documentation warnings
• Enhanced REPL: 19 new commands for vectors, agents, and documents
• Comprehensive Configuration: 8 new config sections for AI, RAG, and search
• Feature-Based Help: Intuitive help system organized by functionality

Added

New REPL Commands

• Session Management Commands

  • \sessions - List all agent sessions
  • \session-new <name> - Create a new agent session
  • \session <id> - Show session details
  • \session-delete <id> - Delete an agent session
  • \chat <id> - Interactive chat with session
  • \session-clear <id> - Clear session messages

• Vector Store Commands

  • \vectors - List all vector stores
  • \vector <name> - Show vector store details
  • \vector create <name> <dims> [metric] - Create vector store
  • \vector delete <name> - Delete vector store
  • \vector stats <name> - Show vector store statistics

• Document Collection Commands

  • \collections - List all document collections
  • \collection <name> - Show collection details
  • \docs <collection> - List documents in collection
  • \doc <collection> <id> - Get document details
  • \search-docs <query> - Search across document collections

• Performance & Utility Commands

  • \explain <query> - Show query execution plan
  • \profile <query> - Profile query with detailed timing
  • \telemetry - Show database statistics and health

Help System Improvements

• Feature-based help organization (not version-based)
• New help categories: basics, schema, branching, time-travel, vectors, documents, agents, ai, settings, examples, sql
• Terminal-responsive layout (2-column for narrow, 3-column for wide terminals)
• Integrated examples with each command
• Category-specific help via \h <category>

Configuration Sections

• [ai] - AI feature toggle
• [ai.llm] - LLM provider configuration (OpenAI, Anthropic, Ollama)
• [ai.embedding] - Embedding model configuration
• [rag] - RAG chunking and retrieval settings
• [search] - Full-text search configuration
• [wasm] - WebAssembly execution limits
• [mcp] - Model Context Protocol server settings
• [storage.tuning] - Advanced storage optimization

Changed

• AI commands (\ai infer, \ai generate, \ai optimize) now use direct database API instead of showing REST API hints
• Improved error messages with helpful suggestions
• Schema analysis provides actionable index recommendations

Fixed

• Help system now organizes by feature instead of version numbers
• Consistent type handling in session and vector commands

Build Quality (GA Polish)

• Eliminated 70+ non-documentation compiler warnings
• Fixed deprecated base64::encode → STANDARD.encode() migration
• Fixed hidden lifetime parameter warnings with explicit annotations
• Resolved unused import/variable warnings across 25+ files
• Fixed deprecated DeltaType enum usage
• Made ServiceMetrics public to fix visibility warning
• Removed sysinfo feature gate (always available)

[2.5.0] - 2025-12-01

Added

REST API (v1)

• Full HTTP REST API with 14 endpoints via Axum framework
• Branch management endpoints (GET/POST/DELETE /v1/branches)
• Table management endpoints (GET/POST/DELETE /v1/branches/{branch}/tables)
• Data CRUD endpoints (GET/POST/PUT/DELETE /v1/branches/{branch}/tables/{table}/data)
• SQL query execution (POST /v1/branches/{branch}/query)
• SQL statement execution (POST /v1/branches/{branch}/execute)
• Vector similarity search endpoint (POST /v1/branches/{branch}/vector/search)
• Health check endpoint (GET /v1/health)
• Database info endpoint (GET /v1/info)

REST API Models

• Comprehensive request/response models for all endpoints
• QueryRequest/QueryResponse for SQL query results
• ExecuteRequest/ExecuteResponse for DDL/DML operations
• InsertDataRequest/InsertDataResponse for data insertion
• UpdateDataRequest/UpdateDataResponse for data updates
• DeleteDataRequest/DeleteDataResponse for data deletion
• VectorSearchRequest/VectorSearchResponse for similarity search
• Parameterized query support with QueryParameter types
• Pagination support with PaginationInfo

API Middleware

• JWT authentication middleware with configurable secret key
• API key authentication support
• Rate limiting middleware with configurable limits
• AuthMethod enum for flexible authentication strategies
• UserContext for request-scoped user information
• RateLimitConfig for customizable rate limiting rules

API Server Infrastructure

• AppState for shared database connection across handlers
• Graceful shutdown support
• Configurable bind address and port
• CORS support for cross-origin requests
• Structured error responses with ApiError

Audit Logging

• AuditLogger for comprehensive operation tracking
• DDL event logging (CREATE, ALTER, DROP operations)
• DML event logging (INSERT, UPDATE, DELETE operations)
• Configurable async buffer for high-throughput logging
• Audit log table (__audit_log) for persistent storage

Documentation

• REST API endpoint documentation with examples
• Authentication guide
• Rate limiting configuration guide
• v2.6.0 to v3.0 roadmap with AI-native features

Changed

Storage Engine

• branch_manager now uses Arc<RwLock<Option<Arc<BranchManager>>>> for better concurrency
• Improved get_or_init_branch_manager return type for Arc compatibility
• Enhanced scan_table functionality for audit logging

Query Handlers

• Schema inference from query results
• Tuple to JSON row conversion
• DataType string representation for all 17 types

Test Infrastructure

• Fixed 21 test instances for Tuple row_id field
• Improved test robustness for async operations
• Graceful handling of not-yet-implemented operations

Fixed

• FSST dictionary array size handling (padded to 8 bytes)
• DateTime/Timestamp conversion in system views
• DataType match exhaustiveness in query handler
• Value::Bytes variant naming consistency
• Router type annotations in API route tests
• Iterator filter pattern in FSST decoder tests

Security

• JWT-based authentication with HS256 algorithm
• API key authentication alternative
• Rate limiting to prevent abuse
• Query parameter validation

[2.2.0] - 2025-11-24

Added

Storage & Transactions (Week 5)

• MVCC snapshot isolation for transactions with proper versioning
• Complete WAL replay logic for crash recovery
• Table name extraction from keys in WAL entries for better observability
• Database statistics tracking (transaction commits, rollbacks, tuple operations)
• Thread-safe atomic counters for all transaction statistics via DatabaseStats
• Branch parent name lookup capability in branch management
• Snapshot size calculation for capacity planning and monitoring
• Enhanced transaction isolation guarantees (read-your-own-writes, snapshot reads)

Query Optimizer (Week 4)

• Cost-based join algorithm selection (hash join vs nested loop)
• NestedLoopJoin physical operator for small tables and non-equality joins
• Query statistics collection and usage in planner decisions
• Real table statistics (row counts, column distinct values, selectivity)
• StatisticsAnalyzer for collecting and managing table/column statistics
• Selectivity estimation for predicates (equality, range, NULL, AND, OR, NOT)
• Enhanced planner API with cost estimator support
• Verbose mode for debugging query plan decisions
• Explain plan support for all physical operators including NestedLoopJoin

PostgreSQL Protocol (Week 5)

• Prepared statement schema derivation from query AST
• Automatic type mapping from HeliosDB types to PostgreSQL OIDs
• Enhanced Parse message handling with schema extraction
• Result schema storage in PreparedStatement
• Improved Describe message responses with actual column types

Compression (Weeks 1-2)

• Comprehensive compression configuration API with fluent builder pattern
• CompressionBuilder for multi-table configuration
• CompressionAPI for statistics and management
• FSST dictionary persistence (export and restore symbol tables)
• Batch compression optimization with pre-allocation and chunking
• Adaptive compression with automatic cost-benefit analysis
• Intelligent sampling strategies (Stratified, BeginningWeighted, Diversity, Auto)
• Compression value count tracking in metadata
• Column-level compression statistics
• SamplingMethod enum for flexible data sampling
• Enhanced FsstEncoder with multiple compression modes

System Views (Week 5)

• pg_stat_optimizer view with real query statistics
• Enhanced pg_stat_database with transaction statistics
• Enhanced pg_branches with parent branch names
• Enhanced pg_snapshots with actual snapshot sizes
• pg_compression_stats view for compression monitoring (Week 2)

Vector Search (Week 5)

• Vector index length tracking for all metric types (Cosine, InnerProduct, L2)
• len() and is_empty() methods for CosineHnswIndex and InnerProductHnswIndex
• Accurate vector count reporting in MultiMetricHnswIndex

Changed

Storage Engine

• Improved WAL replay with two-pass algorithm (transaction-aware)
• Enhanced transaction handling with snapshot manager integration
• Updated begin_transaction() to pass snapshot_manager
• Updated begin_branch_transaction() with snapshot manager support
• Better error handling in WAL replay (resilient to partial failures)
• Arc-based StorageEngine in EmbeddedDatabase for better concurrency

Query Optimizer

• Planner now uses real statistics instead of hardcoded estimates
• Improved join algorithm selection based on actual cardinality
• Cost estimation now considers table sizes and selectivity
• Physical planner defaults to optimal algorithms per query pattern
• Better query plan quality with accurate row count estimates

Compression

• FSST codec now supports persistent dictionaries
• Improved batch compression performance (10-15% faster at scale)
• Better compression quality with intelligent sampling (1-5% improvement)
• CompressionStats now includes value count tracking
• ColumnCompressionMetadata extended with detailed metrics

PostgreSQL Protocol

• Extended query protocol now returns proper result schemas
• Better client compatibility with automatic schema extraction
• Parse phase includes one-time schema derivation (~160μs overhead)

System Views

• All system views now return real data instead of placeholder values
• Improved accuracy across all statistics views
• Better monitoring and observability capabilities

Fixed

Storage Layer

• Fixed MVCC transaction isolation incomplete implementation
• Fixed WAL replay that only counted entries without applying them
• Fixed table name extraction from storage keys (was always “unknown”)
• Fixed snapshot isolation for concurrent transactions
• Fixed crash recovery functionality (now fully operational)

Query Optimizer

• Fixed compilation errors in logical expression handling
• Fixed missing cost-based decision logic for join selection
• Fixed hardcoded selectivity estimates (now uses real statistics)

Compression

• Fixed missing compression value count in statistics
• Fixed FSST dictionary serialization (was returning empty vectors)
• Fixed compression metadata propagation

Vector Search

• Fixed vector index length always returning 0
• Fixed MultiMetricHnswIndex length calculation

System Views

• Fixed pg_stat_optimizer returning placeholder data (line 890)
• Fixed pg_stat_database missing transaction statistics (line 709)
• Fixed pg_branches parent lookup (line 785)
• Fixed pg_snapshots size calculation (line 836)
• Fixed sql/explain.rs statistics usage (lines 323, 331)

Protocol

• Fixed prepared statement schema derivation TODO (line 30)
• Fixed incomplete extended query protocol support

Type Safety

• Fixed type mismatches in various storage modules
• Fixed test module structure issues
• Improved error handling throughout codebase

Performance

Query Optimizer

• 10-100x speedup for queries with small table joins (nested loop optimization)
• Better query plans with real statistics reduce execution time
• Cost-based selection prevents unnecessary hash table construction
• O(log N) version lookups in MVCC read path

Compression

• 10-15% faster batch compression with pre-allocation
• Better CPU cache utilization with 64-item chunks
• Dictionary serialization/deserialization in ~10-25 μs
• Compression ratios: 2.0-2.5x (emails), 1.8-2.2x (URLs), 1.5-2.0x (mixed strings)
• Adaptive compression prevents wasting resources on incompressible data

WAL & Recovery

• Two-pass WAL replay with progress reporting (every 1000 operations)
• Resilient error handling (continues on non-fatal errors)
• Idempotent replay (safe to replay multiple times)

Statistics

• Negligible overhead for join decision making (~1.6 μs)
• Efficient selectivity estimation with O(1) lookups
• Real-time statistics updates with atomic counters

Deprecated

None

Removed

None

Security

• Enhanced data integrity with MVCC snapshot isolation
• Better crash recovery guarantees with complete WAL replay
• Improved audit trail with accurate table name tracking in WAL

Documentation

• Added comprehensive Week 1-5 progress reports
• Created v2.2.0 roadmap documentation (Part 1 & Part 2)
• Added implementation documentation for prepared statement schema derivation
• Added TODO tracking and audit reports
• Reorganized all markdown files into proper subdirectories
• Created completion reports for each development phase

Testing

• Added 15+ new tests across all components
• Added comprehensive unit tests for MVCC versioning (4 tests)
• Added integration tests for WAL replay and table extraction (6 tests)
• Added tests for compression value tracking
• Added tests for vector index length methods
• Added protocol tests for prepared statement schema derivation (3 tests)
• All 142+ tests passing with 100% success rate

Migration Notes

Upgrading from v2.1.0 to v2.2.0:

1. Statistics Collection: The query optimizer now collects real statistics. Run ANALYZE on your tables for optimal performance (automatic in future versions).

2. Compression Configuration: New compression API is opt-in. Existing compressed data remains compatible.

3. WAL Format: Enhanced WAL entries now include table names. Existing WAL files are forward-compatible.

4. System Views: All system views now return real data. Update any queries that relied on placeholder values.

5. API Changes: All changes are backward-compatible. New constructors added (e.g., Planner::with_cost_estimator()), existing code works unchanged.

---

[2.1.0] - 2025-11-XX

Added

• Physical query planner implementation
• Network protocol enhancements
• PostgreSQL wire protocol improvements

Changed

• Improved type safety throughout codebase
• Enhanced system view accuracy

---

[0.1.0-beta] - 2025-11-15

🎉 First Beta Release

This is the first public beta release of HeliosDB Lite, a PostgreSQL-compatible embedded database with vector search, encryption, and multi-tenancy.

Status: 90% feature complete, production-ready MVP

Added

Core Database Features

• Storage Layer: RocksDB-based LSM-tree storage with MVCC snapshot isolation
• SQL Support: PostgreSQL-compatible SQL engine (95%+ compatibility)
  • Full CRUD operations (CREATE TABLE, INSERT, UPDATE, DELETE, SELECT, DROP TABLE)
  • WHERE clauses with complex expressions
  • Aggregations (COUNT, SUM, AVG, MIN, MAX, COUNT(DISTINCT))
  • GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET, DISTINCT
  • INNER JOIN support (hash join in progress)
  • Transactions with ACID guarantees
  • Snapshot isolation for consistent reads
• Data Types: Complete PostgreSQL type system
  • Numeric: INT2, INT4, INT8, FLOAT4, FLOAT8, NUMERIC, DECIMAL
  • String: TEXT, VARCHAR, CHAR
  • Binary: BYTEA
  • Boolean: BOOL
  • Date/Time: TIMESTAMP, DATE, TIME, INTERVAL
  • UUID: UUID
  • JSON: JSON, JSONB (bincode-compatible)
  • Array: Array types
  • Vector: VECTOR(n) for embeddings

Security Features

• Transparent Data Encryption (TDE): AES-256-GCM encryption
  • <3% performance overhead with AES-NI
  • Argon2 key derivation (NIST recommended)
  • Per-table encryption support
  • Secure key management (environment, file, in-memory)
  • Automatic nonce generation
  • Memory zeroization for sensitive data
• Audit Logging: Comprehensive audit system
  • Authentication events
  • Data access tracking
  • Schema changes
  • Security events
  • Structured JSON logs
  • Query logging with metadata

Advanced Features

• Vector Search: Built-in HNSW index for AI/ML embeddings
  • Support for 1536-dimension vectors (OpenAI ada-002 compatible)
  • Distance metrics: Cosine, L2 (Euclidean), Inner Product
  • Fast k-NN search (<50ms @ 1M vectors target)
  • Configurable index parameters (M, ef_construction)
  • Serialization support
• JSONB Support: Native JSON binary format
  • Bincode-compatible storage
  • Efficient binary encoding
  • Full JSONB querying (operators in progress)
• Interactive REPL: PostgreSQL-style interactive shell
  • Tab completion for tables, columns, keywords
  • Meta-commands (\d, \dt, ?, \q)
  • Pretty table output
  • Multi-line query support
  • Persistent command history

Network & Protocol

• PostgreSQL Wire Protocol: 85% compatible
  • TCP server with async Tokio
  • SCRAM-SHA-256 authentication
  • Message handling infrastructure
  • Session management
  • Transaction status tracking
  • (Message encoding/decoding completion in progress)
• Server Mode: PostgreSQL-compatible network server
• Embedded Mode: SQLite-style in-process usage
• In-Memory Mode: ACID-compliant RAM-only storage

Developer Experience

• Comprehensive Documentation
  • 972 rustdoc API documentation items
  • Complete GETTING_STARTED.md guide (650+ lines)
  • 8 working examples
  • Quick reference guides
  • Troubleshooting documentation
• Testing: 142 tests with 100% pass rate
  • 21 comprehensive test suites
  • Integration tests
  • Unit tests
  • Performance benchmarks
  • Security tests
• Examples:
  • examples/embedded.rs - Basic embedded usage
  • examples/encryption.rs - Encryption setup
  • examples/encryption_demo.rs - Advanced encryption
  • examples/vector_search_demo.rs - Vector search
  • examples/complex_queries_demo.rs - Advanced SQL
  • examples/quickstart.rs - Quick start
  • examples/pg_server.rs - Server mode
  • examples/audit_demo.rs - Audit logging

In Progress (Targeting v0.2.0)

• PostgreSQL Protocol: Complete message encoding/decoding (85% → 100%)
• Hash Joins: Full hash join implementation for all join types
• JSONB Operators: Complete operator set (->, ->>, @>, ?, ?|, ?&)
• GIN Indexes: Generalized Inverted Index for JSONB and full-text search

Planned for Future Releases

Phase 2: Production Hardening (v0.2.x - v0.3.x)

• Multi-tenancy with Row-Level Security (RLS)
• Full-text search (tsvector, tsquery, BM25 ranking)
• CTEs (WITH clause, recursive and non-recursive)
• Window functions (ROW_NUMBER, RANK, LAG, LEAD, etc.)
• Advanced SQL features (LATERAL joins, subquery optimizations)
• Cloud KMS integration (AWS, Azure, GCP)
• CDC (Change Data Capture) for migrations

Phase 3: AI-Support & Ecosystem (v1.0+)

• AI-powered query optimization recommendations
• Schema design suggestions
• Performance monitoring and analysis
• Official client libraries (Python, JavaScript, Go)
• IDE plugins (VS Code, DBeaver)
• Community tools and integrations

Performance

• Build Time: ~36s (release mode)
• Test Execution: All 142 tests passing
• Binary Size: Optimized for embedded usage
• Memory Footprint: Efficient with configurable cache
• Encryption Overhead: <3% with AES-NI

Dependencies

Core Storage

• RocksDB 0.22 (LSM-tree storage)
• Apache Arrow 53 (columnar format)
• Apache Parquet 53 (columnar compression)

SQL Processing

• sqlparser-rs 0.53 (PostgreSQL dialect)

Cryptography

• AES-GCM 0.10 (encryption)
• Argon2 0.5 (key derivation)
• Ring 0.17 (cryptographic primitives)
• RustLS 0.23 (TLS 1.3)

Vector Search

• hnsw_rs 0.3 (HNSW index)

Async Runtime

• Tokio 1.40 (async runtime)

Architecture

HeliosDB Lite follows a Zero-IP Architecture using only open-source components:

• No proprietary algorithms
• All components use published research or standard implementations
• 100% Apache 2.0 licensed code
• Full transparency and auditability

Breaking Changes

None (initial release)

Security

• Transparent Data Encryption (TDE) with AES-256-GCM
• SCRAM-SHA-256 authentication
• Secure key derivation with Argon2
• Memory zeroization for sensitive data
• Comprehensive audit logging

Known Limitations (Beta)

1. PostgreSQL Protocol: Message encoding 85% complete (works with basic clients)
2. Hash Joins: Partial implementation (INNER JOIN works, optimizations pending)
3. JSONB Operators: Storage works, query operators in development
4. Multi-Tenancy: Foundation exists, RLS not yet implemented
5. Full-Text Search: Planned for Phase 2
6. Replication: Single-node only (clustering planned for full HeliosDB)

Migration Path

HeliosDB Lite provides a clear upgrade path to full HeliosDB:

• Data format compatible
• SQL compatibility maintained
• CDC-based migration (Phase 2)
• Zero-downtime tenant migration

System Requirements

• Rust: 1.75+ (for building from source)
• Operating Systems: Linux, macOS, Windows
• Architecture: x86_64, ARM64
• Memory: Minimum 512MB, recommended 2GB+
• Disk: Varies by data size (uses compression)

Benchmarks

See benches/ directory for comprehensive benchmarks:

• Encryption overhead validation
• Vector search performance
• Query execution benchmarks
• Storage performance tests

Contributors

This release was made possible by the HeliosDB team and community contributors.

License

Apache License 2.0 - see LICENSE for details.

Links

• Documentation: https://docs.rs/heliosdb-lite
• Repository: https://github.com/heliosdb/heliosdb
• Issues: https://github.com/heliosdb/heliosdb/issues
• Discussions: https://github.com/heliosdb/heliosdb/discussions

---

Upgrade Guide

From Source Build to v0.1.0-beta

If you were using a source build:

1. Update your Cargo.toml:

   [dependencies]
   heliosdb-lite = "0.1.0-beta"

2. Run:

   cargo update
   cargo build --release

3. Data format is compatible (no migration needed)

API Stability

Beta Stability Guarantees:

• Core API (EmbeddedDatabase) is stable
• SQL syntax is stable (PostgreSQL compatible)
• Data format is forward-compatible
• Configuration format is stable

May Change Before v1.0:

• Internal APIs (marked as pub(crate))
• Experimental features (documented as such)
• Performance tuning parameters

---

Release Checklist

• All tests passing (142/142, 100%)
• Documentation complete (API docs + user guides)
• Examples validated (8 examples)
• CHANGELOG.md created
• Version bumped to 0.1.0-beta
• GitHub release created
• Published to crates.io
• Announcements posted (HN, Reddit, community)

---

Status: ✅ Ready for beta launch Next Release: v0.2.0 (targeting remaining 10% + Phase 2 features)