---
title: "Migration Guide: v2.0 → v2.1"
---

# 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](/docs/lite/reference/cli/) and
> [Installation](/docs/lite/getting-started/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:

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

Build the new release from the licensed source distribution:

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

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

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

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

```bash
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
```sql
-- Queries run as-is
SELECT name FROM (SELECT * FROM users) WHERE age > 18;
```

**After (v2.1)**: Automatic optimization
```sql
-- 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:

```sql
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](#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:

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

```bash
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](/docs/lite/guides/postgresql_ssl_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:

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

```toml
[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](/docs/lite/user-guide/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

1. **Install the New Binary**
   ```bash
   cd heliosdb-lite
   cargo build --release
   ```

2. **Run Your Existing Queries**
   ```bash
   heliosdb-lite repl --data-dir ./mydb
   # Expected: your queries return the same results as on v2.0
   ```

3. **Run Your Application**
   ```bash
   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
   ```

4. **Benchmark (Optional)**
   ```bash
   psql -h 127.0.0.1 -p 5432 -U postgres -c '\timing on' -f your-queries.sql
   # Expected: 2-10x faster than v2.0
   ```

5. **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**:
```bash
# 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:

```sql
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**:
```bash
# 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](/docs/lite/reference/cli/) - `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)**:
```bash
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**:
```bash
# 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

- [ ] **Read release notes** - RELEASE_NOTES_v2.1.0.md
- [ ] **Back up the data directory** - With every process that opens it stopped
- [ ] **Build the new binary** - `cargo build --release` in the source distribution
- [ ] **Open the existing data** - `heliosdb-lite repl --data-dir ...`
- [ ] **Test application** - Verify everything works
- [ ] **Check performance** - Should be faster
- [ ] **(Optional) Enable server mode** - `heliosdb-lite start`
- [ ] **(Optional) Configure SSL/TLS** - `--tls-cert` and `--tls-key`
- [ ] **(Optional) Set up authentication** - `--auth scram-sha-256 --password ...`
- [ ] **(Optional) Review plans** - `EXPLAIN`
- [ ] **Update documentation** - Note any configuration changes
- [ ] **Deploy** - Roll out to production

---

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