Skip to content
HeliosDB HeliosDB Nano

HeliosDB Nano v3.3.0 Release Notes

HeliosDB Nano v3.3.0 Release Notes

Release Date: December 13, 2025 Previous Version: v3.2.0

Overview

HeliosDB Nano v3.3.0 is a Code Quality & Stability Release focused on eliminating potential runtime panics and improving error handling throughout the production codebase. This release ensures panic-free operation in all critical paths.

Highlights

  • Zero Critical Panics: All P0 and P1 panic paths in production code have been eliminated
  • Graceful Error Recovery: New patterns for handling edge cases without crashing
  • Improved Safety Guarantees: Documented safety invariants throughout the codebase
  • 100% Backward Compatible: No API changes, drop-in replacement for v3.2.0

Changes

P0 - Critical Fixes

Mutex Poisoning Recovery (src/sql/realtime_explain.rs)

  • Before: get_stats() would panic if mutex was poisoned (thread panic while holding lock)
  • After: Gracefully recovers data from poisoned mutex and marks execution state as Failed
  • Impact: Query execution tracking never panics, even in catastrophic scenarios
// New recovery pattern
pub fn get_stats(&self) -> ExecutionStats {
    match self.stats.lock() {
        Ok(stats) => stats.clone(),
        Err(poisoned) => {
            let mut stats = poisoned.into_inner().clone();
            stats.state = ExecutionState::Failed;
            stats
        }
    }
}

P1 - High Priority Fixes

OpenAPI Error Responses (src/api/openapi/mod.rs)

  • Before: Nested .expect() calls could panic on response building failures
  • After: New minimal_error_response() helper with Response::default() fallback
  • Impact: API documentation endpoints never panic

Connection Pool Safety (src/protocols/adapters/pool.rs)

  • Before: .expect() on Option access that was “guaranteed” by convention
  • After: Documented unreachable!() with explicit safety reasoning
  • Impact: Better code documentation, same runtime safety (Rust ownership guarantees)

SCRAM Authentication (src/network/auth.rs)

  • Before: Zero iterations would cause panic
  • After: Falls back to minimum 4096 iterations (SCRAM-SHA-256 recommended minimum)
  • Impact: Authentication never panics on invalid input

Base64 Encoding (src/network/auth.rs)

  • Before: .expect() on encoding operations
  • After: unwrap_or_default() with documented safety (Base64 to Vec cannot fail)
  • Impact: Authentication encoding never panics

Reviewed - No Changes Needed

Oracle SQL Translator (src/protocols/oracle/translator.rs)

  • Status: All regex patterns are compile-time string literals using OnceLock<Regex>
  • Verdict: Safe - patterns are valid by inspection, fails deterministically at first use
  • Note: .expect() messages document why patterns are valid

Compile-Time Constants

  • src/storage/statistics.rs:232 - NonZeroUsize::new(100) is always Some
  • src/protocol/postgres/auth.rs:334 - NonZeroU32::new(4096) is always Some
  • src/sql/system_views.rs:111 - NonZeroU32::new(100) is always Some
  • Verdict: Safe - these are compile-time guarantees

Technical Debt Status

CategoryBefore v3.3.0After v3.3.0
P0 Critical Panics10
P1 High Priority60
P3 Safe/Reviewed58 (all documented)
Test Code (P2)~15 modules~15 modules (acceptable)

See docs/TECHNICAL_DEBT_CHECKLIST.md for full tracking.

Error Handling Patterns Introduced

1. Mutex Poisoning Recovery

Recover data from poisoned mutexes instead of panicking:

match mutex.lock() {
    Ok(guard) => /* normal path */,
    Err(poisoned) => {
        let data = poisoned.into_inner();
        // Mark as failed, continue operating
    }
}

2. Fallback Response Pattern

Guaranteed-safe HTTP response construction:

fn minimal_error_response() -> Response {
    Response::builder()
        .status(StatusCode::INTERNAL_SERVER_ERROR)
        .body(Body::empty())
        .unwrap_or_else(|_| Response::default())
}

3. Safe Default Pattern

Compile-time guaranteed defaults:

const MIN_ITERATIONS: NonZeroU32 = match NonZeroU32::new(4096) {
    Some(n) => n,
    None => unreachable!(),
};
let iterations = NonZeroU32::new(input).unwrap_or(MIN_ITERATIONS);

Upgrade Guide

From v3.2.0

No action required. v3.3.0 is a drop-in replacement:

Terminal window
# Download new binary
wget https://releases.heliosdb.com/v3.3.0/heliosdb-nano-linux-amd64.tar.gz
tar xzf heliosdb-nano-linux-amd64.tar.gz


# Replace existing binary
sudo cp heliosdb-nano /usr/local/bin/


# Verify
heliosdb-nano repl

Breaking Changes

None. This is a stability release with no API changes.

Build Information

  • Binary Size: ~20MB (release build)
  • Rust Version: 1.75+
  • Target: x86_64-unknown-linux-gnu
  • Checksum: See releases/v3.3.0/heliosdb-nano.sha256

What’s Next (v3.4.0)

  • Persistent server mode
  • Distributed query execution
  • Enhanced CDC streaming
  • Performance optimizations

Contributors

  • HeliosDB Team