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:

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

Embedding Lite in your own application is covered by the licensed source distribution; contact 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

# 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

psql -h 127.0.0.1 -p 5432 -U postgres

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.

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.

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

[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

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

[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
• Security Best Practices