LunarPhaseORM logo

🌖 LunarPhaseORM

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

PyPI version PyPI Downloads 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:
Latest release

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.3.tar.gz (708.6 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.3-cp39-abi3-win_amd64.whl (202.9 kB view details)

Uploaded CPython 3.9+Windows x86-64

lunarphase_orm-0.1.3-cp39-abi3-manylinux_2_34_x86_64.whl (340.7 kB view details)

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

lunarphase_orm-0.1.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (336.1 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

lunarphase_orm-0.1.3-cp39-abi3-macosx_11_0_arm64.whl (300.8 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

lunarphase_orm-0.1.3-cp39-abi3-macosx_10_12_x86_64.whl (301.9 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: lunarphase_orm-0.1.3.tar.gz
  • Upload date:
  • Size: 708.6 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.3.tar.gz
Algorithm Hash digest
SHA256 ed34373147026b35bb483f14d68e9c701cbff25a532d9f2d47653f23a2d968cf
MD5 efb8963b02477f56cc2283c8a09db408
BLAKE2b-256 158c8a155f6034b1a3568920ee9a2b21f286abf9b5f44a92a5e691de58358c8b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.3-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5699a6cc6e58d04d2ed14b6a166519272355e0c292af4a31a588c1bf5e2fe1fd
MD5 560a678280d9b5e2392da1ceae8ce9ae
BLAKE2b-256 da49337db3f364afc51ed9d798d2c4e421168cab13896075244be03d143633ec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.3-cp39-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 0abf3d35247eee89f04da982c0d87e0b79f77580951d8e8314ffae4d59a55d19
MD5 bc0c36be2df96e55575783cf5538575d
BLAKE2b-256 12598cf66d9320b7d0ab0d2bc0f803c7e3be1742f484b24f6aef9979e73b57c0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 575d80058cc9151462a90a1b29b64eb43b17971779f9e0224c2f79220350f559
MD5 3ce85219ae2d20284a66609a4299ba64
BLAKE2b-256 c35670df87d4884de67b5e044ad0e835a7644b48d589aced106d1c9d893e6b05

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.3-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f6433f9df30369dd82e2f8ad46bb9208e1264ef2b0f67854b6ade786680d5b08
MD5 25206ab971607bd7d14ea39574bff60e
BLAKE2b-256 b1099598e3903448302efdbbb2573cc1ac6e06caf530159e37bfc715a07510f0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for lunarphase_orm-0.1.3-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 208b23966330589426aff68ccbe4fe030137a01dd25a7cdf984610143a153987
MD5 6c46905aa875ababa52744e580b45416
BLAKE2b-256 8d53e6fe9e8b67df2ea1ce15067034b180cb158609a6de869a99627766963e4c

See more details on using hashes here.

Provenance

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

This release

0.1.3 This release

6 files

0.1.2

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