LunarPhaseORM logo

🌖 LunarPhaseORM

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

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.0.tar.gz (37.9 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.0-cp39-abi3-win_amd64.whl (198.3 kB view details)

Uploaded CPython 3.9+Windows x86-64

lunarphase_orm-0.1.0-cp39-abi3-manylinux_2_34_x86_64.whl (336.2 kB view details)

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

lunarphase_orm-0.1.0-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.0-cp39-abi3-macosx_11_0_arm64.whl (296.1 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

lunarphase_orm-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl (297.4 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: lunarphase_orm-0.1.0.tar.gz
  • Upload date:
  • Size: 37.9 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.0.tar.gz
Algorithm Hash digest
SHA256 cdddadc2be602c0b60fdeec1bdef80ee9186316e3c040fb93eb7e43fe2493164
MD5 7ff0569cbdf154e017ae79f798f37448
BLAKE2b-256 7ebe7d430e67cea7ace3945f54f92fe498cc9c19e314b574de85b7809bac37bb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2664494011d40acbb618d522a226ad794f1f6cceeb038b197977fb248fa06cdb
MD5 3079e5dd340286c1753ad226f4ff82ff
BLAKE2b-256 232eada186c6dc32dc0f9290c3fb614f9e41d078373a25234fd36042dd5ad7ec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.0-cp39-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 171a8502939904846b7ed28ab308d7611b981052520e3cb6a95eba0e01991ad8
MD5 80ffb0269b819e47eca94465ebcb7b42
BLAKE2b-256 29fba4180891a7955b4e30957b1464a96b18994bf48fa430864a43a985cfcd18

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 cbd1d46847a26ca1053994f60c6f55deda8c265f5e368488ba01f73fe399839d
MD5 9c1cf37126a94257427d5bee857f9381
BLAKE2b-256 096b3a94527d9667b97bdb1ec9364c8134bbf6510e23e6d5fe52e95d3bb79f26

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d1691170fadde7f4fd673fdf3ffe23c528ae5a4f0c45f358755c8a696a31d112
MD5 6571998c9b8e2a1d34b07c43e22dabe9
BLAKE2b-256 34174cdb77474e1cfcad66b87fe5c7efd70f07fbc71c3b6cf1733bc70659be74

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 effcbd38effc75fe049152f8e91fcb3cfdbda6997b73039667c24aa84e41c40f
MD5 33f5462377ff04bc0fe96240d6df43cc
BLAKE2b-256 b2b13a9dbc8afb913dd08627bc8ab2ed1b1c032a6180fe4c808eaacc9a1adaee

See more details on using hashes here.

Provenance

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

0.1.1

6 files

This release

0.1.0 This release

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