halfORM is a database-first ORM for PostgreSQL. Your schema lives in the database; halfORM introspects it at runtime and gives you Python objects to work with your data. No migrations, no code generation.
The central idea: a Relation object is a predicate. It describes the
logical condition that rows must satisfy to belong to the relation. Its
extension — the set of rows currently satisfying the predicate in the
database — is what you read, update, or delete. Why a predicate rather than an
object mapped to a row is argued in
A Relation Is a Predicate, Not an Object.
- Database-first — the schema lives in PostgreSQL, not in Python classes.
- Predicate model — relations are predicates; set operators (
|,&,-) compose them before any SQL is sent. - FK navigation — join across tables (and views) by setting FK attributes;
explicit
Fkeysdict for views where PostgreSQL stores no FK metadata. - Sync + async — every executor has an
a-prefixed async counterpart (ho_aselect,ho_ainsert, …). - Bulk load —
ho_copy/ho_acopyfor high-throughput inserts via PostgreSQLCOPY. - No magic — queries are built from the predicate you describe and executed
only when you call an executor.
ho_mogrify()shows the exact SQL.
pip install half_ormRequires psycopg 3 (psycopg[binary]).
# ~/.half_orm/blog
[database]
name = blog
user = alice
password = secret
host = localhostfrom half_orm.model import Model
from half_orm.relation_errors import NotFoundError, MultipleRowsError
blog = Model('blog')
Post = blog.get_relation_class('blog.post')
Author = blog.get_relation_class('blog.author')
# Insert — returns the inserted row as a dict
alice = Author(
first_name='Alice', last_name='Martin', email='alice@example.com'
).ho_insert()
# Query — Author(last_name='Martin') is a predicate, not a query
for row in Author(last_name='Martin').ho_select('id', 'email'):
print(row)
# Get exactly one row
try:
author = Author(last_name='Martin').ho_get()
except NotFoundError:
print("no such author")
except MultipleRowsError:
print("ambiguous — more than one author named Martin")
# FK navigation — no JOIN written by hand
post = Post(id=1)
post.author_fk.set() # join all authors
for row in post.ho_select(json_agg={'author_fk': ['first_name', 'last_name']}):
print(row['author_fk']) # {'first_name': 'Alice', 'last_name': 'Martin'}
# Set operators — compose predicates before hitting the database
recent = Post(created_at=('>', '2024-01-01'))
featured = Post(featured=True)
combined = recent | featured # UNION
print(combined.ho_count())
# Update / delete
Author(id=alice['id']).ho_update(email='alice@newdomain.com')
Author(id=alice['id']).ho_delete()- Learn halfORM in half an hour
- API Reference
- Why database-first — the argument behind the design, in six essays
- Breaking changes — and what to do coming from a 0.x release, all of which were published as Beta
- Security — advisories by release line, and how to report a vulnerability
- What halfORM defends, and what it cannot
| Extension | Description |
|---|---|
| half-orm-dev | Development tools — half_orm dev project scaffolding, patch management, and schema synchronisation. |
halfORM is licensed under the GPL-3.0 license.