Deployment Modes

Deployment Modes

HeliosDB Nano 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_nano::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-nano --server ./data

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

# With REST API
heliosdb-nano --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-nano 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

• Configuration Reference
• Security Best Practices