HeliosDB-Lite v3.2 Release Notes

Version: 3.2.0

Overview

HeliosDB-Lite v3.2 adds multi-tenancy infrastructure with Row-Level Security (RLS), Tenant Quota Enforcement, and Change Data Capture (CDC) for data migration. This release focuses on security isolation and resource management for SaaS deployments.

What’s New

1. Row-Level Security (RLS) Framework

Comprehensive security framework for data isolation in shared environments:

Features:

Type-Safe Policy System: Policies with USING and WITH CHECK expressions
RLS Commands: SELECT, INSERT, UPDATE, DELETE, ALL command types
Database Execution Hooks: Automatic RLS enforcement in DML operations
Tenant Context Management: Per-request user/role/tenant tracking
Policy Registration: Simple API for policy creation and retrieval

Architecture:

Application → Tenant Context → Database Layer → RLS Evaluation → Execution

Security Guarantees:

Data isolation by tenant via RLS policies
Automatic policy enforcement in UPDATE/DELETE/INSERT
Defense-in-depth: RLS AND-ed with WHERE clauses
Type-safe policy definition prevents injection

Known Limitations:

Expression evaluation deferred to v3.3
SELECT queries require application-level filtering
Single policy per table (multiple policies use first match)

2. Tenant Quota Enforcement System

Real-time resource management system for multi-tenant deployments:

Features:

Connection Limiting: Enforce max concurrent connections per tenant
Storage Quotas: Track and limit storage usage (bytes)
QPS Throttling: Rate-limit queries per second with sliding windows
Tier Configuration: Pre-configured plan templates (Free/Starter/Pro/Enterprise)
Monitoring APIs: Real-time quota tracking and metrics

Architecture:

Operation Request → Quota Check (O(1)) → Allow/Reject → Record Metrics

Performance:

Connection Check: O(1) HashMap lookup
Storage Update: O(1) atomic write
QPS Recording: O(1) counter increment
Memory per Tenant: < 1 KB

Default Limits:

Free:        10 GB storage, 5 connections, 100 QPS
Starter:     50 GB storage, 20 connections, 500 QPS
Pro:        500 GB storage, 100 connections, 5000 QPS
Enterprise: 10 TB storage, 1000 connections, 50000 QPS

Known Limitations:

Quotas reset on restart (in-memory only)
Single-process instance (no coordination)
QPS window not reset by background task

3. RETURNING Clause Framework

Support for PostgreSQL-compatible RETURNING clause in DML operations:

Features:

Logical Plan Support: RETURNING for INSERT/UPDATE/DELETE
Parser Integration: RETURNING columns parsed from SQL
Execution Hooks: Framework ready for tuple capture in v3.3

Supported Syntax:

INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')
RETURNING id, name, email;

UPDATE users SET email = 'newalice@example.com' WHERE id = 1
RETURNING id, old_email, new_email;

DELETE FROM users WHERE id = 1
RETURNING id, name;

Architecture:

SQL → Parser (extract RETURNING) → Logical plan → Executor (capture tuples)

4. Change Data Capture (CDC) for Tenant Migration

Infrastructure for tenant-to-tenant data migration:

Features:

Change Events: Capture all INSERT/UPDATE/DELETE operations
CDC Log: Ordered, immutable change sequence per tenant
Migration State Machine: Pending → Snapshotting → Replicating → Verifying → Completed
Consistency Verification: Checksum-based validation
Replication Targets: Track multiple migrations per source tenant
Lifecycle Control: Pause, resume, rollback migration at any stage

Architecture:

Source Tenant Data
    ↓
Record Change Events
    ↓
CDC Log (per tenant)
    ↓
Start Migration
    ├─ Stage 1: Snapshot
    ├─ Stage 2: Replicate Changes
    ├─ Stage 3: Verify Consistency
    └─ Stage 4: Complete or Rollback
        ↓
Target Tenant Data

Performance:

Event Recording: O(1) monotonic ID + append
Progress Tracking: O(1) field update
Consistency Check: O(1) checksum comparison
Log Retrieval: O(n) clone of events

Known Limitations:

Manual change-event recording required (v3.3 adds hooks)
Logs lost on restart (v3.3 adds persistence)
No automatic checksum computation (v3.3 adds helpers)
Single-process scope (v3.4 adds distribution)

Breaking Changes

None

All v3.2 features are:

Opt-in: Existing code unaffected
Backward compatible: No API changes to existing methods
Non-breaking: new parameters are optional

Deprecations

None planned

All existing APIs remain stable through v3.2 and beyond.

Migration Guide for Users

For Single-Tenant Applications

Impact: Zero impact

RLS, Quota, and CDC are opt-in
Existing queries and operations unaffected
No performance degradation
Default: features disabled

For Multi-Tenant SaaS Applications

Prepare for CDC in v3.3:

// v3.2: Framework ready, manual integration
// v3.3: Automatic hooks will be added

// For now, applications can:
// 1. Monitor DML operations
// 2. Plan migration workflows
// 3. Prepare target tenants

Performance Impact

Compilation

Binary Size: +0.2%
Build Time: +3% (additional type checking)

Runtime (When Features Disabled)

Query Execution: No overhead
Memory: +200 bytes
Latency: < 1 microsecond (feature flag check)

Runtime (When Features Enabled)

Measured on representative fixtures; reproduce on your own hardware.

Operation	Latency	Throughput
RLS policy check	< 10 µs	100k+/sec
Quota check	< 5 µs	200k+/sec
Record change event	< 100 µs	10k+/sec
Get CDC log	< 1 ms	1k+/sec

Known Issues

v3.2 Framework Level

RLS SELECT not supported: Use application-level filtering
- Workaround: Manual WHERE clause + tenant context
- Fix: v3.3 expression evaluation
CDC logs not persistent: Lost on restart
- Workaround: Implement application-level persistence
- Fix: v3.3 RocksDB integration
Manual change recording: No automatic hooks
- Workaround: Record change events from your application’s DML paths
- Fix: v3.3 automatic integration
Quota window reset: No background task
- Workaround: Reset the QPS window manually
- Fix: v3.3 background task

Testing

How to Verify Installation

# Check version on a running server (HTTP port); in the REPL use the \version meta-command
curl http://127.0.0.1:8080/version
# Should return: {"name":"HeliosDB-Lite","version":"3.2.0","api_version":"v1"}

# Verify features compile
cargo build --all-features

# Run embedded tests
cargo test --lib

Dependencies

New Dependencies

None - All features use existing dependencies

Dependency Versions

parking_lot: 0.12+ (RwLock)
uuid: 1.0+ (TenantId)
chrono: 0.4+ (Timestamps)
serde: 1.0+ (JSON serialization)

Upgrade Instructions

From v3.1 to v3.2

Backup your data (no schema changes)
Unpack the v3.2 source distribution (available to licensed customers) next to the v3.1 one, so you can roll back.
Recompile:
Terminal window
```
cargo build --release
```
No migration required: v3.2 is fully backward compatible
Optional: Enable features in your application code

Rollback Instructions

If needed, revert to v3.1: stop the server, then start the v3.1 binary you kept (or rebuild it from the v3.1 source distribution with cargo build --release) on the same data directory.

No data changes needed - v3.2 framework is non-destructive.

Support & Feedback

Reporting Issues

Support: support@heliosdb.com

Include:

HeliosDB version (GET /version on the HTTP port, or \version in the REPL)
Feature being used (RLS/Quota/CDC)
Reproduction steps
Error messages

Feature Requests

Discuss on Discord: support@heliosdb.com

Vote on priority features for v3.3.

License

HeliosDB-Lite remains under the same license as v3.1. See LICENSE file for details.

Acknowledgments

Thanks to the HeliosDB community for feedback and requirements that shaped v3.2’s design.

What’s Next?

Try v3.2: Explore new RLS, Quota, and CDC capabilities
Provide feedback: Tell us what works and what needs improvement
Plan upgrades: Evaluate v3.2 features for your deployment
Stay tuned: v3.3 brings expression evaluation and persistence

HeliosDB-Lite v3.2.0 - Enterprise Multi-Tenancy, Now Available