---
title: "Quick Start Guide"
description: "Create a HeliosDB Lite database in server or REPL mode, then run SQL, time-travel queries, branching and vector search."
---

# Quick Start Guide

Get up and running with HeliosDB-Lite in 5 minutes.

## Create a Database

### Server (any PostgreSQL driver)

Start the server, then connect with a standard PostgreSQL driver. Lite is not published on PyPI; from Python, use `psycopg`.

```bash
# Lite refuses to start without a REST token-signing secret
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb
```

```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 1").fetchone())
```

The default `--auth trust` is for local development only; see [Deployment Modes](https://www.heliosdb.com/docs/lite/getting-started/deployment/) and the [authentication guide](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/) before you expose the server.

### CLI (REPL)

```bash
# Start REPL with file database
heliosdb-lite repl --data-dir ./mydb

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

## Create Tables

```sql
-- Users table
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Orders table with foreign key concept
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    total DECIMAL(10,2),
    status TEXT DEFAULT 'pending'
);
```

## Insert Data

```sql
-- Single insert
INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');

-- Multiple rows
INSERT INTO users (id, name, email) VALUES
    (2, 'Bob', 'bob@example.com'),
    (3, 'Carol', 'carol@example.com');

-- Insert with RETURNING
INSERT INTO orders (user_id, total) VALUES (1, 99.99) RETURNING id;
```

## Query Data

```sql
-- Basic query
SELECT * FROM users;

-- With conditions
SELECT name, email FROM users WHERE id > 1;

-- Join tables
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id;

-- Aggregation
SELECT user_id, SUM(total) as total_spent
FROM orders
GROUP BY user_id;
```

## Try Advanced Features

### Time-Travel Queries

```sql
-- Query data as it existed yesterday
SELECT * FROM orders AS OF TIMESTAMP '2025-01-14 00:00:00';
```

### Database Branching

```sql
-- Create a development branch (AS OF is optional)
CREATE DATABASE BRANCH dev FROM main AS OF NOW;

-- Switch to branch
USE BRANCH dev;

-- Make changes safely
DELETE FROM users WHERE id = 1;

-- Switch back
USE BRANCH main;
-- Original data is still there!
```

### Vector Search

```sql
-- Create table with vector column
CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding VECTOR(384)
);

-- Insert with embedding
INSERT INTO documents (id, content, embedding)
VALUES (1, 'Machine learning basics', '[0.1, 0.2, ...]');

-- Similarity search
SELECT content FROM documents
ORDER BY embedding <-> '[0.15, 0.25, ...]'
LIMIT 5;
```

## REPL Tips

```bash
# Show help
\h

# List tables
\d

# Describe table
\d users

# Show branches
\branches

# Toggle timing
\timing
```

## Next Steps

- [SQL Reference](https://www.heliosdb.com/docs/lite/user-guide/sql-reference/) - Complete SQL syntax
- [REPL Commands](https://www.heliosdb.com/docs/lite/user-guide/repl-commands/) - All meta commands
- [Features](https://www.heliosdb.com/docs/lite/features/) - Branching, time-travel, vectors