Skip to content

Deployment Modes

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

Embedded Mode (Default)

Run the database as an in-process library, similar to SQLite.

use heliosdb_lite::EmbeddedDatabase;

let db = EmbeddedDatabase::new("./data")?;
db.execute("SELECT 1")?;

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

# Start with default settings
heliosdb-lite --server ./data

# With custom port
heliosdb-lite --server ./data --port 5433

# With REST API
heliosdb-lite --server ./data --http-port 8080

Connect with PostgreSQL Clients

# psql
psql -h localhost -p 5432 -d mydb

# Python
import psycopg2
conn = psycopg2.connect("host=localhost port=5432 dbname=mydb")

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.

let db = EmbeddedDatabase::new_in_memory()?;

Or via CLI:

heliosdb-lite --repl :memory:

Best for:

  • Testing
  • Caching layers
  • Ephemeral data
  • Development

Characteristics:

  • Fastest read/write
  • Data lost on shutdown
  • No disk I/O
  • Limited by RAM

Configuration

File: heliosdb.toml

[storage]
path = "./data"
cache_size = 536870912  # 512MB
compression = "zstd"

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

[http]
enabled = true
port = 8080

[encryption]
enabled = false
algorithm = "aes256-gcm"
key_source = { environment = "HELIOSDB_KEY" }

Environment Variables

HELIOSDB_PORT=5432
HELIOSDB_DATA_DIR=./data
HELIOSDB_LOG_LEVEL=info
HELIOSDB_ENCRYPTION_KEY=your-secret-key

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]
ssl_enabled = true
ssl_cert = "/path/to/cert.pem"
ssl_key = "/path/to/key.pem"
max_connections = 200

Next Steps