halfORM Documentation¶

Documentation Version

This documentation covers halfORM 0.15.x (latest stable release). For older versions, see the GitHub releases.

The PostgreSQL-native ORM that stays out of your way

halfORM lets you keep your database schema in SQL where it belongs, while giving you the comfort of Python for data manipulation. No migrations, no schema conflicts, no ORM fighting — just PostgreSQL and Python working together.

Overview¶

halfORM is a lightweight, database-first Object-Relational Mapper designed specifically for PostgreSQL. Unlike traditional ORMs that impose their own schema management, halfORM adapts to your existing database structure, making it perfect for teams that prefer SQL-first development.

Why halfORM?

🎯 Database-First: Your PostgreSQL schema is the source of truth
🔍 SQL Transparency: See exactly what queries are generated
⚡ Zero Setup: Connect to existing databases instantly
🚀 PostgreSQL Native: Leverage advanced PostgreSQL features

Key Features¶

🔥 Instant Database Access¶

from half_orm.model import Model

# Connect to your existing database
blog = Model('blog_db')

# Work with your tables immediately
Post = blog.get_relation_class('blog.post')
Author = blog.get_relation_class('blog.author')

🎨 Custom Relation Classes¶

from half_orm.model import register
from half_orm.relation import singleton

@register
class Post(blog.get_relation_class('blog.post')):
    Fkeys = {
        'author_fk': 'post_author_id_fkey'
    }

@register
class Author(blog.get_relation_class('blog.author')):
    Fkeys = {
        'posts_rfk': '_reverse_fkey_blog_post_author_id'
    }

    @singleton
    def create_post(self, title, content):
        return self.posts_rfk(title=title, content=content).ho_insert()

# Foreign keys now return your custom classes!
post = Post(title='Welcome')
author = post.author_fk()  # Returns Author instance
author.create_post("New Post", "Content")  # Custom method available

🔍 Intuitive Querying¶

# The object IS the filter - no .filter() needed
young_people = Person(birth_date=('>', '1990-01-01'))
gmail_users = Person(email=('ilike', '%@gmail.com'))

# Navigate relationships while filtering
alice_posts = Author(name=('ilike', 'alice%')).posts_rfk(is_published=True)

# Chain operations naturally
recent_posts = (Post(is_published=True)
    .ho_order_by('created_at desc')
    .ho_limit(10))

🔧 PostgreSQL Native Features¶

# Use views, functions, and procedures
UserStats = blog.get_relation_class('analytics.user_stats')  # Database view
results = blog.execute_function('calculate_metrics', user_id=123)

# Advanced PostgreSQL data types work seamlessly
JsonData = blog.get_relation_class('app.json_table')
data = JsonData(metadata='{"type": "user", "premium": true}')  # JSONB support

Quick Start¶

Get up and running in under 5 minutes:

Install halfORM
```
pip install half_orm
```

Configure connection

mkdir ~/.half_orm
echo "[database]
name = my_database
user = username
password = password
host = localhost" > ~/.half_orm/my_database

Start coding

from half_orm.model import Model

db = Model('my_database')
Person = db.get_relation_class('public.person')

# Create
person = Person(name='Alice', email='alice@example.com')
result = person.ho_insert()

# Query
for person in Person(email=('ilike', '%@gmail.com')):
    print(f"Found: {person['name']}")

👉 Full Quick Start Guide →

Documentation Sections¶

🚀 Quick Start

Get up and running with halfORM in minutes. Connect to your database and start working with your data immediately.

Get Started →
🧩 Fundamentals

Core concepts that underpin halfORM's design and behavior. Essential reading for understanding the philosophy and patterns.

Master the Basics →
📚 Tutorial

Step-by-step guide covering all halfORM concepts from basic CRUD operations to advanced relationship navigation.

Learn halfORM →
📋 API Reference

Complete documentation of all halfORM classes, methods, and functions with detailed examples.

API Docs →
💡 Examples

Real-world examples and patterns for common use cases like web applications, data analysis, and more.

View Examples →
📖 Guides

In-depth guides on configuration, performance optimization, testing, and migrating from other ORMs.

Browse Guides →
🏗️ Architecture

Understanding halfORM's internals, design principles, and how it works under the hood.

Deep Dive →

Why Choose halfORM?¶

✅ Perfect For¶

PostgreSQL-centric applications - Leverage PostgreSQL's full power
Existing database projects - Work with established schemas
SQL-comfortable teams - Keep complex logic in the database
Rapid prototyping - Get started instantly
Microservices - Lightweight with no framework baggage

🤔 Consider Alternatives If¶

Multi-database support needed - halfORM is PostgreSQL-only
Django ecosystem - Django ORM may integrate better
Code-first approach preferred - You want to define models in Python
Heavy ORM features required - Need lazy loading, identity maps, etc.

Community & Support¶

GitHub Repository - Source code and issue tracking
Discussions - Community Q&A and ideas
PyPI Package - Official releases

What's New¶

Version 0.15.0 🎉¶

Latest Release - June 2025

Major update with new custom relation classes and breaking changes.

🎨 New @register decorator for custom relation classes with business logic
🔗 Enhanced foreign key navigation with custom class resolution
📚 Complete documentation rewrite with improved structure
⚠️ Breaking change: HOP packager moved to separate halfORM_dev package

# New in 0.15.0: Custom relation classes
@register
class Author(blog.get_relation_class('blog.author')):
    Fkeys = {'posts_rfk': '_reverse_fkey_blog_post_author_id'}

    @singleton
    def create_post(self, title, content):
        return self.posts_rfk(title=title, content=content).ho_insert()

# Foreign keys now return your custom classes!
post = Post(id=42)
author = post.author_fk()  # Returns Author instance
author.create_post("Title", "Content")  # Custom method available

Version 0.15.1 🎉¶

🔧 Developer Experience¶

New diagnostic command: python -m half_orm for instant installation verification
Improved peer authentication: Better error messages and timeout handling
Streamlined tutorial: Simplified installation process with built-in testing

Migration from 0.14.x¶

HOP Users - Action Required

If you were using the hop command, install the new package:

pip install half_orm_dev

Ready to start?

Jump into the Quick Start Guide or explore the Tutorial for a comprehensive introduction to halfORM.

Made with ❤️ for PostgreSQL and Python developers