sqlobjects 1.9.0__tar.gz → 1.10.0__tar.gz

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 1.10.0 (2026-07-24)
+
+### Feat
+
+- **model**: add public get_dirty_fields() accessor on BaseMixin
+
+### Fix
+
+- **build**: sync __version__ with pyproject and auto-update via cz version_files
+
+## 1.9.1 (2026-04-09)
+
+### Fix
+
+- **query**: order_by uses replace semantics instead of append
+
 ## 1.9.0 (2026-03-27)
 
 ### Feat

{sqlobjects-1.9.0/sqlobjects.egg-info → sqlobjects-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.9.0
+Version: 1.10.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -48,6 +48,8 @@ loading. SQLObjects combines the familiar Django ORM API with the performance an
 - **📊 High performance** - Built on SQLAlchemy Core for optimal performance
 - **🔄 Smart operations** - Automatic CREATE/UPDATE detection and bulk operations
 - **🎣 Lifecycle hooks** - Comprehensive signal system for database operations
+- **🌊 Cascade operations** - Database- and ORM-level cascade deletes/updates with automatic detection
+- **📝 SQL logging** - Zero-config `sqlobjects.sql` logger with user-code caller rewriting
 - **🗄️ Multi-database support** - Seamless multi-database configuration and routing
 
 ## 🚀 Quick Start
@@ -89,7 +91,7 @@ active_users = await User.objects.filter(
 ).order_by("-age").limit(10).all()
 
 # Complex queries with Q objects
-from sqlobjects.queries import Q
+from sqlobjects import Q
 
 users = await User.objects.filter(
     Q(User.age >= 18) & (Q(User.username.like("%admin%")) | Q(User.is_active == True))
@@ -380,9 +382,14 @@ uv run pytest
 
 See our [TODO.md](TODO.md) for planned features:
 
-- **v2.0**: Database health checks, window functions, advanced bulk operations
-- **v2.1**: Advanced field optimization, query performance tools
-- **v2.2+**: CTE support, advanced SQL functions
+- **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
+- **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
+- **Query optimization**: index suggestions and slow-query analysis tools
+- **Migrations**: model-diff migration generation and batched data-migration tooling
+
+Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
+query analysis, cascade operations, SQL logging, and high-performance bulk
+operations.
 
 ## 📄 License
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/README.md

@@ -19,6 +19,8 @@ loading. SQLObjects combines the familiar Django ORM API with the performance an
 - **📊 High performance** - Built on SQLAlchemy Core for optimal performance
 - **🔄 Smart operations** - Automatic CREATE/UPDATE detection and bulk operations
 - **🎣 Lifecycle hooks** - Comprehensive signal system for database operations
+- **🌊 Cascade operations** - Database- and ORM-level cascade deletes/updates with automatic detection
+- **📝 SQL logging** - Zero-config `sqlobjects.sql` logger with user-code caller rewriting
 - **🗄️ Multi-database support** - Seamless multi-database configuration and routing
 
 ## 🚀 Quick Start
@@ -60,7 +62,7 @@ active_users = await User.objects.filter(
 ).order_by("-age").limit(10).all()
 
 # Complex queries with Q objects
-from sqlobjects.queries import Q
+from sqlobjects import Q
 
 users = await User.objects.filter(
     Q(User.age >= 18) & (Q(User.username.like("%admin%")) | Q(User.is_active == True))
@@ -351,9 +353,14 @@ uv run pytest
 
 See our [TODO.md](TODO.md) for planned features:
 
-- **v2.0**: Database health checks, window functions, advanced bulk operations
-- **v2.1**: Advanced field optimization, query performance tools
-- **v2.2+**: CTE support, advanced SQL functions
+- **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
+- **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
+- **Query optimization**: index suggestions and slow-query analysis tools
+- **Migrations**: model-diff migration generation and batched data-migration tooling
+
+Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
+query analysis, cascade operations, SQL logging, and high-performance bulk
+operations.
 
 ## 📄 License
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/01-database-session-guide.md

@@ -104,7 +104,7 @@ async with ctx_session() as session:
 
 # Good: Connection pool configuration
 await init_db(
-    "postgresql://localhost/db",
+    "postgresql+asyncpg://localhost/db",
     pool_size=20,
     max_overflow=30,
     pool_timeout=30,
@@ -141,7 +141,7 @@ await Post.objects.create(title="Post", author_id=user.id)
 ```python
 # Production configuration
 await init_db(
-    "postgresql://localhost/db",
+    "postgresql+asyncpg://localhost/db",
     pool_size=20,           # Base connections
     max_overflow=30,        # Burst capacity
     pool_timeout=30,        # Wait time for connection
@@ -249,7 +249,7 @@ except OperationalError:
 ## Complete Example
 
 ```python
-from sqlobjects.database import init_dbs, create_tables, close_all_dbs
+from sqlobjects.database import init_dbs, create_tables, close_dbs
 from sqlobjects.session import ctx_session, ctx_sessions
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn
@@ -264,8 +264,8 @@ class Log(ObjectModel):
 async def main():
     # Setup
     await init_dbs({
-        "main": {"url": "postgresql://localhost/main", "pool_size": 20},
-        "analytics": {"url": "sqlite:///analytics.db"}
+        "main": {"url": "postgresql+asyncpg://localhost/main", "pool_size": 20},
+        "analytics": {"url": "sqlite+aiosqlite:///analytics.db"}
     }, default="main")
 
     await create_tables(ObjectModel, "main")
@@ -286,7 +286,7 @@ async def main():
         )
 
     # Cleanup
-    await close_all_dbs()
+    await close_dbs()
 
 # Run
 import asyncio
@@ -330,3 +330,58 @@ async def get_user(user_id: int, session: AsyncSession = Depends(get_db_session)
     user = await User.objects.using(session).get(User.id == user_id)
     return {"username": user.username}
 ```
+
+## SQL Logging
+
+SQLObjects ships zero-config SQL logging through the standard library `logging`
+module. Every executed statement is logged at `DEBUG` level to the logger named
+**`sqlobjects.sql`**. This logger is an `ObjectLogger` (installed automatically
+on import) that rewrites each record's caller fields — `pathname`, `filename`,
+`funcName`, `lineno` — to the first user-code frame, skipping internal
+`sqlobjects.*` and `sqlalchemy.*` frames. Your log output therefore points at
+the line in your application that issued the query, not at ORM internals.
+
+### Enabling
+
+```python
+import logging
+
+# Show SQL (and everything else) at DEBUG
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("sqlobjects.sql").setLevel(logging.DEBUG)
+
+# Now queries emit DEBUG log records
+users = await User.objects.filter(User.is_active == True).all()
+```
+
+To capture SQL only, without lowering the level of the rest of your app, attach
+a dedicated handler to the `sqlobjects.sql` logger:
+
+```python
+import logging
+
+sql_logger = logging.getLogger("sqlobjects.sql")
+sql_logger.setLevel(logging.DEBUG)
+
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter("%(pathname)s:%(lineno)d - %(message)s"))
+sql_logger.addHandler(handler)
+```
+
+Statement compilation only happens when the logger is actually enabled for
+`DEBUG`, so leaving logging off has no runtime cost. Each record carries the
+compiled SQL as the message plus an `extra` dict with `sql`, `params`, and
+`duration_ms`.
+
+### Public API
+
+```python
+from sqlobjects import ObjectLogger, get_caller_frame
+```
+
+- **`ObjectLogger`** — the `logging.Logger` subclass used for `sqlobjects.sql`.
+  It accepts an `extra_skip_packages` list to skip additional module prefixes
+  (e.g. your own middleware) when resolving the user-code frame.
+- **`get_caller_frame(extra_skip_packages=None, max_frames=1)`** — returns the
+  first user-code frame as a `"path:lineno in func"` string (or a list when
+  `max_frames > 1`), applying the same skip rules. Useful for custom logging.

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/02-model-definition-guide.md

@@ -69,7 +69,8 @@ class User(ObjectModel):
 
 ```python
 from sqlobjects.model import ObjectModel
-from sqlobjects.fields import Column, StringColumn, index, constraint
+from sqlobjects.fields import Column, StringColumn, IntegerColumn
+from sqlobjects.metadata import index, constraint
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -88,6 +89,38 @@ class User(ObjectModel):
         ]
 ```
 
+### Named & Composite Foreign Keys
+
+For composite foreign keys, custom constraint names, or explicit referential
+actions defined at the table level, use the `foreignkey()` constraint builder
+in `Config.constraints`. For simple single-column foreign keys, prefer the
+`foreign_key()` field descriptor (see the Relationships guide) instead.
+
+```python
+from sqlobjects.model import ObjectModel
+from sqlobjects.fields import Column, StringColumn, IntegerColumn
+from sqlobjects.metadata import foreignkey
+
+class OrderItem(ObjectModel):
+    order_id: Column[int] = IntegerColumn()
+    product_id: Column[int] = IntegerColumn()
+    quantity: Column[int] = IntegerColumn()
+
+    class Config:
+        constraints = [
+            # Named single-column foreign key with explicit referential action
+            foreignkey("order_id", "Order.id", name="fk_items_order", ondelete="CASCADE"),
+            # Composite foreign key
+            foreignkey(["product_id", "order_id"], ["Product.id", "Order.id"]),
+        ]
+```
+
+`foreignkey(fields, references, *, name=None, ondelete=None, onupdate=None,
+deferrable=False, initially="IMMEDIATE")` accepts a single field/reference or a
+list for composite keys. References may be given as class names (e.g.
+`"Order.id"`) or table names (e.g. `"orders.id"`); class names are resolved
+automatically.
+
 ### Field Parameters
 
 ```python
@@ -333,8 +366,8 @@ from sqlobjects.model import ObjectModel
 from sqlobjects.fields import (
     Column, column, StringColumn, IntegerColumn,
     BooleanColumn, DateTimeColumn, JsonColumn,
-    index, constraint
 )
+from sqlobjects.metadata import index, constraint
 from datetime import datetime
 
 class User(ObjectModel):

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/03-query-operations-guide.md

@@ -41,7 +41,7 @@ users = await User.objects.filter(User.username.like("admin%")).all()
 ### Complex Filtering with Q Objects
 
 ```python
-from sqlobjects.queries import Q
+from sqlobjects import Q
 
 # OR conditions
 users = await User.objects.filter(
@@ -242,7 +242,7 @@ result = await User.objects.with_cte(adults).filter(adults.c.age < 30).all()
 base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("hierarchy", recursive=True)
 recursive_part = Employee.objects.join(base, Employee.manager_id == base.c.id)
 hierarchy = base.union_all(recursive_part)
-all_employees = await Employee.objects.with_cte(hierarchy).select_from(hierarchy).all()
+all_employees = await Employee.objects.with_cte(hierarchy).all()
 ```
 
 ### Manual Joins
@@ -406,7 +406,7 @@ users = await User.objects.filter(
 ```python
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, IntegerColumn, BooleanColumn
-from sqlobjects.queries import Q
+from sqlobjects import Q
 from sqlobjects.expressions import func
 from datetime import datetime, timedelta
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/04-crud-operations-guide.md

@@ -69,7 +69,7 @@ mappings = [
 await User.objects.bulk_update(mappings, match_fields=["id"], batch_size=1000)
 
 # Update all matching records
-await User.objects.filter(User.department == "sales").update_all(is_active=False)
+await User.objects.filter(User.department == "sales").update(is_active=False)
 ```
 
 ### Delete Operations
@@ -84,9 +84,37 @@ user_ids = [1, 2, 3, 4, 5]
 await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 
 # Delete all matching records
-await User.objects.filter(User.is_active == False).delete_all()
+await User.objects.filter(User.is_active == False).delete()
 ```
 
+### Cascade on Delete
+
+Both delete entry points detect and apply cascade behavior automatically:
+
+- **`instance.delete(cascade=None)`** — with the default `None`, the instance
+  auto-detects whether any relationship declares an on-delete cascade and
+  handles related objects accordingly. Pass `cascade=True` to force cascade
+  handling or `cascade=False` to skip it and issue a direct delete.
+- **`QuerySet.delete(cascade="auto")`** — accepts a strategy string:
+  - `"auto"` (default): choose automatically based on the model's relationships
+    and delete signals
+  - `"full"`: complete cascade deletion with full ORM functionality (fires signals)
+  - `"fast"`: fast cascade deletion with minimal ORM processing
+  - `"none"`: direct SQL deletion without any ORM cascade processing
+
+```python
+# Instance delete with explicit cascade control
+user = await User.objects.get(User.id == 1)
+await user.delete(cascade=True)   # force cascade
+await user.delete(cascade=False)  # skip cascade, direct delete
+
+# QuerySet delete with an explicit strategy
+await User.objects.filter(User.is_active == False).delete(cascade="fast")
+```
+
+See the Relationships guide for how cascade behavior is configured on
+relationships and foreign keys.
+
 ### Bulk Operations
 
 ```python
@@ -192,8 +220,8 @@ user.is_active = False
 await user.save()  # Only updates email and is_active fields
 
 # Check dirty fields
-if user._has_changes():
-    changed_fields = user._get_changed_fields()
+changed_fields = user.get_dirty_fields()
+if changed_fields:
     print(f"Modified fields: {changed_fields}")
 ```
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/05-relationships-guide.md

@@ -14,7 +14,7 @@
 
 ```python
 from sqlobjects.model import ObjectModel
-from sqlobjects.fields import Column, StringColumn, foreign_key, relationship, Related
+from sqlobjects.fields import Column, StringColumn, column, foreign_key, relationship, Related
 
 # One-to-Many (Foreign Key)
 class Post(ObjectModel):
@@ -227,6 +227,96 @@ class Category(ObjectModel):
 category = await Category.objects.select_related("parent").prefetch_related("children").get(Category.id == 1)
 ```
 
+## Cascade Operations
+
+SQLObjects offers cascade behavior at two independent layers. Choose the one
+that matches how you want related rows handled when a parent is updated or
+deleted.
+
+### Database-Level (`ondelete` / `onupdate`)
+
+Declared on the `foreign_key()` field descriptor, these translate directly into
+the SQL `ON DELETE` / `ON UPDATE` referential actions enforced by the database
+engine. Use the `OnDelete` enum (or the equivalent string) for clarity.
+
+```python
+from sqlobjects.model import ObjectModel
+from sqlobjects.fields import Column, StringColumn, foreign_key, relationship, Related
+from sqlobjects import OnDelete
+
+class Post(ObjectModel):
+    title: Column[str] = StringColumn(length=200)
+    # DB deletes child rows automatically when the parent User is deleted
+    author_id: Column[int] = foreign_key("User.id", ondelete=OnDelete.CASCADE, nullable=False)
+    author: Related["User"] = relationship("User", back_populates="posts")
+```
+
+Available `OnDelete` values: `CASCADE`, `SET_NULL`, `RESTRICT`, `NO_ACTION`.
+`onupdate` accepts the same set. Strings such as `ondelete="CASCADE"` are also
+accepted.
+
+### ORM-Level (`relationship(cascade=...)`)
+
+Declared on `relationship()`, these are applied by the ORM when it saves or
+deletes an instance — independent of what the database constraint does. Use the
+`CascadePresets` constants for common combinations.
+
+```python
+from sqlobjects import CascadePresets
+
+class User(ObjectModel):
+    username: Column[str] = StringColumn(length=50)
+    # Saving a User cascades to its posts; deleting a User deletes them,
+    # and posts removed from the collection are deleted as orphans
+    posts: Related[list["Post"]] = relationship(
+        "Post",
+        back_populates="author",
+        cascade=CascadePresets.ALL_DELETE_ORPHAN,
+    )
+```
+
+`CascadePresets` combinations:
+
+- `NONE` — no cascade
+- `SAVE_UPDATE` — cascade save/update only
+- `DELETE` — cascade delete only
+- `SAVE_DELETE` — `"save-update, delete"`
+- `ALL` — `"save-update, merge, refresh-expire"`
+- `ALL_DELETE_ORPHAN` — `ALL` plus orphan deletion
+
+The `cascade` argument also accepts a raw string (e.g. `cascade="save-update, delete"`),
+a `CascadeOption`, or a set of `CascadeOption` values.
+
+### Automatic Detection on `delete()`
+
+`Model.delete()` inspects the model's relationships and applies cascade handling
+automatically:
+
+```python
+user = await User.objects.get(User.id == 1)
+await user.delete()               # auto-detects on-delete cascade relations
+await user.delete(cascade=True)   # force ORM cascade handling
+await user.delete(cascade=False)  # skip cascade, direct delete
+```
+
+For bulk deletes, `QuerySet.delete(cascade="auto")` chooses a strategy
+(`"full"`, `"fast"`, or `"none"`) based on the model's relationships and delete
+signals. See the CRUD guide for details.
+
+### ✅ Do
+
+- **Use `ondelete`** when you want the database to enforce referential integrity
+- **Use `relationship(cascade=...)`** when related objects must go through the
+  ORM (e.g. to fire delete signals or handle orphans)
+- **Combine both layers** when appropriate — they are independent
+
+### ❌ Don't
+
+- **Don't assume ORM cascade removes rows the DB constraint handles** (or vice
+  versa) — they are configured separately
+- **Don't rely on `ondelete=CASCADE`** to fire `before_delete` / `after_delete`
+  signals; database-level cascades bypass the ORM
+
 ## Performance Tips
 
 ### N+1 Query Prevention
@@ -348,7 +438,7 @@ class Post(ObjectModel):
 
 ```python
 from sqlobjects.model import ObjectModel
-from sqlobjects.fields import Column, StringColumn, foreign_key, relationship, Related
+from sqlobjects.fields import Column, StringColumn, column, foreign_key, relationship, Related
 from datetime import datetime, timedelta
 
 class User(ObjectModel):

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/07-performance-guide.md

@@ -93,7 +93,7 @@ class User(ObjectModel):
 ```python
 # Production configuration
 await init_db(
-    "postgresql://localhost/db",
+    "postgresql+asyncpg://localhost/db",
     pool_size=20,           # Base connections
     max_overflow=30,        # Burst capacity
     pool_timeout=30,        # Wait time for connection
@@ -243,7 +243,7 @@ await User.objects.bulk_create(data, batch_size=2000)
 
 # Connection pool configuration
 await init_db(
-    "postgresql://localhost/db",
+    "postgresql+asyncpg://localhost/db",
     pool_size=20,
     max_overflow=40,
     pool_pre_ping=True
@@ -258,7 +258,7 @@ await User.objects.bulk_create(data, batch_size=1000)
 
 # Connection pool configuration
 await init_db(
-    "mysql://localhost/db",
+    "mysql+aiomysql://localhost/db",
     pool_size=15,
     max_overflow=25,
     pool_recycle=3600  # Important for MySQL
@@ -273,7 +273,7 @@ await User.objects.bulk_create(data, batch_size=100)
 
 # Single connection for SQLite
 await init_db(
-    "sqlite:///app.db",
+    "sqlite+aiosqlite:///app.db",
     pool_size=1,  # SQLite doesn't support concurrent writes
     max_overflow=0
 )
@@ -431,7 +431,8 @@ users = await User.objects.prefetch_related("posts").all()
 
 ```python
 from sqlobjects.model import ObjectModel
-from sqlobjects.fields import Column, StringColumn, foreign_key, relationship, Related
+from sqlobjects.fields import Column, StringColumn, column, foreign_key, relationship, Related
+from sqlobjects.metadata import index
 from sqlobjects.session import ctx_session
 from sqlobjects.database import init_db
 import time
@@ -456,7 +457,7 @@ class Post(ObjectModel):
 async def main():
     # Configure connection pool
     await init_db(
-        "postgresql://localhost/db",
+        "postgresql+asyncpg://localhost/db",
         pool_size=20,
         max_overflow=30,
         pool_recycle=3600,

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/docs/rules/README.md

@@ -4,11 +4,11 @@ Best practices and usage patterns for SQLObjects, optimized for AI coding assist
 
 ## Quick Navigation
 
-- **[01. Database & Session Guide](01-database-session-guide.md)** - Connection management and transactions
+- **[01. Database & Session Guide](01-database-session-guide.md)** - Connection management, transactions, and SQL logging
 - **[02. Model Definition Guide](02-model-definition-guide.md)** - Model creation and field configuration
 - **[03. Query Operations Guide](03-query-operations-guide.md)** - Filtering, sorting, and data retrieval
 - **[04. CRUD Operations Guide](04-crud-operations-guide.md)** - Create, read, update, delete operations
-- **[05. Relationships Guide](05-relationships-guide.md)** - Model relationships and loading strategies
+- **[05. Relationships Guide](05-relationships-guide.md)** - Model relationships, loading strategies, and cascade operations
 - **[06. Validation & Signals Guide](06-validation-signals-guide.md)** - Data validation and lifecycle hooks
 - **[07. Performance Guide](07-performance-guide.md)** - Optimization techniques and best practices
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.9.0"
+version = "1.10.0"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"
@@ -89,6 +89,7 @@ name = "cz_conventional_commits"
 tag_format = "$version"
 version_scheme = "pep440"
 version_provider = "uv"
+version_files = ["sqlobjects/__init__.py:__version__"]
 update_changelog_on_bump = true
 
 [tool.pyright]

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/sqlobjects/__init__.py

@@ -19,7 +19,7 @@ from .queryset import Q, QuerySet
 from .sql_logging import ObjectLogger, get_caller_frame
 
 
-__version__ = "0.3.0"
+__version__ = "1.10.0"
 
 __all__ = [
     # Core classes

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/sqlobjects/expressions/cte.py

@@ -33,7 +33,7 @@ class CTEExpression:
             >>> base = Employee.objects.filter(Employee.manager_id.is_(None)).cte("hierarchy", recursive=True)
             >>> recursive = Employee.objects.join(base, Employee.manager_id == base.c.id)
             >>> hierarchy = base.union_all(recursive)
-            >>> all_employees = await Employee.objects.with_cte(hierarchy).select_from(hierarchy).all()
+            >>> all_employees = await Employee.objects.with_cte(hierarchy).all()
     """
 
     def __init__(self, queryset: QuerySet, name: str, recursive: bool = False):

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/sqlobjects/mixins.py

@@ -136,6 +136,14 @@ class BaseMixin:
         if not hasattr(self, "_state_manager"):
             self._state_manager = _StateManager()
 
+    def get_dirty_fields(self) -> set[str]:
+        """Get fields modified since the last save or database load.
+
+        Returns:
+            Set of field names with unsaved changes
+        """
+        return self._state_manager.get_dirty_fields().copy()
+
     @classmethod
     def get_table(cls) -> Table:
         """Get SQLAlchemy Core Table definition.

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/sqlobjects/queries/builder.py

@@ -70,16 +70,16 @@ class QueryBuilder:
         return new_builder
 
     def add_ordering(self, *fields):
-        """Add ORDER BY fields to the query.
+        """Set ORDER BY fields for the query, replacing any existing ordering.
 
         Args:
             *fields: Field names or SQLAlchemy ordering expressions
 
         Returns:
-            New QueryBuilder instance with added ordering
+            New QueryBuilder instance with replaced ordering
         """
         new_builder = self.copy()
-        new_builder.ordering.extend(fields)
+        new_builder.ordering = list(fields)
         return new_builder
 
     def add_limit(self, count: int):

{sqlobjects-1.9.0 → sqlobjects-1.10.0}/sqlobjects/queryset.py

@@ -762,7 +762,7 @@ class QuerySet(Generic[T]):
             hierarchy = base.union_all(recursive_part)
             all_employees = await Employee.objects.with_cte(
                 hierarchy
-            ).select_from(hierarchy).all()
+            ).all()
         """
         return CTEExpression(self, name, recursive)
 

{sqlobjects-1.9.0 → sqlobjects-1.10.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.9.0
+Version: 1.10.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -48,6 +48,8 @@ loading. SQLObjects combines the familiar Django ORM API with the performance an
 - **📊 High performance** - Built on SQLAlchemy Core for optimal performance
 - **🔄 Smart operations** - Automatic CREATE/UPDATE detection and bulk operations
 - **🎣 Lifecycle hooks** - Comprehensive signal system for database operations
+- **🌊 Cascade operations** - Database- and ORM-level cascade deletes/updates with automatic detection
+- **📝 SQL logging** - Zero-config `sqlobjects.sql` logger with user-code caller rewriting
 - **🗄️ Multi-database support** - Seamless multi-database configuration and routing
 
 ## 🚀 Quick Start
@@ -89,7 +91,7 @@ active_users = await User.objects.filter(
 ).order_by("-age").limit(10).all()
 
 # Complex queries with Q objects
-from sqlobjects.queries import Q
+from sqlobjects import Q
 
 users = await User.objects.filter(
     Q(User.age >= 18) & (Q(User.username.like("%admin%")) | Q(User.is_active == True))
@@ -380,9 +382,14 @@ uv run pytest
 
 See our [TODO.md](TODO.md) for planned features:
 
-- **v2.0**: Database health checks, window functions, advanced bulk operations
-- **v2.1**: Advanced field optimization, query performance tools
-- **v2.2+**: CTE support, advanced SQL functions
+- **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
+- **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
+- **Query optimization**: index suggestions and slow-query analysis tools
+- **Migrations**: model-diff migration generation and batched data-migration tooling
+
+Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
+query analysis, cascade operations, SQL logging, and high-performance bulk
+operations.
 
 ## 📄 License