---
title: "Quick Start Guide"
description: "Run HeliosDB Lite in server or REPL mode: start the server, connect over PostgreSQL wire, and run SQL over the REST API."
---

# Quick Start Guide

> Get HeliosDB-Lite running in 5 minutes

---

## Choose Your Mode

HeliosDB-Lite runs in three modes:

| Mode | Best For | Latency | Setup |
|------|----------|---------|-------|
| **Embedded** | Single-app, edge, mobile | In-process | Licensed source distribution |
| **Server** | Multi-client, team use | Network round trip | 1 command |
| **REPL** | Exploration, prototyping | Interactive | 1 command |

In server mode, HeliosDB Lite serves the PostgreSQL wire protocol and a REST API. An MCP server, an Oracle listener, a MySQL listener and a gRPC query API are planned.

---

## Option 1: Server Mode

### Step 1: Build and Start the Server

```bash
# Build the binary from the licensed source distribution (no binary downloads;
# contact sales@heliosdb.com for access)
cd heliosdb-lite && cargo build --release && cp target/release/heliosdb-lite .. && cd ..

# PostgreSQL wire on 127.0.0.1:5432, REST API on 127.0.0.1:8080
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"   # required to start the server (REST token signing)
./heliosdb-lite start --data-dir ./data
```

The server prints its PostgreSQL and REST addresses when it is ready. Use `--port`, `--http-port` and `--listen` to change the ports or the bind address. For anything beyond local development, add `--auth scram-sha-256 --password <password>`; see [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/).

### Step 2: Create a Table over PostgreSQL Wire

Any PostgreSQL client or driver works:

```bash
psql -h 127.0.0.1 -p 5432 -U postgres -d heliosdb
```

```sql
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT UNIQUE);
INSERT INTO users VALUES (1, 'Alice', 'alice@example.com');
```

### Step 3: Get a REST Token

The REST API accepts HS256 JWTs signed with `HELIOSDB_JWT_SECRET`. Lite does not issue tokens itself, so mint one as shown in [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/#mint-a-token-python) and export it:

```bash
export TOKEN="eyJhbGciOiJIUzI1NiIs..."
```

### Step 4: Run SQL over REST

Statements that change data or schema go to `execute`, and queries go to `query`. Both take a branch name (`main` by default):

```bash
# Insert
curl -X POST http://127.0.0.1:8080/v1/branches/main/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "INSERT INTO users VALUES (2, '\''Bob'\'', '\''bob@example.com'\'')"}'

# Query with a parameter
curl -X POST http://127.0.0.1:8080/v1/branches/main/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE id = $1", "params": [{"type": "int4", "value": 1}]}'
```

A query returns `columns`, `column_types`, `rows` (one object per row), `row_count` and `execution_time_ms`.

---

## Option 2: Embedded Mode

The engine can run inside your own process with no server, reading a local data directory.
Embedding Lite in your application is covered by the licensed source distribution; the REPL
below runs the same embedded engine interactively.

---

## Option 3: REPL Mode (Interactive)

### Start REPL

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

# Or in memory
./heliosdb-lite repl --memory
```

### Interactive Session

```sql
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT,
    price DECIMAL(10,2),
    embedding VECTOR(3)
);

INSERT INTO products VALUES (1, 'Widget', 29.99, '[0.1, 0.2, 0.3]');
INSERT INTO products VALUES (2, 'Gadget', 49.99, '[0.4, 0.5, 0.6]');

SELECT name, embedding <-> '[0.2, 0.3, 0.4]' AS distance
FROM products
ORDER BY distance
LIMIT 1;
```

---

## Using with Common Languages

Over the PostgreSQL wire, use your language's standard PostgreSQL driver. Over REST, any HTTP client works.

### Python (PostgreSQL wire)

```python
import psycopg  # pip install "psycopg[binary]"

with psycopg.connect("host=127.0.0.1 port=5432 user=postgres dbname=heliosdb") as conn:
    print(conn.execute("SELECT * FROM users").fetchall())
```

### Python (REST)

```python
import requests

BASE_URL = "http://127.0.0.1:8080/v1"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.post(
    f"{BASE_URL}/branches/main/query",
    headers=headers,
    json={"sql": "SELECT * FROM users"},
)
print(response.json()["rows"])
```

### JavaScript/TypeScript (REST)

```typescript
const BASE_URL = "http://127.0.0.1:8080/v1";

async function query(sql: string, token: string) {
  const response = await fetch(`${BASE_URL}/branches/main/query`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ sql })
  });
  return response.json();
}
```

### Go (PostgreSQL wire)

```go
import "github.com/jackc/pgx/v5"

conn, err := pgx.Connect(ctx, "postgres://postgres@127.0.0.1:5432/heliosdb")
```

---

## Next Steps

| Guide | Description |
|-------|-------------|
| [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/) | Wire authentication and REST tokens |
| [Schema Generation](https://www.heliosdb.com/docs/lite/website/api/schema-generation/) | Draft DDL from JSON samples |
| [Vector Search](https://www.heliosdb.com/docs/lite/website/guides/vector-search/) | HNSW and similarity queries |
| [Multi-Tenancy](https://www.heliosdb.com/docs/lite/website/guides/multi-tenancy/) | RLS and tenant isolation |

---

## Common Commands Reference

### Server Management

```bash
# Every `start` needs the REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Password authentication on the PostgreSQL wire
./heliosdb-lite start --data-dir ./data --auth scram-sha-256 --password "$DB_PASSWORD"

# TLS on the PostgreSQL wire
./heliosdb-lite start --data-dir ./data --tls-cert cert.pem --tls-key key.pem

# Run in the background, then check and stop it
./heliosdb-lite start --data-dir ./data --daemon
./heliosdb-lite status
./heliosdb-lite stop
```

Encryption at rest is configured in the `[encryption]` section of the configuration file passed with `--config`; see the [Encryption Quick Start](https://www.heliosdb.com/docs/lite/guides/encryption_quickstart/).

### Database Operations

```sql
-- Create a branch for testing
CREATE DATABASE BRANCH test_feature FROM main AS OF NOW;
USE BRANCH test_feature;

-- Time travel query
SELECT * FROM orders AS OF TIMESTAMP '2024-01-01 00:00:00';

-- Create materialized view
CREATE MATERIALIZED VIEW monthly_sales AS
SELECT month, SUM(amount) FROM orders GROUP BY month;
```

---

## Troubleshooting

### Connection Refused

```bash
# Check a server started with --daemon
./heliosdb-lite status

# Check which process holds the ports
lsof -i :5432 -i :8080
```

The server binds to `127.0.0.1` by default. Use `--listen 0.0.0.0` to accept remote connections, and enable password authentication when you do.

### Authentication Failed

```bash
# The health endpoint needs no token; a 200 here means the REST API is up
curl http://127.0.0.1:8080/health
```

If `/health` answers but `/v1/...` returns `401`, re-mint the token; see [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/#troubleshooting).

### Permission Denied

```bash
# Check file permissions on the data directory
ls -la ./data
```

---

*Need help? [Join Discord](https://discord.gg/yTykuUrFXc) | [Email support](mailto:support@heliosdb.com)*