Skip to content
HeliosDB HeliosDB Lite

HeliosDB-Lite v3.4.0 Release Notes

Previous Version: v3.3.0

Overview

HeliosDB-Lite v3.4.0 is an Advanced SQL Features Release that extends PostgreSQL compatibility with JSON aggregation, array operations, and enhanced type verification. This release also includes transaction system improvements and comprehensive documentation updates.

Highlights

  • json_agg() Function: PostgreSQL-compatible JSON array aggregation for analytical queries
  • Array Operations: 1-based subscript indexing and || concatenation operator
  • Type Verification: Built-in validation for UUID, Boolean, and BYTEA types
  • Transaction Improvements: Enhanced lock management with RAII pattern
  • Documentation Sync: Fixed broken links and updated version references
  • 100% Backward Compatible: No API changes, drop-in replacement for v3.3.0

New Features

JSON Aggregation

The json_agg() aggregate function allows building JSON arrays from query results:

-- Aggregate user data into JSON array
SELECT json_agg(name) AS user_names FROM users;
-- Result: ["Alice", "Bob", "Charlie"]


-- With ORDER BY support
SELECT json_agg(product ORDER BY price DESC) AS products_by_price
FROM products;


-- Integration with GROUP BY
SELECT department, json_agg(name) AS employees
FROM staff
GROUP BY department;


-- Works with materialized views
CREATE MATERIALIZED VIEW customer_orders AS
SELECT customer_id, json_agg(order_id) AS order_ids
FROM orders
GROUP BY customer_id;

Implementation Details:

  • Full PostgreSQL compatibility for NULL handling
  • Type-safe JSONB output
  • ORDER BY support within aggregation
  • Materialized view integration

Array Operations

Array Subscript Operator

Access array elements using 1-based indexing (PostgreSQL compatible):

-- 1-based indexing
SELECT ARRAY[10, 20, 30, 40, 50][1] AS first_element;
-- Result: 10


SELECT ARRAY[10, 20, 30, 40, 50][3] AS third_element;
-- Result: 30


-- Out-of-bounds returns NULL (safe indexing)
SELECT ARRAY[10, 20, 30][10] AS out_of_bounds;
-- Result: NULL


-- Use in WHERE clauses
SELECT * FROM products WHERE tags[1] = 'featured';

Array Concatenation

Combine arrays using the || operator:

-- Concatenate arrays
SELECT ARRAY[1, 2, 3] || ARRAY[4, 5, 6] AS combined;
-- Result: [1, 2, 3, 4, 5, 6]


-- Type coercion
SELECT ARRAY[1, 2] || ARRAY[3.5, 4.5] AS mixed;
-- Result: [1.0, 2.0, 3.5, 4.5]


-- Dynamic array building
SELECT user_id, favorite_items || recent_items AS all_items
FROM user_preferences;

Type Verification

Enhanced type system validation for:

  • UUID: Format validation for 128-bit identifiers
  • Boolean: Strict true/false validation
  • BYTEA: Binary data type support

Improvements

Transaction System Enhancements

  • RAII Lock Guards: Automatic lock release on transaction commit/rollback
  • Lock Manager Integration: Session-aware locking with deadlock detection
  • Concurrent Write Sets: Lock-free concurrent access to write sets

Documentation Updates

  • Fixed 8 broken documentation links in README.md
  • Updated version references from v3.0 to v3.4.0
  • Synchronized architecture documentation with implementation

Known Issues

Transaction Isolation in Concurrent Scenarios

Issue: There is a known limitation with transaction isolation in concurrent read-modify-write scenarios.

Root Cause: Lost update anomaly in concurrent UPDATE statements. When multiple transactions perform read-modify-write operations on the same row:

  1. Transaction A reads balance = 1000
  2. Transaction B reads balance = 1000 (before A commits)
  3. Transaction A writes balance = 900
  4. Transaction B writes balance = 900 (overwrites A’s result)

Workarounds:

  1. Use application-level optimistic locking with version checks
  2. Use SELECT... FOR UPDATE semantics (planned for future release)
  3. Serialize updates at the application level

Upgrade Guide

From v3.3.0

No action required. v3.4.0 is a drop-in replacement. Build it from the licensed source distribution (HeliosDB Lite is not published on crates.io, PyPI, npm or Docker Hub; see Installation), then restart the server on the existing data directory:

Terminal window
cd heliosdb-lite
cargo build --release
export PATH="$PWD/target/release:$PATH"


# Keep the secret the server already uses: tokens signed with another secret are rejected
export HELIOSDB_JWT_SECRET="<existing secret>"
heliosdb-lite start --data-dir /var/lib/heliosdb

Breaking Changes

None. This release maintains full backward compatibility.

Build Information

  • Binary Size: ~20MB (release build)
  • Rust Version: 1.75+
  • Target: x86_64-unknown-linux-gnu
  • Dependencies: RocksDB 8.10, Arrow 52.2

Contributors

  • HeliosDB Team