oceanic-mysql-orm 1.0.5

A production-grade async MySQL ORM with LoopBack-style nested relation queries, typed model instances, and zero N+1.

🚀 Oceanic MySQL ORM Connector

A high-performance, asynchronous MySQL ORM for Python. Built for speed, deep relational integrity, and developer transparency.

---

📦 Core Features

• Async First: Built on top of aiomysql for non-blocking I/O.
• N+1 Prevention: Intelligent batch-loading for relations (no implicit lazy-loading penalties).
• Relational Power: Supports One-to-One, One-to-Many, Many-to-Many (Through), and Self-referential models.
• Additive Migrations: Safe, non-destructive schema synchronization.
• Debug Echo: Real-time SQL monitoring with color-coded terminal output.

---

🏁 Initialization

from mysql_connector import MySQLConnector

connector = MySQLConnector(
    host="127.0.0.1",
    port=3306,
    user="root",
    password="yourpassword",
    database="your_db",
    echo=True  # Enables Query Debug Mode
)

await connector.connect()
await connector.migrate() # Synchronizes schema

---

📝 Model Definition

from mysql_connector import MySQLModel, Field, Relation

class User(MySQLModel):
    __table__ = "users"
    
    id    = Field(primary_key=True, auto_increment=True)
    name  = Field(nullable=False)
    email = Field(unique=True)
    
    # One-to-Many Relation
    posts = Relation("hasMany", target_model="Post", foreign_key="author_id")

class Post(MySQLModel):
    __table__ = "posts"
    
    id        = Field(primary_key=True)
    title     = Field()
    author_id = Field()

---

🔍 Query API

find(model_class, options)

Fetches a list of instances matching the criteria.

posts = await connector.find(Post, {
    "where": {"status": "published"},
    "order": ["id DESC"],
    "limit": 10,
    "include": ["author"] # Batch-loads authors
})

find_one(model_class, options)

Fetches a single instance or returns None.

find_by_id(model_class, pk_value, options)

Shortcut for fetching by primary key.

create(model_instance)

Inserts a new record and triggers before_create hooks.

update(model_instance)

Persists changes to an existing record.

---

🏗️ Relation Strategies

Type	Direction	Batch Strategy
belongsTo	Child → Parent	WHERE pk IN (...)
hasOne	Parent → Child	WHERE fk IN (...) LIMIT 1
hasMany	Parent → Children	WHERE fk IN (...)
hasManyThrough	M2M	Junction Query -> Target Query

---

🛠️ Schema Migration Policy (Safety First)

The Migrator follow an Additive-Only policy:

• Missing Tables: Will be created automatically.
• Missing Columns: Will be added (ALTER TABLE ADD COLUMN).
• Extra Columns: Will be ignored. The ORM will never drop a column from your database, even if it is removed from models.py. This prevents accidental data loss during refactoring.

Scenario: Manual Column Removal If you wish to delete a column from the database, you must do so manually via SQL: ALTER TABLE table_name DROP COLUMN column_name;

---

📡 Debugging (Echo Mode)

When echo=True is passed to the constructor, the ORM prints formatted SQL to the console:

[ORM QUERY] SELECT * FROM users WHERE email = %s
[PARAMS]    ['[e-mail]']

This is essential for identifying inefficient queries during development.