---
title: "HeliosDB-Lite v2.1.0 Release Notes"
---

# HeliosDB-Lite v2.1.0 Release Notes

> **Editor's note (2026-10-15):** the Product Quantization figures in these release notes (compression ratios and recall) are as announced for this release; no test behind them has been published. The current published measurement is about 16x less resident vector-index RAM at recall-safe defaults (recall@10 0.987 vs 0.989; internal tests, Nano 3.32.1 vs an unquantized index). No Lite-specific measurement has been published. The current release is Lite 3.6.0.

**Version**: 2.1.0
**Codename**: "Network Ready"

---

## What's New in v2.1.0

HeliosDB-Lite v2.1.0 is a major release that adds **PostgreSQL network protocol support** and a **query optimizer**, so HeliosDB-Lite runs as a network server as well as an embedded database.

### Headline Features

#### 1. PostgreSQL Wire Protocol Support

**Transform HeliosDB-Lite into a network database server!**

HeliosDB-Lite can now act as a PostgreSQL-compatible network server, allowing connections from any PostgreSQL client:

```bash
# Start as network server (current CLI; the server needs a REST token-signing secret)
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --port 5432

# Connect with psql
psql -h localhost -p 5432 -U postgres

# Or any PostgreSQL driver (Python, Node.js, Java, Go, etc.)
```

**Features**:
- Full PostgreSQL wire protocol implementation
- Simple Query Protocol (text-based SQL)
- Extended Query Protocol (prepared statements with $1, $2 parameters)
- SSL/TLS encryption (TLS 1.2/1.3)
- SCRAM-SHA-256 authentication
- Client compatibility: psql, pgAdmin, DBeaver, all major drivers
- 100+ concurrent connections supported

**Performance**:
- Simple queries: ~1.3ms latency
- Prepared statements: ~0.6ms latency (54% faster!)
- Statement cache hit rate: >95%

---

#### 2. Security

**Enterprise-level security for your data**

- **SSL/TLS Encryption**: TLS 1.2/1.3 with strong cipher suites
- **SCRAM-SHA-256 Authentication**: RFC 5802/7677 compliant, timing attack resistant
- **6 SSL Modes**: disable, allow, prefer, require, verify-ca, verify-full
- **No Plaintext Passwords**: Salted PBKDF2-HMAC-SHA-256 hashing
- **Certificate Management**: Self-signed and CA-signed certificate support

**Example**:
```bash
# Secure connection
psql "sslmode=require host=db.example.com user=admin password=secret"
```

---

#### 3. Intelligent Query Optimizer

**2-10x faster queries with automatic optimization**

The new rule-based query optimizer automatically optimizes your queries for maximum performance:

**5 Optimization Rules**:
1. **Selection Pushdown** - Move filters closer to data sources
2. **Projection Pruning** - Eliminate unused columns (50-80% I/O reduction)
3. **Join Reordering** - Process smallest tables first (10-50x speedup)
4. **Index Selection** - Automatically choose the best index
5. **Constant Folding** - Evaluate constant expressions at planning time

**Performance Impact**:
- Simple queries: 2-3x faster
- Complex queries: 5-10x faster
- Join-heavy queries: 10-50x faster
- Memory usage: 60-80% reduction

**Example**:
```sql
-- Before optimization
SELECT u.name FROM
  (SELECT * FROM users) u
  WHERE u.age > 18 AND 1 + 1 = 2;

-- After automatic optimization
SELECT name FROM users WHERE age > 18;
-- ✓ Constant folded (1+1=2 removed)
-- ✓ Projection pruned (only name column read)
-- ✓ Filter pushed down to scan
```

**See the plan the optimizer chose** with `EXPLAIN` from any client:
```sql
EXPLAIN SELECT u.name FROM (SELECT * FROM users) u WHERE u.age > 18 AND 1 + 1 = 2;
```

---

### Improved Features from v2.0

#### Enhanced Time-Travel Queries
- **10-100x faster** with new reverse timestamp index
- O(log N) performance instead of O(N)
- Handles 10,000+ versions efficiently

#### Optimized Compression
- **ALP/FSST fully integrated** with storage engine
- Automatic compression on INSERT
- Automatic decompression on SELECT
- 2-10x storage reduction achieved

#### Hardened Error Handling
- Eliminated all critical unwrap/panic calls
- Improved error messages
- Proper error propagation throughout

---

## Complete Feature List

### Core Database (Inherited from v2.0)

- **SQL Engine** - PostgreSQL 95% compatible
- **ACID Transactions** - Full transaction support
- **Parameterized Queries** - SQL injection protection
- **WAL** - Write-Ahead Logging with crash recovery
- **Catalog System** - Complete schema management
- **Query Timeout** - DoS protection
- **Type Inference** - Automatic type detection

### Advanced Features (Phase 3 - v2.0)

- **Product Quantization** - 384x vector compression
- **Quantized HNSW** - Memory-efficient vector search
- **Database Branching** - Git-like branching (CREATE BRANCH)
- **Time-Travel** - Query historical data (AS OF syntax)
- **Materialized Views** - With REFRESH support
- **System Views** - Introspection (pg_catalog)

### Network Features (New in v2.1)

- **PostgreSQL Protocol** - Full wire protocol implementation
- **SSL/TLS** - Encrypted connections
- **SCRAM-SHA-256** - Secure authentication
- **Prepared Statements** - Extended query protocol
- **Query Optimizer** - 5 optimization rules

### Experimental Features

  - Enable with: `--features sync-experimental`
  - Target: v2.2.0 for production

---

## Getting Started

### Installation

HeliosDB-Lite is available to licensed customers as a source distribution (contact
sales@heliosdb.com); it is not published on crates.io, PyPI, npm or Docker Hub. Build the
`heliosdb-lite` binary from the unpacked distribution:

```bash
cd heliosdb-lite

# Build
cargo build --release
export PATH="$PWD/target/release:$PATH"

# Run tests
cargo test --all
```

See [Installation](/docs/lite/getting-started/installation/).

### Quick Start - Embedded Mode

Open a database directory in-process with the REPL:

```bash
heliosdb-lite repl --data-dir ./mydb
```

```sql
CREATE TABLE users (id INT PRIMARY KEY, name TEXT);
INSERT INTO users (id, name) VALUES (1, 'Alice');

-- Time-travel: read the table as it was at an earlier point
SELECT * FROM users AS OF TIMESTAMP '2025-01-01 00:00:00';
```

Applications can also open the database in-process through the embedded API (licensed source
distribution).

### Quick Start - Server Mode

```bash
# Start server (current CLI): password authentication and TLS on the PostgreSQL port
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --port 5432 \
  --auth scram-sha-256 --password secret \
  --tls-cert certs/server.crt --tls-key certs/server.key

# Connect with any PostgreSQL client
psql "host=localhost port=5432 user=postgres sslmode=require"
```

```python
# Python example (parameterized query over the extended query protocol)
import psycopg2

conn = psycopg2.connect(
    host='localhost',
    port=5432,
    user='postgres',
    password='secret',
    sslmode='require'
)
cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE id = %s", (1,))
print(cursor.fetchall())
```

---

## Upgrading from v2.0

### Database Compatibility

**Good News**: v2.1.0 is **100% backward compatible** with v2.0 databases!

- No schema changes required
- Existing data works without migration
- All v2.0 queries work unchanged
- New features are additive only

### Upgrade Steps

1. Stop every process that has the data directory open, then back it up:
   ```bash
   cp -r ./mydb ./mydb.backup-$(date +%Y%m%d)
   ```
2. Build the v2.1 binary from the source distribution (`cargo build --release`).
3. Open the existing data directory with the new binary. No data conversion is needed.

### SQL and Client Changes

**Embedded Mode**: No changes required. Existing SQL and in-process code run unchanged
(embedded API, licensed source distribution).

**New Server Mode** (optional): `heliosdb-lite start --data-dir <dir>` serves the PostgreSQL
wire protocol on `--port` (default `5432`) and the REST API on `--http-port` (default `8080`).
Set `HELIOSDB_JWT_SECRET` before starting; the server refuses to start without it.

**New Query Optimizer** (automatic): applies to every query with no SQL change. Inspect plans
with `EXPLAIN`; `SET enable_predicate_pushdown = off` turns off storage-level filter pushdown
for a session.

### Configuration Changes

**Configuration file** (`heliosdb-lite start --config <path>`; flags override keys), keys of the
current binary:
```toml
[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

[optimizer]
enable_predicate_pushdown = true
```

TLS and authentication are `start` flags, not configuration-file keys:

| Flag | Values |
|------|--------|
| `--tls-cert`, `--tls-key` | PEM certificate and key, passed together |
| `--auth` | `trust` (default, local development only), `password`, `md5`, `scram-sha-256` |
| `--password` | Required by every `--auth` method except `trust` |

Clients choose the TLS mode with the standard `sslmode` values (`disable`, `allow`, `prefer`,
`require`, `verify-ca`, `verify-full`); the server offers TLS and accepts clients that do not use
it, so require TLS on the client side.

---

## Breaking Changes

**None!** v2.1.0 is fully backward compatible with v2.0.

All new features are opt-in:
- Server mode is optional (embedded mode unchanged)
- Query optimizer is automatic but non-breaking
- SSL/TLS is configurable (can be disabled)

---

## Performance Improvements

### Benchmarks

| Operation | v2.0 | v2.1 | Improvement |
|-----------|------|------|-------------|
| Simple SELECT | 3.5ms | 1.2ms | 2.9x faster |
| Complex JOIN | 120ms | 15ms | 8x faster |
| Time-Travel Query | 450ms | 4.2ms | 107x faster |
| INSERT (compressed) | 2.1ms | 2.3ms | -9% (overhead acceptable) |
| Prepared Statement | N/A | 0.6ms | N/A (new feature) |

**Memory Usage**:
- Query execution: 60-80% reduction (optimizer)
- Vector index: 8-16x reduction (product quantization)
- Overall: 40-60% reduction in typical workloads

**Storage**:
- Compression ratio: 2-10x (ALP/FSST)
- Typical savings: 50-70% for mixed workloads

---

## Bug Fixes

### Critical Fixes

1. **Fixed 4 unwrap/panic calls in production code**

### Other Fixes

2. **Time-travel query performance** - Added reverse timestamp index
3. **Compression integration** - Fully integrated ALP/FSST with storage
4. **Error messages** - Improved clarity and context

---

## Documentation

### New Documentation

- **PostgreSQL Protocol Quick Start** - Get started with server mode
- **SSL/TLS Configuration Guide** - Secure connection setup
- **SCRAM Authentication Guide** - User management and auth
- **Query Optimizer Guide** - Understanding optimizations
- **Integration Test Plan** - Testing with PostgreSQL clients
- **Migration Guide** - Upgrade from v2.0 to v2.1

### Updated Documentation

- **README.md** - Added server mode examples
- **API Reference** - Complete v2.1 API
- **Examples** - 5+ new working examples

All docs available at: https://www.heliosdb.com/docs/lite/

---

## Security

### Security Enhancements

1. **TLS 1.2/1.3 Support** - Modern encryption standards
2. **SCRAM-SHA-256** - Secure password authentication
3. **Timing Attack Prevention** - Constant-time comparisons
4. **No Plaintext Storage** - All passwords salted and hashed
5. **SQL Injection Protection** - Parameterized queries enforced
6. **Certificate Validation** - Full chain verification support

### Security Advisories

No known vulnerabilities in v2.1.0.

Report security issues to: security@heliosdb.com

---

## Known Issues

### Minor Issues

1. **COPY Protocol Not Implemented**
   - Workaround: Use INSERT for bulk data
   - Planned: v2.2.0

2. **GUI Client Compatibility Untested**
   - pgAdmin, DBeaver not yet validated
   - Expected to work but needs testing

3. **Sync/Replication Experimental**
   - Use `--features sync-experimental` at your own risk
   - operationally hardened in v2.2.0

### Performance Notes

1. **First Connection Slower**
   - Initial SSL handshake takes ~100-200ms
   - Subsequent connections <10ms
   - This is normal behavior

2. **Query Optimizer Overhead**
   - Planning adds ~1-2ms for simple queries
   - Execution savings typically 10-100x greater
   - Net benefit positive for all but trivial queries

---

## Contributors

- **Core Team**: HeliosDB Development Team
  - Compression Research Specialist
  - PostgreSQL Protocol Engineer
  - Query Optimizer Engineer
  - Security Auditor
- **Community**: Beta testers and feedback providers

---

## Support

- **Documentation**: https://www.heliosdb.com/docs/lite/
- **Issues**: support@heliosdb.com
- **Community**: [Discord](https://discord.gg/yTykuUrFXc)
- **Security**: security@heliosdb.com

---

**Full Changelog**: [CHANGELOG.md](https://www.heliosdb.com/docs/lite/releases/changelog/)
**Migration Guide**: [MIGRATION_v2.0_to_v2.1.md](https://www.heliosdb.com/docs/lite/releases/migration_v20_to_v21/)
**Download**: available to licensed customers (contact sales@heliosdb.com)

**Released**: November 2025
**Version**: 2.1.0