LunarPhaseORM logo

🌖 LunarPhaseORM

Smart Sync. Zero N+1. High-Performance Python & Rust ORM.

PyPI version Python 3.9+ Rust Engine License: MIT Coverage

LunarPhaseORM is an async-first Object-Relational Mapper built for high-throughput applications where database performance and memory efficiency matter. It combines the developer ergonomics of Active Record (user.save()) with the safety of Data Mapper & Unit of Work, accelerated by a native Rust core (PyO3/maturin).

✨ Key Features

  • 🦀 Rust-Powered Performance: Offloads snapshot isolation state tracking, dirty diffing, AST compilation, and schema diffing to C-level Rust structs (_lunarphase_rs), drastically reducing Python RAM overhead.
  • ⚡ Zero N+1 Query Problem: Solves N+1 query issues automatically via asyncio event loop micro-task flushing (DeferredAutoBatcher). Relation access inside loops is automatically batched into single WHERE id IN (...) queries.
  • 🎯 Precise Dirty Tracking: Computes dirty attribute diffs in Rust. Calling await user.save() executes SQL UPDATE only on modified columns, and skips database I/O completely if no fields were altered.
  • 🛡️ Type-Safe Query Builder: Fluent API with native Python operator overloading (User.age > 18) producing AST query nodes cleanly.
  • 🔄 Unit of Work & Session Transactions: Guarantees object identity via IdentityMap and provides atomic transaction blocks (async with session.begin()) with automatic rollback on failure.
  • 🛠 CLI Auto-Migration System: Automated database schema diffing and reversible DDL script generation (lunarphase make:migration, migrate, rollback, status).

📦 Installation

Install LunarPhaseORM from PyPI:

pip install lunarphase-orm

Or build locally with Maturin:

git clone https://github.com/LunarPy-Labs/LunarPhaseORM.git
cd LunarPhaseORM
python3 -m venv .venv
source .venv/bin/activate
pip install maturin aiosqlite pydantic
maturin develop

⚡ Quick Start

import asyncio
from lunarphase import (
    Model,
    PrimaryKeyField,
    StringField,
    IntegerField,
    HasMany,
    BelongsTo,
    create_engine,
    UnitOfWork,
)

# 1. Define Models
class Author(Model):
    __tablename__ = "authors"
    id = PrimaryKeyField()
    name = StringField()
    posts = HasMany(lambda: Post, foreign_key="author_id")

class Post(Model):
    __tablename__ = "posts"
    id = PrimaryKeyField()
    title = StringField()
    author_id = IntegerField()
    author = BelongsTo(Author, foreign_key="author_id")

async def main():
    # 2. Connect Database Engine (SQLite, Postgres, MySQL)
    engine = create_engine("sqlite:///:memory:")

    # Setup Tables
    await engine.execute("CREATE TABLE authors (id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR(255));")
    await engine.execute("CREATE TABLE posts (id INTEGER PRIMARY KEY AUTOINCREMENT, title VARCHAR(255), author_id INTEGER);")

    # 3. Create Record
    author = await Author.create(name="Arthur Conan Doyle")

    # 4. Create Related Record
    await Post.create(title="A Study in Scarlet", author_id=author.id)
    await Post.create(title="The Sign of the Four", author_id=author.id)

    # 5. Access Relations (Zero N+1 Query Problem!)
    fetched_author = await Author.where(name="Arthur Conan Doyle").first()
    posts = await fetched_author.posts
    print(f"Author: {fetched_author.name}")
    for p in posts:
        print(f" - Post: {p.title}")

    # 6. Precise Dirty Tracking Update
    fetched_author.name = "Sir Arthur Conan Doyle"
    await fetched_author.save() # Updates ONLY 'name' column in SQL!

if __name__ == "__main__":
    asyncio.run(main())

📊 Comparison Matrix

Feature 🌖 LunarPhaseORM 🐍 SQLAlchemy (v2.0) 🐢 Tortoise ORM
Primary Architecture Hybrid (AR + Data Mapper) Data Mapper Active Record
State Storage & RAM Rust Core (_lunarphase_rs) Heavy Python Object Graph Python Dict
N+1 Query Resolution Automatic (Zero N+1 Engine) Manual (joinedload) Manual (prefetch)
Dirty Attribute Diffing Rust Snapshot Isolation Unit of Work History Basic re-save
SQL Query Compilation Rust AST Compiler Python AST PyPika
Async Support Native Async First Async Extension Native Async

🛠 CLI Migration Commands

LunarPhaseORM includes a command-line tool for managing schema migrations:

# Check migration status
lunarphase status

# Generate a new DDL schema migration file
lunarphase make:migration "create_users_table"

# Apply pending migrations
lunarphase migrate

# Rollback last migration
lunarphase rollback

🗺 Development Roadmap

LunarPhaseORM is developed in structured milestone phases. Core phases 1 through 5 are completed in v0.1.0, with advanced phases planned through v1.0.0 Stable:

  • ✅ Phases 1 - 5 (Completed - v0.1.0): Core Descriptors, Multi-driver Async Engines, N+1 Auto-Batching, Rust Snapshot Isolation & Dirty Tracking, CLI Auto-Migrations.
  • 🔷 Phase 6 (Sep - Oct 2026): Native Rust PostgreSQL/MySQL drivers (sqlx) & Connection Pool engine.
  • 🔷 Phase 7 (Nov - Dec 2026): Advanced query constructs (GROUP BY, HAVING, CTEs) & JSON path query operators.
  • 🔷 Phase 8 (Jan 2027): Framework integrations (lunarphase-fastapi middleware, Pydantic v2 auto-schemas).
  • 🔷 Phase 9 (Feb - Mar 2027): SIMD JSON parsing (simd-json) & v1.0.0 Stable Release.

For full timeline details, research disclaimers, and milestone tracking, see ROADMAP.md.

📖 Full Documentation & Benchmarks

For in-depth technical documentation, API references, and advanced usage patterns, read DOCUMENTATION.md. For detailed empirical benchmark reports, execution speeds, and memory metrics, read BENCHMARK.md.

📄 License

This project is licensed under the MIT License.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for indhifarhandika27 from gravatar.com indhifarhandika27

Credits

Author: LunarPy-Labs

Requires

Python >=3.9

Tags

orm async sqlite postgres mysql rust active-record data-mapper

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lunarphase_orm-0.1.2.tar.gz (40.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

lunarphase_orm-0.1.2-cp39-abi3-win_amd64.whl (202.8 kB view details)

Uploaded CPython 3.9+Windows x86-64

lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_34_x86_64.whl (340.6 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.34+ x86-64

lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (336.0 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

lunarphase_orm-0.1.2-cp39-abi3-macosx_11_0_arm64.whl (300.5 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

lunarphase_orm-0.1.2-cp39-abi3-macosx_10_12_x86_64.whl (301.8 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file lunarphase_orm-0.1.2.tar.gz.

File metadata

  • Download URL: lunarphase_orm-0.1.2.tar.gz
  • Upload date:
  • Size: 40.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for lunarphase_orm-0.1.2.tar.gz
Algorithm Hash digest
SHA256 ca8b5168610fd37612af8ed58c51988e3a59555e3be6e3d482941c791baf38ea
MD5 8fc00f8e33da3ead21a7a3489e84fb68
BLAKE2b-256 2f61fc7a4f40263930b642e2bc5132e3a9fc89b1b0788c556493dc4f89e5e123

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2.tar.gz:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lunarphase_orm-0.1.2-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.2-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d080e5fe3c9453b4f00fc711224606bcbf2b41aae25ed0f1c3e4704c9dc20b67
MD5 382e081d0c66c164ef76eab26b51c22d
BLAKE2b-256 8a915b2e23f9d25c987e14e317a321f9bd6b45ac5f49483cb1ffc5e0ab08c902

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2-cp39-abi3-win_amd64.whl:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 869cbdad6879bcda1f433d15b99eabf2b7d9908bd8f826167ae4a7cd80f1fcf4
MD5 4eb16012acc4058dc3cb567693b9767d
BLAKE2b-256 84b41c7723f1270136964909b5c1edf3fba007b90659bcc759b96785eb64376f

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_34_x86_64.whl:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 319db4324defb7df8556608df80df3bf55047220854b57a48c1a787abb7bf7e2
MD5 6c0003bdb3269da7f783ada5242f568a
BLAKE2b-256 6bb057a0b619906473d12e8f2888ea910b2fd42fc022c3aea9b22745d8740038

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lunarphase_orm-0.1.2-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.2-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 588bdf0177e8e187a6a0af7dcffcc0bea7c973625ae548232d0600482aa84d79
MD5 a43e55dd126cdd296c61cc516a4d0744
BLAKE2b-256 d4a524b97be74866046be293ff625b35c4902c72defeef8b85d8466fd0eba350

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lunarphase_orm-0.1.2-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.2-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 12b721880b91bc1e4513f1ba2156fffbd4908f4231088cd4d4131bb6977f9989
MD5 f2c629a2c9a56023e182274cff5c48ad
BLAKE2b-256 3066e23f778eca2289e47f984ddd190f8d6095cea87a22cb6702b43f4d193c8c

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.2-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: pypi-publish.yml on LunarPy-Labs/LunarPhaseORM

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.3

6 files

This release

0.1.2 This release

6 files

0.1.1

6 files

0.1.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page