---
title: "Deployment Modes"
---

# Deployment Modes

HeliosDB-Lite supports multiple deployment modes to fit your use case.

## Embedded Mode (Default)

Run the database in-process, similar to SQLite: the engine lives inside the
application and reads and writes a local data directory. The `heliosdb-lite
repl` shell is the quickest way to try it:

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

Embedding Lite in your own application is covered by the licensed source
distribution; contact [sales@heliosdb.com](mailto:sales@heliosdb.com).

**Best for:**

- Desktop applications
- Mobile apps
- Edge devices
- Single-process services
- Testing

**Characteristics:**

- Zero network overhead
- Single-process access
- File or memory storage
- Fastest performance

## Server Mode

Run as a PostgreSQL-compatible network server.

### Start Server

```bash
# The server refuses to start without a REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Start with default settings (PostgreSQL wire on 127.0.0.1:5432, REST on 8080)
heliosdb-lite start --data-dir ./data

# With a custom PostgreSQL port and REST port
heliosdb-lite start --data-dir ./data --port 5433 --http-port 8081
```

### Connect with PostgreSQL Clients

```bash
psql -h 127.0.0.1 -p 5432 -U postgres
```

```python
import psycopg  # pip install "psycopg[binary]"
conn = psycopg.connect("host=127.0.0.1 port=5432 user=postgres")
```

The default `--auth trust` is for local development only. Before you bind to
another address with `--listen`, start with `--auth scram-sha-256 --password ...`;
see the [authentication guide](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/).

**Best for:**

- Multi-client access
- Production deployments
- Existing PostgreSQL tooling
- Network-accessible databases

**Characteristics:**

- PostgreSQL wire protocol v3.0
- Multi-client connections
- REST API available
- Standard tooling compatible

## In-Memory Mode

Store all data in RAM for maximum performance.

```bash
# In-memory REPL
heliosdb-lite repl --memory

# In-memory server (HELIOSDB_JWT_SECRET exported as above)
heliosdb-lite start --memory
```

**Best for:**

- Testing
- Caching layers
- Ephemeral data
- Development

**Characteristics:**

- Fastest read/write
- Data is RAM-only by default; add `--dump-on-shutdown` to write a dump when the process stops
- No disk I/O
- Limited by RAM

## Configuration

### File: `heliosdb.toml`

Pass the file with `heliosdb-lite start --config heliosdb.toml`.

```toml
[storage]
path = "./data"
cache_size = 536870912  # 512MB

[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

[encryption]
enabled = false
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }
```

The REST port is set on the command line with `--http-port` (default 8080).

### Environment Variables

```bash
HELIOSDB_JWT_SECRET=...        # required by `heliosdb-lite start` (REST token signing)
HELIOSDB_ENCRYPTION_KEY=...    # read when [encryption] is enabled with the default key source
RUST_LOG=info                  # log level (or start with --verbose for debug output)
```

## Comparison

| Feature | Embedded | Server | In-Memory |
|---------|----------|--------|-----------|
| Multi-client | No | Yes | No |
| Network access | No | Yes | No |
| Persistence | Yes | Yes | No |
| Performance | Fastest | Fast | Fastest |
| PostgreSQL tools | No | Yes | No |
| Resource usage | Low | Medium | RAM-bound |

## Production Recommendations

### For Embedded

- Enable WAL for durability
- Set appropriate cache size
- Use encryption for sensitive data

### For Server

- Use TLS/SSL in production
- Configure max connections
- Set up monitoring
- Use connection pooling

```toml
[server]
tls_enabled = true
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"
max_connections = 200
```

## Next Steps

- [Configuration Reference](https://www.heliosdb.com/docs/lite/user-guide/configuration/)
- [Security Best Practices](https://www.heliosdb.com/docs/lite/resources/security/)