HeliosDB Nano vs PostgreSQL

Choose HeliosDB Nano when you want PostgreSQL clients and SQL in an embedded library or a single server binary, with vector search, branching and time-travel queries built into the engine; keep PostgreSQL when you need full semantic compatibility, row-level security enforced for network clients, PL/pgSQL procedures, extensions or foreign data wrappers, or its long production record.

PostgreSQL is the gold standard for relational databases. HeliosDB Nano brings the PostgreSQL wire protocol and a large documented subset of its SQL to embedded and single-binary server deployments. That is client compatibility, not semantic parity: read the known limitations before you migrate.

---

Quick Comparison

---

What You Keep

Client compatibility and a large SQL subset — not full semantic parity (FAQ):

• SQL dialect -- Most DDL and queries run unchanged; test rather than assume
• Wire protocol -- psql, pgAdmin, DBeaver and most PostgreSQL drivers and ORMs
• JSONB -- JSON operators such as ->, ->> and @>
• Window functions -- OVER, PARTITION BY, etc.
• CTEs -- WITH queries

-- These queries run on both (collation and NULL ordering can differ):

-- 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}';

-- Not yet on both: SQL CREATE POLICY is planned in Nano. Today RLS
-- policies are defined through the embedded API or the REPL and are
-- not enforced for wire or REST clients

---

What You Gain

1. Embedded Deployment

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

// HeliosDB Nano, embedded (a persistent data directory):
let db = EmbeddedDatabase::new("./myapp-data")?;

2. Operations Compared

3. Built-in Vector Search

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

-- HeliosDB Nano: vector type and HNSW in the default build
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(768)  -- Native type
);

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- Product Quantization, also in the default build
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (quantization = 'product');

Product Quantization is in Nano's default build: add WITH (quantization='product') to an HNSW index. Indexes are unquantized unless you ask, and durable restart-surviving PQ-HNSW indexes need the vector-persist build (Product Quantization guide). Memory savings and recall for Product Quantization are measured on representative fixtures on the benchmarks page.

4. Database Branching

Copy-on-write branches of the whole database, created with SQL. A merge is last-writer-wins with no conflict detection, so for anything conflict-sensitive, discard the branch and re-apply the validated SQL (merging branches):

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

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

-- Merge (last-writer-wins, no conflict report)
MERGE DATABASE BRANCH staging INTO main;

-- Or discard
DROP DATABASE BRANCH staging;

5. Time-Travel Queries

-- Read past versions within the retention window (not a backup)
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. Embedded, In-Memory or Server

// One engine; the mode is chosen when you open or start it

// Development: embedded, persistent data directory
let db = EmbeddedDatabase::new("./dev-data")?;

// Tests: in-memory, discarded when the process exits
let db = EmbeddedDatabase::new_in_memory()?;

// Production: stop the embedded process, then serve the same directory
//   $ heliosdb-nano start --data-dir ./dev-data --port 5432
// and connect with any PostgreSQL client (embedded calls become client calls)

Moving from embedded to server is a stop-then-start handoff with real code changes, not a configuration flip (embedded to server).

---

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)
• Language-aware full-text search (stemming, phrase queries, GIN indexes used at runtime)
• Row-level security for network clients (Nano enforces RLS only for embedded and REPL callers)
• Proven large-scale operation (HeliosDB's published benchmarks are single-node, on a small dataset)
• Existing PostgreSQL ecosystem (extensions, tools)

---

When HeliosDB is not the right fit

• You need PostgreSQL semantics, not just its protocol. Wire compatibility is not semantic parity: collation is byte-order (C) only, and open issues include ignored NULLS FIRST/LAST, a setval() that does not move the sequence and rejected expression indexes. FAQ · Known limitations
• Your correctness depends on true SERIALIZABLE isolation. Nano serves SERIALIZABLE as snapshot isolation, which permits write skew. Isolation levels
• You run concurrent read-modify-write updates on hot rows. Concurrent UPDATE … SET n = n + 1 on one row can lose increments under READ COMMITTED without raising a serialization error. Known limitations: concurrency
• Network clients rely on row-level security or role privileges. In the stock Nano server, row-level security is enforced through the embedded API and the REPL; SQL CREATE POLICY and enforcement for REST and wire clients are planned, and SET ROLE is refused. Deployment modes · Security hardening
• You keep business logic in stored procedures or triggers. Nano runs plain-SQL DO blocks and simple SQL/plpgsql functions; PL/pgSQL control flow and trigger bodies (beyond simple BEFORE INSERT row rewrites) are planned. PL/pgSQL compatibility · Known limitations: SQL behaviour
• You depend on extensions, custom types or language-aware full-text search. Extensions and custom types need built-in equivalents; full-text search has no stemming or phrase queries yet (both are planned), and GIN indexes are accepted but not used at runtime. Migrating from PostgreSQL · Full-text search compatibility

---

Migration Path

Schema Migration

Most PostgreSQL DDL loads unchanged, but compatibility is not total, so test rather than assume (migration guide):

-- This PostgreSQL schema loads in HeliosDB Nano
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);
-- Accepted as DDL; GIN is not consulted at runtime
CREATE INDEX idx_orders_data ON orders USING gin(items);

Data Migration

# Export schema and data from PostgreSQL
pg_dump -s -h postgres-server -U postgres mydb > schema.sql
pg_dump -a -h postgres-server -U postgres mydb > data.sql

# Remove the pg_catalog.set_config() calls pg_dump emits
# (Nano does not implement set_config yet), then load
heliosdb-nano init ./mydb
heliosdb-nano repl --data-dir ./mydb < schema.sql
heliosdb-nano repl --data-dir ./mydb < data.sql

Connection String Change

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

# HeliosDB Nano server: the same PostgreSQL dialect and driver
engine = create_engine("postgresql://user:pass@localhost:5432/db")

# There is no HeliosDB SQLAlchemy dialect; for in-process use,
# call the embedded binding (import heliosdb_nano) directly

---

Feature Comparison: Real-World Scenarios

Scenario 1: SaaS Application

Scenario 2: AI Application

Scenario 3: Desktop Application

---

Performance Comparison

We do not publish throughput figures for this pairing. The benchmarks page compares Nano with PostgreSQL 16 across 35 query categories, measured on representative fixtures: Nano runs embedded with no network hop, PostgreSQL runs over local TCP, the dataset is small and single-node, and PostgreSQL wins several categories. Its caveats also note that write-heavy OLTP benchmarks show PostgreSQL's maturity advantage. Reproduce the suite on your own workload and hardware before deciding.

---

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 Nano Deployment

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

Or simply:

// No Docker, no separate service: the engine runs in your process
use heliosdb_nano::EmbeddedDatabase;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = EmbeddedDatabase::new("./data")?;
    // Your application code
    Ok(())
}