Migration Guide: v2.0 → v2.1

Note (current distribution): HeliosDB Lite is distributed to licensed customers as a source distribution that builds the heliosdb-lite binary. This guide describes the upgrade at the server surface: the heliosdb-lite CLI, the PostgreSQL wire protocol, the REST API and the configuration file. Commands, flags and keys are those of the current binary; see the CLI reference and Installation.

Audience: Operators and developers upgrading a HeliosDB-Lite v2.0 deployment to v2.1 Difficulty: Easy (100% backward compatible) Estimated Time: 15-30 minutes

Summary

v2.1.0 is 100% backward compatible with v2.0:

No database migration required
No SQL changes required
All v2.0 features work unchanged
New features are opt-in only

Migration Checklist:

Back up the data directory
Build and install the new heliosdb-lite binary
(Optional) Test your application
(Optional) Enable new features
(Optional) Update configuration

Time Required: 15 minutes (binary upgrade only) to 30 minutes (with new features)

Quick Migration

Step 1: Back Up and Install the New Binary

Stop every process that has the data directory open (a server or a REPL session), then copy the directory:

cp -r ./mydb ./mydb.backup-$(date +%Y%m%d)

Build the new release from the licensed source distribution:

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

Step 2: Verify (Optional)

Open the existing data directory with the new binary and run a query you know the answer to:

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

SELECT COUNT(*) FROM users;
\version

Expected Result: Everything works exactly as before.

New Features (Optional)

v2.1 adds the following capabilities, all opt-in:

Feature 1: Network Server Mode

Before (v2.0): Embedded only. The database was opened in-process, by an embedding application or by the REPL.

After (v2.1): The same data directory can also be served over the PostgreSQL wire protocol:

# Required: the server signs REST API tokens with this secret and will not start without it
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

heliosdb-lite start --data-dir ./mydb --listen 127.0.0.1 --port 5432

psql -h 127.0.0.1 -p 5432 -U postgres

start also serves the REST API on --http-port (default 8080). Use one process per data directory: stop the server before you open the directory with heliosdb-lite repl.

Impact: None if you don’t use it. In-process use works unchanged.

Feature 2: Query Optimizer

Before (v2.0): No automatic optimization

-- Queries run as-is
SELECT name FROM (SELECT * FROM users) WHERE age > 18;

After (v2.1): Automatic optimization

-- Same query, optimized automatically:
SELECT name FROM (SELECT * FROM users) WHERE age > 18;
-- filters pushed down, unused columns removed
-- Result: 2-10x faster execution

Use EXPLAIN to see the plan the optimizer chose:

EXPLAIN SELECT name FROM (SELECT * FROM users) WHERE age > 18;

Impact:

Positive: Queries run 2-10x faster automatically
No SQL Changes: Works transparently
Can Disable Pushdown: If needed (see Configuration Changes)

Feature 3: SSL/TLS Support

Before (v2.0): No network mode, SSL not applicable

After (v2.1): TLS on the PostgreSQL port. Pass a PEM certificate and key together:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

heliosdb-lite start --data-dir ./mydb --listen 0.0.0.0 \
  --tls-cert certs/server.crt --tls-key certs/server.key

psql "host=db.example.com port=5432 user=postgres sslmode=require"

The server offers TLS and still accepts clients that connect without it, so require TLS in the clients (sslmode=require or stricter). See SSL/TLS configuration.

Impact: Only applies if using network server mode.

Feature 4: SCRAM-SHA-256 Authentication

Before (v2.0): No network mode, auth not applicable

After (v2.1): Password authentication on the PostgreSQL port:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

heliosdb-lite start --data-dir ./mydb \
  --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD"

--auth accepts trust (the default, for local development only), password, md5 and scram-sha-256. Every method except trust needs --password, which sets the password of the postgres and helios logins.

Impact: Only applies if using network server mode.

Configuration Changes

Configuration File

Pass a configuration file with heliosdb-lite start --config <path>. Every section is optional; a flag on the command line overrides the matching key. The keys related to this release in the current binary:

[server]
listen_addr = "127.0.0.1"   # --listen
port = 5432                 # --port
max_connections = 100

[optimizer]
# Storage-level filter pushdown. Set to false to evaluate filters row by row.
# Override per session with: SET enable_predicate_pushdown = off;
enable_predicate_pushdown = true

TLS and authentication are set with the start flags --tls-cert, --tls-key, --auth and --password; the current binary does not read them from the configuration file. There is no enabled switch for server mode: heliosdb-lite start runs the server.

Default Behavior: Without a configuration file, the built-in defaults apply (loopback listener on port 5432, trust authentication, no TLS). See Configuration for every section.

API Changes

No Breaking Changes

All v2.0 SQL works unchanged. New capabilities are additive only.

New Interfaces (Optional to Use)

PostgreSQL Protocol

Served by heliosdb-lite start on --port (default 5432), with the TLS and authentication flags shown above. Any PostgreSQL client or driver connects to it.

Query Optimizer

Automatic for every query. Inspect plans with EXPLAIN; turn off storage-level pushdown with SET enable_predicate_pushdown = off or the [optimizer] key above.

Applications that embed HeliosDB Lite in-process: embedded API change (licensed source distribution).

Performance Impact

Query Performance

v2.0 Baseline:

Simple SELECT: ~3.5ms
Complex JOIN: ~120ms
Time-travel: ~450ms

v2.1 Performance:

Simple SELECT: ~1.2ms (2.9x faster)
Complex JOIN: ~15ms (8x faster)
Time-travel: ~4.2ms (107x faster)

Impact: Automatically faster in v2.1, no SQL changes needed.

Memory Usage

v2.1 Improvements:

Query execution: 60-80% less memory (optimizer)
Vector index: Same as v2.0 (unchanged)
Overall: 40-60% reduction in typical workloads

Impact: Lower memory usage automatically.

Storage

v2.0: Compression available but manual v2.1: Compression applied automatically

Impact: Same compression ratios, better integration.

Testing Your Migration

Recommended Test Plan

Install the New Binary
Terminal window
```
cd heliosdb-lite
cargo build --release
```

Run Your Existing Queries

heliosdb-lite repl --data-dir ./mydb
# Expected: your queries return the same results as on v2.0

Run Your Application

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb
# Expected: your application connects on port 5432 and works as on v2.0

Benchmark (Optional)

psql -h 127.0.0.1 -p 5432 -U postgres -c '\timing on' -f your-queries.sql
# Expected: 2-10x faster than v2.0

Try New Features (Optional)
- Test server mode
- Verify SSL/TLS
- Test SCRAM auth
- Check plans with EXPLAIN

Potential Issues

Issue 1: Server Does Not Start

Symptom: heliosdb-lite start exits at startup

Solution:

# The server needs a REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Either --data-dir or --memory is required; --tls-cert and --tls-key go together
heliosdb-lite start --data-dir ./mydb

Issue 2: Performance Regression

Symptom: Queries slower after upgrade (very unlikely)

Cause: Optimizer overhead for trivial queries

Solution: Compare the plan with storage-level pushdown on and off for the affected query:

EXPLAIN SELECT ...;
SET enable_predicate_pushdown = off;
EXPLAIN SELECT ...;
RESET enable_predicate_pushdown;

Keep the optimizer on in general: its benefit outweighs its planning cost for all but trivial queries.

Issue 3: TLS Certificate Errors

Symptom: SSL connections fail

Cause: Self-signed certificates not trusted

Solution:

# Use sslmode=require instead of verify-full for testing
psql "sslmode=require host=localhost port=5432"

# Or: Install CA certificate in system trust store (production)

Updated Documentation

New Guides

PostgreSQL Protocol Quick Start
SSL/TLS Configuration Guide
SCRAM Authentication Guide
Query Optimizer Guide
Integration Testing Guide

Updated Guides

README.md - Server mode examples
CLI Reference - start flags
Examples - 5+ new examples

Location: https://www.heliosdb.com/docs/lite/

Migration Scenarios

Scenario 1: Existing Data Directory, Same Usage

Current (v2.0): The database is opened in-process.

Migration: Back up the data directory, install the v2.1 binary, open the directory as before. No data conversion.

Benefit: Queries 2-10x faster automatically.

Scenario 2: Add Network Access

Current (v2.0): Embedded only

After (v2.1):

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --listen 0.0.0.0 --port 5432 \
  --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD"

Benefit: Clients can now connect via psql, Python, Node.js, etc.

Scenario 3: Add SSL/TLS

Current: No encryption

After:

# Self-signed certificate for testing; use a CA-signed certificate in production
openssl req -x509 -newkey rsa:4096 -nodes -days 365 \
  -keyout certs/server.key -out certs/server.crt -subj "/CN=localhost"

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --listen 0.0.0.0 \
  --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD" \
  --tls-cert certs/server.crt --tls-key certs/server.key

Benefit: Encrypted connections between clients and the server.

Migration Checklist

Getting Help

Resources

Documentation: https://www.heliosdb.com/docs/lite/
Migration support: support@heliosdb.com
Community: support@heliosdb.com
Email: support@heliosdb.com

Common Questions

Q: Do I need to migrate my database files? A: No, v2.1 reads v2.0 databases directly.

Q: Will my queries break? A: No, all v2.0 SQL works unchanged.

Q: Should I enable the optimizer? A: It is on by default and makes queries 2-10x faster.

Q: Do I need to use server mode? A: No, in-process use works as before.

Q: Is SSL/TLS required? A: Only if using server mode in production.

Before & After Comparison

Feature	v2.0	v2.1	Impact
Embedded Mode	✓	✓	Unchanged
Network Server	✗	✓	New feature
Query Speed	Baseline	2-10x faster	Automatic
Memory Usage	Baseline	40-60% less	Automatic
SSL/TLS	✗	✓	Opt-in
Authentication	✗	✓	Opt-in
Backward Compat	N/A	100%	No changes needed

Migration Difficulty: 1 of 5 Time Required: 15-30 minutes

Version: 2.1.0