ORM Support - HeliosDB Lite¶

Overview¶

HeliosDB Lite provides 100% PostgreSQL wire protocol compatibility, which means it automatically works with all major ORMs that support PostgreSQL, with zero code changes required.

Supported ORMs¶

Python¶

SQLAlchemy¶

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# Connect to HeliosDB Lite (same as PostgreSQL)
engine = create_engine('postgresql://localhost:5432/mydb')
Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    email = Column(String(100))

# Create tables
Base.metadata.create_all(engine)

# Use ORM
Session = sessionmaker(bind=engine)
session = Session()
user = User(name='Alice', email='alice@example.com')
session.add(user)
session.commit()

Compatibility: ✅ 100% (all SQLAlchemy features work)

Vector Search Extension:

from pgvector.sqlalchemy import Vector

class Document(Base):
    __tablename__ = 'documents'
    id = Column(Integer, primary_key=True)
    content = Column(String)
    embedding = Column(Vector(1536))  # OpenAI ada-002 compatible

# Semantic search with SQLAlchemy
results = session.query(Document).order_by(
    Document.embedding.cosine_distance([0.1, 0.2, ...])
).limit(10).all()

Django ORM¶

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'postgres',
        'PASSWORD': '',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

# models.py
from django.db import models

class User(models.Model):
    name = models.CharField(max_length=50)
    email = models.EmailField(unique=True)
    created_at = models.DateTimeField(auto_now_add=True)

# Use Django ORM
user = User.objects.create(name='Alice', email='alice@example.com')
users = User.objects.filter(name__startswith='A')

Compatibility: ✅ 100% (all Django features work)

Rust¶

Diesel¶

use diesel::prelude::*;

#[derive(Queryable, Insertable)]
#[diesel(table_name = users)]
struct User {
    id: i32,
    name: String,
    email: String,
}

// Connect to HeliosDB Lite
let database_url = "postgresql://localhost:5432/mydb";
let mut conn = PgConnection::establish(&database_url)?;

// Insert
diesel::insert_into(users::table)
    .values(&new_user)
    .execute(&mut conn)?;

// Query
let results = users::table
    .filter(users::name.like("A%"))
    .load::<User>(&mut conn)?;

Compatibility: ✅ 100% (PostgreSQL backend)

SeaORM¶

use sea_orm::*;

#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "users")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    pub email: String,
}

// Connect
let db = Database::connect("postgresql://localhost:5432/mydb").await?;

// Insert
let user = users::ActiveModel {
    name: Set("Alice".to_owned()),
    email: Set("alice@example.com".to_owned()),
    ..Default::default()
};
user.insert(&db).await?;

// Query
let users: Vec<users::Model> = users::Entity::find()
    .filter(users::Column::Name.starts_with("A"))
    .all(&db)
    .await?;

Compatibility: ✅ 100% (SQLx PostgreSQL driver)

TypeScript/JavaScript¶

TypeORM¶

import { Entity, PrimaryGeneratedColumn, Column, createConnection } from "typeorm";

@Entity()
class User {
    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    name: string;

    @Column()
    email: string;
}

// Connect to HeliosDB Lite
const connection = await createConnection({
    type: "postgres",
    host: "localhost",
    port: 5432,
    database: "mydb",
    entities: [User],
    synchronize: true,
});

// Insert
const user = new User();
user.name = "Alice";
user.email = "alice@example.com";
await connection.manager.save(user);

// Query
const users = await connection.manager.find(User, {
    where: { name: Like("A%") }
});

Compatibility: ✅ 100% (PostgreSQL driver)

Prisma¶

// schema.prisma
datasource db {
  provider = "postgresql"
  url      = "postgresql://localhost:5432/mydb"
}

model User {
  id    Int    @id @default(autoincrement())
  name  String
  email String @unique
}

// TypeScript code
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

// Insert
const user = await prisma.user.create({
  data: {
    name: 'Alice',
    email: 'alice@example.com',
  },
})

// Query
const users = await prisma.user.findMany({
  where: {
    name: {
      startsWith: 'A',
    },
  },
})

Compatibility: ✅ 100% (PostgreSQL connector)

Go¶

GORM¶

import (
    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

type User struct {
    ID    uint   `gorm:"primaryKey"`
    Name  string
    Email string `gorm:"unique"`
}

// Connect to HeliosDB Lite
dsn := "host=localhost user=postgres password= dbname=mydb port=5432"
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})

// Auto-migrate
db.AutoMigrate(&User{})

// Insert
user := User{Name: "Alice", Email: "alice@example.com"}
db.Create(&user)

// Query
var users []User
db.Where("name LIKE ?", "A%").Find(&users)

Compatibility: ✅ 100% (PostgreSQL driver)

Ruby¶

ActiveRecord¶

require 'active_record'

ActiveRecord::Base.establish_connection(
  adapter:  'postgresql',
  host:     'localhost',
  port:     5432,
  database: 'mydb'
)

class User < ActiveRecord::Base
end

# Insert
user = User.create(name: 'Alice', email: 'alice@example.com')

# Query
users = User.where("name LIKE ?", "A%")

Compatibility: ✅ 100% (PostgreSQL adapter)

Vector Search with ORMs¶

HeliosDB Lite's built-in vector search integrates seamlessly with ORMs through PostgreSQL's type extension system (pgvector compatibility):

Python (SQLAlchemy + pgvector)¶

from pgvector.sqlalchemy import Vector
from sqlalchemy import select

class Document(Base):
    __tablename__ = 'documents'
    id = Column(Integer, primary_key=True)
    content = Column(Text)
    embedding = Column(Vector(1536))

# Semantic search
query_embedding = [0.1, 0.2, ...]  # From OpenAI, Cohere, etc.
stmt = select(Document).order_by(
    Document.embedding.cosine_distance(query_embedding)
).limit(10)
results = session.execute(stmt).scalars().all()

TypeScript (TypeORM + pgvector)¶

import { Entity, Column } from "typeorm";

@Entity()
class Document {
    @Column("vector", { length: 1536 })
    embedding: number[];

    @Column()
    content: string;
}

// Semantic search (raw SQL with ORM)
const results = await connection.query(`
    SELECT * FROM documents
    ORDER BY embedding <=> $1
    LIMIT 10
`, [queryEmbedding]);

Migration from Other Databases¶

From SQLite¶

# Before (SQLite)
engine = create_engine('sqlite:///mydb.db')

# After (HeliosDB Lite) - just change connection string!
engine = create_engine('postgresql://localhost:5432/mydb')

Zero code changes required for basic SQL operations.

From MySQL¶

# Before (MySQL)
engine = create_engine('mysql://localhost/mydb')

# After (HeliosDB Lite)
engine = create_engine('postgresql://localhost:5432/mydb')

Minor changes for MySQL-specific syntax (e.g., AUTO_INCREMENT → SERIAL).

From MongoDB¶

# Before (MongoDB + mongoengine)
from mongoengine import connect, Document, StringField
connect('mydb')

# After (HeliosDB Lite + SQLAlchemy) - requires schema definition
from sqlalchemy import create_engine, Column, String
engine = create_engine('postgresql://localhost:5432/mydb')

Requires schema migration but benefits from ACID guarantees and SQL queries.

Testing with ORMs¶

Integration Test Example (Python + pytest)¶

import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

@pytest.fixture
def db_session():
    # Use in-memory HeliosDB Lite for tests
    engine = create_engine('postgresql://localhost:5432/test_db')
    Session = sessionmaker(bind=engine)
    session = Session()

    # Setup
    Base.metadata.create_all(engine)

    yield session

    # Teardown
    session.close()
    Base.metadata.drop_all(engine)

def test_user_creation(db_session):
    user = User(name='Test', email='test@example.com')
    db_session.add(user)
    db_session.commit()

    assert user.id is not None
    assert db_session.query(User).count() == 1

Performance Optimization with ORMs¶

Connection Pooling¶

# SQLAlchemy
from sqlalchemy.pool import QueuePool

engine = create_engine(
    'postgresql://localhost:5432/mydb',
    poolclass=QueuePool,
    pool_size=20,
    max_overflow=10,
    pool_pre_ping=True  # Verify connections
)

Query Optimization¶

# Eager loading to avoid N+1 queries
from sqlalchemy.orm import joinedload

users = session.query(User).options(
    joinedload(User.posts)
).all()

# Bulk operations
session.bulk_insert_mappings(User, [
    {'name': 'User1', 'email': 'user1@example.com'},
    {'name': 'User2', 'email': 'user2@example.com'},
])

Limitations & Workarounds¶

Current Limitations (Phase 1 MVP)¶

Advanced PostgreSQL Extensions: Some PostgreSQL-specific features not yet implemented
Workaround: Use standard SQL features in ORMs
Stored Procedures: Not yet supported
Workaround: Implement business logic in application code
Custom Aggregates: Limited support
Workaround: Use built-in aggregates (SUM, AVG, COUNT, MIN, MAX)

Roadmap (Phase 2+)¶

✅ JSONB support (Month 4-6)
✅ Full-text search (Month 4-6)
✅ Advanced indexing (Month 4-6)
✅ Stored procedures (Month 7-12)

Resources¶

SQLAlchemy Documentation: https://docs.sqlalchemy.org/
Django ORM Guide: https://docs.djangoproject.com/en/stable/topics/db/
Diesel Guide: https://diesel.rs/guides/
TypeORM Documentation: https://typeorm.io/
Prisma Documentation: https://www.prisma.io/docs
GORM Documentation: https://gorm.io/docs/

Getting Help¶

For ORM-specific issues with HeliosDB Lite:

Check ORM's PostgreSQL compatibility documentation
Join our Discord: https://discord.gg/heliosdb
GitHub Discussions: https://github.com/heliosdb/heliosdb/discussions
AI-Support subscription (coming soon): Automated query optimization and ORM integration help

Key Takeaway: If it works with PostgreSQL, it works with HeliosDB Lite. Zero code changes for ORM migrations from PostgreSQL.