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.1.tar.gz (38.1 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.1-cp39-abi3-win_amd64.whl (198.4 kB view details)

Uploaded CPython 3.9+Windows x86-64

lunarphase_orm-0.1.1-cp39-abi3-manylinux_2_34_x86_64.whl (336.3 kB view details)

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

lunarphase_orm-0.1.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (331.7 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

lunarphase_orm-0.1.1-cp39-abi3-macosx_11_0_arm64.whl (296.3 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

lunarphase_orm-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl (297.5 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: lunarphase_orm-0.1.1.tar.gz
  • Upload date:
  • Size: 38.1 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.1.tar.gz
Algorithm Hash digest
SHA256 f7b01f3f2cda36da563db0b80ec2854e44abec7377b328f706f19ace6b2b1d67
MD5 d4cd3b9ee0a978d2640f0479f9040b1a
BLAKE2b-256 63dfcb0cad743dca797dd6cf51795ccb0fab2841ff3f73731c82cb65d9e86c64

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1.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.1-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 74e1f512c8f7166f83fa24cf64a8c7e45e0415ff0ff9b7d9320e2e009b2f99d1
MD5 b3060cb8083d3ad12aa8f1d196c04c04
BLAKE2b-256 2ef3c19e5da644175d70860c2224932d5a59b8749f740246d0716dbba7cb70a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1-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.1-cp39-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.1-cp39-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 9d33a1e36b04103bd5d66a9a0fe1d59697f9aa67c445ac769021012ea597624c
MD5 84d167c0e0a6362c6d5c614e8c460426
BLAKE2b-256 b42d11f1a1e3f0b34c3cb694bd952636af90078364386bbe3071aded1b361c46

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1-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.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3e508f89ded4a5469bfc192b2948be570838e93ba04096ac5310055ea7341166
MD5 966fed6cef187255a76d956cb3fe2406
BLAKE2b-256 6bd8172c4c1f50ee3cade62a27a1d42e76d24d9db759a261ef6118aec6c926fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1-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.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5436eac8f615a780f100664bc12d511d885982003c575fdcd8fbe738ad1156a2
MD5 9294db8d6d2ebda10d1feb13df830230
BLAKE2b-256 ccc08cb3b8840bb1cac629a7de74da5d2e797b9e4cc2df4e91cce9e299ea6899

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1-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.1-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for lunarphase_orm-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6720b03b5b036ccb3c6e49294e0d18e6aaeca7da4cf20723aafd2c482790ddaf
MD5 8b1d8bd82eca86df070e59088ce529b8
BLAKE2b-256 86f95b740d9ad048f1497eb351581704a904e01a8d7c4dfe5e6abd81d7dbf7f8

See more details on using hashes here.

Provenance

The following attestation bundles were made for lunarphase_orm-0.1.1-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

0.1.2

6 files

This release

0.1.1 This release

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