HeliosDB vs PostgreSQL

PostgreSQL is the gold standard for relational databases. HeliosDB-Lite brings PostgreSQL's SQL dialect and wire protocol to embedded deployments -- without the operational overhead.

---

Quick Comparison

Feature	PostgreSQL	HeliosDB-Lite
Deployment	Server process	Embedded library OR server
Configuration	Extensive tuning	Zero-config
Operations	DBA required	Self-managing
SQL Compatibility	Native	95%+ compatible
Wire Protocol	Native	Compatible
Vector Search	pgvector extension	Built-in
Encryption	pgcrypto extension	Built-in TDE + ZKE
Database Branching	No	Yes
Time-Travel	No	Yes
Row-Level Security	Yes	Yes
JSONB	Yes	Yes
Window Functions	Yes	Yes

---

What You Keep

Full PostgreSQL compatibility:

• SQL dialect -- Same queries work in both
• Wire protocol -- Same clients, drivers, ORMs
• JSONB -- Full JSON path queries
• Window functions -- OVER, PARTITION BY, etc.
• CTEs -- WITH queries
• Row-Level Security -- Same policies

-- These queries work identically in both:

-- CTEs
WITH active_users AS (
    SELECT user_id FROM orders
    WHERE order_date > NOW() - INTERVAL '30 days'
    GROUP BY user_id
)
SELECT * FROM users WHERE id IN (SELECT user_id FROM active_users);

-- Window functions
SELECT
    *,
    ROW_NUMBER() OVER (PARTITION BY category ORDER BY price DESC) AS rank
FROM products;

-- JSONB
SELECT data->'address'->>'city' FROM users WHERE data @> '{"active": true}';

-- RLS
CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.tenant_id')::int);

---

What You Gain

1. Zero-Config Embedded Deployment

// PostgreSQL requires:
// - Install PostgreSQL
// - Configure postgresql.conf
// - Create database
// - Manage connections
// - Handle upgrades

// HeliosDB-Lite:
let db = HeliosDB::open("myapp.db")?;  // That's it.

2. No Operational Overhead

Task	PostgreSQL	HeliosDB-Lite
Installation	Package manager + config	cargo add heliosdb-lite
Backup	pg_dump + storage	Copy file
Upgrades	Careful migration	Replace binary
Monitoring	External tools	Built-in
Scaling	Replicas, pg_bouncer	HeliosProxy included

3. Built-in Vector Search

-- PostgreSQL: Install and configure pgvector extension
CREATE EXTENSION vector;

-- HeliosDB-Lite: Built-in, optimized
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(768)  -- Native type
);

-- 384x compression with Product Quantization
-- Not available in pgvector
ALTER TABLE documents
ALTER COLUMN embedding SET STORAGE COMPRESSED(pq);

4. Database Branching

What PostgreSQL can't do:

-- Create isolated environment for testing
CREATE BRANCH staging FROM main;
USE BRANCH staging;

-- Make changes, run tests
ALTER TABLE users ADD COLUMN preferences JSONB;

-- Merge when ready
MERGE BRANCH staging INTO main;

-- Or discard
DROP BRANCH staging;

5. Time-Travel Queries

-- Query historical data without backups
SELECT * FROM orders
AS OF TIMESTAMP '2026-01-25 09:00:00'
WHERE status = 'pending';

-- Compare versions
SELECT
    current.balance,
    historical.balance,
    current.balance - historical.balance AS change
FROM accounts current
JOIN accounts AS OF TIMESTAMP '2026-01-01' historical
    ON current.id = historical.id;

6. Hybrid Architecture

// Same codebase, multiple deployment modes

// Development: embedded
let db = HeliosDB::embedded("dev.db")?;

// Testing: in-memory
let db = HeliosDB::in_memory()?;

// Production: server mode
let db = HeliosDB::server(ServerConfig {
    host: "0.0.0.0",
    port: 5432,
})?;

// All use the same API

---

When to Choose PostgreSQL

PostgreSQL might be better if you need:

• Stored procedures (PL/pgSQL, PL/Python)
• Foreign data wrappers (query external databases)
• Table inheritance (native support)
• Full text search (ts_vector, ts_query)
• Very large scale (> 10TB single instance)
• Existing PostgreSQL ecosystem (extensions, tools)

---

Migration Path

Schema Migration

Most PostgreSQL schemas work unchanged:

-- This PostgreSQL schema works in HeliosDB-Lite
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,
    data JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    user_id INT REFERENCES users(id),
    items JSONB NOT NULL,
    total DECIMAL(10,2),
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_orders_user ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_orders_data ON orders USING gin(items);

Data Migration

# Export from PostgreSQL
pg_dump -h postgres-server -d mydb -F p -f export.sql

# Import to HeliosDB-Lite
heliosdb-lite import --input export.sql --database myapp.db

Connection String Change

# PostgreSQL
engine = create_engine("postgresql://user:pass@server:5432/db")

# HeliosDB-Lite (server mode)
engine = create_engine("postgresql://user:pass@localhost:5432/db")

# HeliosDB-Lite (embedded mode)
engine = create_engine("heliosdb:///path/to/db")

---

Feature Comparison: Real-World Scenarios

Scenario 1: SaaS Application

Requirement	PostgreSQL	HeliosDB-Lite
Multi-tenancy	RLS + manual isolation	RLS + built-in quotas
Development staging	Clone database (slow)	Branch (instant)
Audit trail	Custom triggers	Built-in time-travel
Encryption	pgcrypto extension	Native TDE
Connection pooling	PgBouncer (separate)	HeliosProxy (built-in)

Scenario 2: AI Application

Requirement	PostgreSQL	HeliosDB-Lite
Vector storage	pgvector extension	Native
Vector compression	Not available	384x PQ
Hybrid search	Complex setup	Single query
Embedding updates	Slow	Fast bulk load
Semantic caching	Manual	HeliosProxy built-in

Scenario 3: Desktop Application

Requirement	PostgreSQL	HeliosDB-Lite
Deployment	Server installation	Embed in app
User setup	Required	None
Data portability	Export/import	Copy file
Offline support	No	Yes
Update process	Complex	Replace binary

---

Performance Comparison

Write Performance

Operation	PostgreSQL	HeliosDB-Lite
Single INSERT	~30K/s	~45K/s
Bulk INSERT	~200K/s	~700K/s
COPY command	~500K/s	~900K/s

Read Performance

Operation	PostgreSQL	HeliosDB-Lite
Point lookup	~80K/s	~450K/s
Range scan	~500K/s	~1.2M/s
Aggregation	~400K/s	~2M/s (SIMD)
Vector search	~1K QPS (pgvector)	~3K QPS

Note: HeliosDB-Lite benefits from embedded deployment (no network latency).

---

Deployment Comparison

PostgreSQL Deployment

# docker-compose.yml for PostgreSQL
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  pgbouncer:
    image: pgbouncer/pgbouncer
    environment:
      DATABASE_URL: postgresql://postgres:secret@postgres/db
    ports:
      - "6432:6432"

  app:
    image: myapp
    environment:
      DATABASE_URL: postgresql://pgbouncer:6432/db
    depends_on:
      - pgbouncer

volumes:
  pgdata:

HeliosDB-Lite Deployment

# docker-compose.yml for HeliosDB-Lite
services:
  app:
    image: myapp
    volumes:
      - ./data:/data
    # Database is embedded, no separate service needed

Or simply:

// No Docker, no services, just code
fn main() {
    let db = HeliosDB::open("data/app.db").unwrap();
    // Your application code
}