---
title: "ORM Support - HeliosDB Nano"
---

# ORM Support - HeliosDB Nano

## Overview

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

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

# Connect to HeliosDB Nano (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:**
```python
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

```python
# 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

```rust
use diesel::prelude::*;

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

// Connect to HeliosDB Nano
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

```rust
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

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

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

    @Column()
    name: string;

    @Column()
    email: string;
}

// Connect to HeliosDB Nano
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

```typescript
// 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

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

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

// Connect to HeliosDB Nano
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

```ruby
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 Nano's built-in vector search works with ORMs through PostgreSQL's type extension system (pgvector compatibility):

### Python (SQLAlchemy + pgvector)

```python
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)

```typescript
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

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

# After (HeliosDB Nano): only the connection string changes
engine = create_engine('postgresql://localhost:5432/mydb')
```

**Zero code changes required** for basic SQL operations.

### From MySQL

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

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

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

### From MongoDB

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

# After (HeliosDB Nano + 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)

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

@pytest.fixture
def db_session():
    # Use in-memory HeliosDB Nano 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

```python
# 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

```python
# 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

1. **Advanced PostgreSQL Extensions**: Some PostgreSQL-specific features not yet implemented
   - Workaround: Use standard SQL features in ORMs

2. **Stored Procedures**: plain-SQL procedures and simple PL/pgSQL functions run; PL/pgSQL control flow is planned
   - Workaround: Implement branching logic in application code

3. **Custom Aggregates**: Limited support
   - Workaround: Use built-in aggregates (SUM, AVG, COUNT, MIN, MAX)

### Planned

- Stored procedures with full PL/pgSQL control flow
- Wider PostgreSQL extension coverage

## 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 Nano:

1. Check ORM's PostgreSQL compatibility documentation
2. Join our Discord: https://discord.gg/yTykuUrFXc
3. Discord: https://discord.gg/yTykuUrFXc
4. Use `EXPLAIN` output and ORM logs to review query plans and parameter binding behavior

---

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