---
title: "HeliosDB-Lite v3.4.0 Release Notes"
---

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

```sql
-- 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):

```sql
-- 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:

```sql
-- 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](/docs/lite/getting-started/installation/)), then restart the server on the
existing data directory:

```bash
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

---

## Links

- [HeliosDB Lite product page](https://www.heliosdb.com/lite.html)
- [Previous Release (v3.3.0)](https://www.heliosdb.com/docs/lite/releases/v33/release_notes_v33/)