sqlobjects 1.9.1__tar.gz → 2.0.0__tar.gz

{sqlobjects-1.9.1 → sqlobjects-2.0.0}/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 2.0.0 (2026-08-19)
+
+### BREAKING CHANGE
+
+- annotate().group_by().all() with non-primary-key
+grouping and group_by().aggregate() now raise QueryError; both
+previously returned silently wrong results. QuerySet.create() removed
+(never wrote to the database) — use Model.objects.create().
+
+### Feat
+
+- **rules**: stamp installed rule files with the package version
+- **query**: strict GROUP BY semantics, values-mode aggregation, manager-only hints
+- **orm**: support SQLAlchemy expressions as write values
+- **bulk**: make BulkResult a sequence and guarantee insert RETURNING order
+- **session**: add join_ambient option to ctx_session and warn on nested sessions
+- **build**: ship py.typed marker so type checkers see the package as typed
+
+## 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

{sqlobjects-1.9.1/sqlobjects.egg-info → sqlobjects-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.9.1
+Version: 2.0.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.1 → sqlobjects-2.0.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.1 → sqlobjects-2.0.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,
@@ -120,14 +120,27 @@ await init_db(
 - **Don't create sessions manually** (use context managers)
 
 ```python
-# Caution: Nested sessions use separate transactions
+# DANGER: Nested ctx_session opens a SECOND physical connection
 async with ctx_session() as session1:
     user = await User.objects.using(session1).create(username="alice")
     async with ctx_session() as session2:
-        # Nesting is safe (Token-based restore), but uses a separate transaction
-        # — session1 won't see session2's uncommitted changes and vice versa
+        # ContextVar restore is safe, but session2 is a separate physical
+        # connection with its own transaction:
+        # - session1 won't see session2's uncommitted changes and vice versa
+        # - if session2 writes a row that session1 holds a lock on, session2
+        #   blocks forever while session1 sits idle-in-transaction waiting for
+        #   this coroutine to return. The database deadlock detector CANNOT
+        #   see this cycle — it manifests as request timeouts, and session1's
+        #   locks block unrelated requests until then.
         await Post.objects.using(session2).create(author_id=user.id)
 
+# Good: join the ambient session when running inside a possibly-active transaction
+async with ctx_session(join_ambient=True) as session:
+    # Reuses the outer session if one exists (no second connection);
+    # creates a new one only at the top level. Lifecycle (commit/rollback/close)
+    # belongs to the outermost owner.
+    await Post.objects.using(session).create(author_id=user.id)
+
 # Bad: No transaction control
 user = await User.objects.create(username="alice")
 # If next operation fails, user is already created
@@ -141,7 +154,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 +262,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 +277,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 +299,7 @@ async def main():
         )
 
     # Cleanup
-    await close_all_dbs()
+    await close_dbs()
 
 # Run
 import asyncio
@@ -330,3 +343,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.1 → sqlobjects-2.0.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.1 → sqlobjects-2.0.0}/docs/rules/03-query-operations-guide.md

@@ -24,7 +24,7 @@ users = await User.objects.filter(
 
 # Comparison operators
 adults = await User.objects.filter(User.age >= 18).all()
-recent = await User.objects.filter(User.created_at > datetime.now() - timedelta(days=7)).all()
+recent = await User.objects.filter(User.created_at > datetime.now(timezone.utc) - timedelta(days=7)).all()
 ```
 
 ### String Operations
@@ -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(
@@ -113,18 +113,33 @@ users = await User.objects.annotate(
 
 ### Grouping
 
+Grouped aggregation returns **one row per group**, not model instances — use
+values-mode: list the grouping columns and aggregate aliases in `.values()`.
+
 ```python
-# Group by with aggregation
+# Group by with aggregation → list[dict], one dict per group
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
+# [{"department": "sales", "user_count": 10}, ...]
 
 # Having clause (filter groups)
 large_depts = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").having(func.count() > 10).all()
+).group_by("department").having(func.count() > 10).values("department", "user_count")
+
+# Grouping by the primary key is the one case where .all() stays valid:
+# each group is exactly one model row (e.g. counting related rows per user)
+users = await User.objects.annotate(post_count=Post.id.count()) \
+    .join(Post.__table__, User.id == Post.author_id, join_type="left") \
+    .group_by(User.id).all()
 ```
 
+**Do not** call `.all()` on a query grouped by a non-primary-key column — the
+selected model columns would fall outside GROUP BY, so SQLObjects raises
+`QueryError` instead of silently corrupting the aggregation (each group would
+collapse to a single row).
+
 ### Distinct
 
 ```python
@@ -242,7 +257,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,9 +421,9 @@ 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
+from datetime import datetime, timedelta, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -426,10 +441,10 @@ admins_or_staff = await User.objects.filter(
     Q(User.department == "admin") | Q(User.department == "staff")
 ).all()
 
-# Aggregation
+# Aggregation (one row per group — see "Grouping" section)
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
 
 # Pagination with field selection
 users = await User.objects.only(

{sqlobjects-1.9.1 → sqlobjects-2.0.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,63 @@ 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()
 ```
 
+### BulkResult (return_objects=True)
+
+`bulk_create` / `bulk_update` / `bulk_delete` return a plain `int` count by default.
+With `return_objects=True` they return a **`BulkResult`**, not a list:
+
+```python
+result = await User.objects.bulk_create(users_data, return_objects=True)
+
+result.objects        # list[User] — or list[dict] when return_fields is given
+result.success_count  # rows written successfully
+result.error_count    # rows that failed
+result.total_count    # input rows (success + failed)
+result.failed_records # list[FailedRecord] with .index/.data/.error per failure
+```
+
+Key semantics:
+
+- **Sequence protocol**: `len(result)`, `for obj in result`, and `result[i]` all
+  operate on `result.objects` (the successfully returned objects).
+- **Partial failure**: `len(result)` can be less than `result.total_count`.
+  Always read `success_count` / `failed_records` when `error_count > 0`.
+- **Order guarantee**: for `bulk_create`, `result.objects` order matches the
+  input rows order.
+- **`return_fields`**: when specified, `objects` contains dicts limited to those
+  fields instead of model instances.
+
+### 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
@@ -98,9 +152,11 @@ users_data = [
 await User.objects.bulk_create(users_data, batch_size=500)
 
 # Bulk update with match fields
+# (bulk rows must be plain values — datetime.now(timezone.utc) here, never naive
+# local time; per-row SQL expressions are not supported in bulk operations)
 mappings = [
-    {"id": 1, "status": "active", "last_seen": datetime.now()},
-    {"id": 2, "status": "inactive", "last_seen": datetime.now()},
+    {"id": 1, "status": "active", "last_seen": datetime.now(timezone.utc)},
+    {"id": 2, "status": "inactive", "last_seen": datetime.now(timezone.utc)},
 ]
 await User.objects.bulk_update(mappings, match_fields=["id"])
 
@@ -109,6 +165,68 @@ user_ids = list(range(1, 1001))
 await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 ```
 
+## SQL Expressions as Write Values
+
+`create()` and `QuerySet.update()` accept SQLAlchemy expressions as values —
+they are evaluated by the database, not serialized in Python:
+
+```python
+from sqlalchemy import func, text
+
+# Database clock, not application clock
+await Task.objects.filter(Task.id == task_id).update(claimed_at=func.now())
+
+# Relative updates (atomic, no read-modify-write race)
+await User.objects.filter(User.id == user_id).update(age=User.age + 1)
+
+# SQL fragments
+await Task.objects.filter(Task.id == task_id).update(
+    not_before=text("now() + interval '60 seconds'")  # PostgreSQL
+)
+
+# Also works in create()
+task = await Task.objects.create(name="reindex", scheduled_at=func.now())
+```
+
+Notes:
+
+- After `create()` with an expression value, the in-memory instance attribute
+  holds the expression object, not the database result — re-fetch the row if
+  you need the actual stored value.
+- **Bulk operations (`bulk_create` / `bulk_update`) do not support per-row SQL
+  expressions** — they execute with driver-level parameter batching, which
+  requires plain values.
+
+### Clock Discipline
+
+Any field that participates in SQL-side time comparison (scheduling, leases,
+debounce, `not_before` checks) **must use the database clock**, never
+`datetime.now()` from the application:
+
+```python
+# Bad: naive local time — breaks when app timezone != database timezone
+await Task.objects.filter(Task.id == tid).update(not_before=datetime.now())
+
+# Good: database clock — always consistent with SQL-side now() comparisons
+await Task.objects.filter(Task.id == tid).update(not_before=func.now())
+```
+
+A naive `datetime.now()` written from an application in UTC+8 compared against
+PostgreSQL's `now()` (UTC) schedules work 8 hours into the future.
+
+Which clock to use, by scenario:
+
+| Scenario | Correct clock | Example |
+|---|---|---|
+| SQL-compared writes (scheduling, leases, `not_before`) | database clock | `update(not_before=func.now())` |
+| Creation timestamps | database clock via default | `server_default=func.now()` |
+| Instance attributes / signal handlers (need a real value in memory) | aware app clock | `self.updated_at = datetime.now(timezone.utc)` |
+| Bulk operation rows (no per-row SQL expressions) | aware app clock | `{"last_seen": datetime.now(timezone.utc)}` |
+| Read-side window comparisons (relative windows computed in Python) | aware app clock | `filter(created_at >= datetime.now(timezone.utc) - timedelta(days=7))` |
+
+Never naive `datetime.now()` — in every scenario above the naive form breaks
+as soon as the application timezone differs from UTC.
+
 ## Best Practices
 
 ### ✅ Do
@@ -192,8 +310,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}")
 ```
 
@@ -324,7 +442,7 @@ await User.objects.bulk_create(users_data, batch_size=1000)
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, BooleanColumn
 from sqlobjects.session import ctx_session
-from datetime import datetime
+from datetime import datetime, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)