sqlobjects 2.0.1__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/CHANGELOG.md +21 -0
  2. {sqlobjects-2.0.1/sqlobjects.egg-info → sqlobjects-2.1.0}/PKG-INFO +9 -2
  3. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/README.md +7 -2
  4. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/01-database-session-guide.md +44 -5
  5. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/02-model-definition-guide.md +25 -0
  6. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/03-query-operations-guide.md +33 -4
  7. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/05-relationships-guide.md +37 -15
  8. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/06-validation-signals-guide.md +32 -0
  9. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/pyproject.toml +8 -4
  10. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/__init__.py +1 -1
  11. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/cascade.py +22 -31
  12. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/contrib/asgi.py +5 -3
  13. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/database/manager.py +44 -30
  14. sqlobjects-2.1.0/sqlobjects/expressions/aggregate.py +173 -0
  15. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/scalar.py +5 -9
  16. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/__init__.py +2 -0
  17. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/core.py +3 -2
  18. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/proxies.py +78 -30
  19. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/descriptors.py +4 -2
  20. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/prefetch.py +62 -63
  21. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/utils.py +50 -11
  22. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/internal/results.py +1 -1
  23. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/metadata.py +106 -30
  24. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/mixins.py +24 -5
  25. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/model.py +45 -72
  26. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/objects/bulk.py +159 -245
  27. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/objects/core.py +62 -58
  28. sqlobjects-2.1.0/sqlobjects/objects/upsert.py +155 -0
  29. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/queries/builder.py +77 -145
  30. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/queries/dialect.py +4 -4
  31. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/queries/executor.py +105 -209
  32. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/queryset.py +64 -45
  33. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/session.py +342 -38
  34. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/signals.py +60 -33
  35. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/sql_logging.py +100 -11
  36. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/utils/naming.py +17 -1
  37. {sqlobjects-2.0.1 → sqlobjects-2.1.0/sqlobjects.egg-info}/PKG-INFO +9 -2
  38. sqlobjects-2.1.0/sqlobjects.egg-info/requires.txt +4 -0
  39. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/tests/test_config.py +5 -5
  40. sqlobjects-2.0.1/sqlobjects/expressions/aggregate.py +0 -112
  41. sqlobjects-2.0.1/sqlobjects/objects/upsert.py +0 -78
  42. sqlobjects-2.0.1/sqlobjects.egg-info/requires.txt +0 -1
  43. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/LICENSE +0 -0
  44. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/04-crud-operations-guide.md +0 -0
  45. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/07-performance-guide.md +0 -0
  46. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/docs/rules/README.md +0 -0
  47. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/setup.cfg +0 -0
  48. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/_install_rules.py +0 -0
  49. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/contrib/__init__.py +0 -0
  50. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/contrib/fastapi.py +0 -0
  51. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/database/__init__.py +0 -0
  52. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/database/config.py +0 -0
  53. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/exceptions.py +0 -0
  54. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/__init__.py +0 -0
  55. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/base.py +0 -0
  56. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/cte.py +0 -0
  57. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/explain.py +0 -0
  58. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/function.py +0 -0
  59. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/mixins.py +0 -0
  60. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/subquery.py +0 -0
  61. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/terminal.py +0 -0
  62. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/expressions/window.py +0 -0
  63. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/functions.py +0 -0
  64. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/__init__.py +0 -0
  65. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/managers.py +0 -0
  66. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/relations/strategies.py +0 -0
  67. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/shortcuts.py +0 -0
  68. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/types/__init__.py +0 -0
  69. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/types/base.py +0 -0
  70. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/types/comparators.py +0 -0
  71. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/types/registry.py +0 -0
  72. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/fields/utils.py +0 -0
  73. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/internal/__init__.py +0 -0
  74. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/internal/operations.py +0 -0
  75. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/objects/__init__.py +0 -0
  76. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/py.typed +0 -0
  77. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/queries/__init__.py +0 -0
  78. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/utils/__init__.py +0 -0
  79. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/utils/inspect.py +0 -0
  80. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/utils/pattern.py +0 -0
  81. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects/validators.py +0 -0
  82. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects.egg-info/SOURCES.txt +0 -0
  83. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects.egg-info/dependency_links.txt +0 -0
  84. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects.egg-info/entry_points.txt +0 -0
  85. {sqlobjects-2.0.1 → sqlobjects-2.1.0}/sqlobjects.egg-info/top_level.txt +0 -0
@@ -1,3 +1,24 @@
1
+ ## 2.1.0 (2026-10-08)
2
+
3
+ ### Feat
4
+
5
+ - **queries**: support aggregation over grouped querysets
6
+ - **relations**: implement scoped async dynamic collections
7
+ - **migrations**: add async Alembic integration and isolated registries
8
+ - **logging**: observe SQL execution across database engines
9
+ - **session**: add transaction commit callbacks
10
+
11
+ ### Fix
12
+
13
+ - **orm**: close review follow-ups in sessions, upsert attribution and dynamic proxies
14
+ - **metadata**: preserve distinct index definitions during deduplication
15
+ - **metadata**: generate portable collision-safe schema names
16
+ - **queries**: preserve composed queryset aggregation semantics
17
+ - **database**: align event registration with SQLAlchemy Core
18
+ - **orm**: preserve distinct semantics and transaction-bound signals
19
+ - **session**: enforce task ownership and cancellation cleanup
20
+ - **orm**: enforce persistence and transaction contracts
21
+
1
22
  ## 2.0.1 (2026-08-31)
2
23
 
3
24
  ### Fix
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sqlobjects
3
- Version: 2.0.1
3
+ Version: 2.1.0
4
4
  Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
5
5
  Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
6
6
  Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -25,6 +25,8 @@ Requires-Python: >=3.12
25
25
  Description-Content-Type: text/markdown
26
26
  License-File: LICENSE
27
27
  Requires-Dist: sqlalchemy[asyncio]>=2.0.44
28
+ Provides-Extra: migrations
29
+ Requires-Dist: alembic>=1.16.5; extra == "migrations"
28
30
  Dynamic: license-file
29
31
 
30
32
  # SQLObjects
@@ -352,6 +354,10 @@ uv run pytest tests/performance/ # Performance tests
352
354
  uv run pytest --cov=sqlobjects
353
355
  ```
354
356
 
357
+ Performance tests verify results, query counts and object release while recording
358
+ timing and memory observations. See the [benchmark instructions](tests/performance/README.md)
359
+ for reproducible runs and JUnit measurement reports.
360
+
355
361
  ## 🤝 Contributing
356
362
 
357
363
  We welcome contributions! Please see our development guidelines:
@@ -385,7 +391,8 @@ See our [TODO.md](TODO.md) for planned features:
385
391
  - **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
386
392
  - **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
387
393
  - **Query optimization**: index suggestions and slow-query analysis tools
388
- - **Migrations**: model-diff migration generation and batched data-migration tooling
394
+ - **Migrations**: native migration orchestration and batched data-migration tooling;
395
+ [Alembic autogeneration and async execution](docs/features/09-migrations.md) are available now.
389
396
 
390
397
  Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
391
398
  query analysis, cascade operations, SQL logging, and high-performance bulk
@@ -323,6 +323,10 @@ uv run pytest tests/performance/ # Performance tests
323
323
  uv run pytest --cov=sqlobjects
324
324
  ```
325
325
 
326
+ Performance tests verify results, query counts and object release while recording
327
+ timing and memory observations. See the [benchmark instructions](tests/performance/README.md)
328
+ for reproducible runs and JUnit measurement reports.
329
+
326
330
  ## 🤝 Contributing
327
331
 
328
332
  We welcome contributions! Please see our development guidelines:
@@ -356,7 +360,8 @@ See our [TODO.md](TODO.md) for planned features:
356
360
  - **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
357
361
  - **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
358
362
  - **Query optimization**: index suggestions and slow-query analysis tools
359
- - **Migrations**: model-diff migration generation and batched data-migration tooling
363
+ - **Migrations**: native migration orchestration and batched data-migration tooling;
364
+ [Alembic autogeneration and async execution](docs/features/09-migrations.md) are available now.
360
365
 
361
366
  Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
362
367
  query analysis, cascade operations, SQL logging, and high-performance bulk
@@ -374,4 +379,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
374
379
 
375
380
  ---
376
381
 
377
- **SQLObjects** - Modern async ORM for Python 3.12+
382
+ **SQLObjects** - Modern async ORM for Python 3.12+
@@ -88,6 +88,33 @@ if has_session("analytics"):
88
88
 
89
89
  ## Best Practices
90
90
 
91
+ ### Database Events
92
+
93
+ - `db.on(name, **options)` targets that database's `engine.sync_engine`, with native
94
+ SQLAlchemy Engine/Pool/Dialect event names and callback arguments.
95
+ - Handlers must be synchronous and must not return awaitables. Declared async
96
+ functions, callable objects and async generators are rejected at registration.
97
+ - `commit` and `rollback` run before the driver completes the operation. Use
98
+ `await session.on_commit(callback)` for effects after successful commit.
99
+ - `before_commit`, `after_commit`, `before_rollback` and `after_rollback` are not
100
+ Engine events and are rejected; do not register them through `db.on()`.
101
+ - Pass native listener options such as `named=True` or `retval=True` where the
102
+ event supports them. Remove a listener with
103
+ `sqlalchemy.event.remove(db.engine.sync_engine, name, handler)`.
104
+ - Register before opening connections. Listener failures follow SQLAlchemy's
105
+ propagation rules. See the [event guide](../features/01-database-setup.md#database-events).
106
+
107
+ ### Async task ownership
108
+
109
+ - Open a separate `ctx_session()` inside each `asyncio.gather()` / `create_task()` worker.
110
+ - A copied ContextVar still references the parent's session; using or joining it
111
+ from another live task raises `TransactionError`.
112
+ - Keep operations in one transaction sequential in its owning task. Use
113
+ `asyncio.timeout()` for time limits without creating a different task.
114
+ - `has_session()` reports only an open session usable by the current task.
115
+ - A closed session cannot be reused. Background work must open a new context.
116
+ - Cancellation rolls back request/context transactions and releases their connections.
117
+
91
118
  ### ✅ Do
92
119
 
93
120
  - **Use context managers** for explicit transaction control
@@ -347,7 +374,7 @@ async def get_user(user_id: int, session: AsyncSession = Depends(get_db_session)
347
374
  ## SQL Logging
348
375
 
349
376
  SQLObjects ships zero-config SQL logging through the standard library `logging`
350
- module. Every executed statement is logged at `DEBUG` level to the logger named
377
+ module. Driver cursor executions are logged at `DEBUG` level to the logger named
351
378
  **`sqlobjects.sql`**. This logger is an `ObjectLogger` (installed automatically
352
379
  on import) that rewrites each record's caller fields — `pathname`, `filename`,
353
380
  `funcName`, `lineno` — to the first user-code frame, skipping internal
@@ -381,10 +408,22 @@ handler.setFormatter(logging.Formatter("%(pathname)s:%(lineno)d - %(message)s"))
381
408
  sql_logger.addHandler(handler)
382
409
  ```
383
410
 
384
- Statement compilation only happens when the logger is actually enabled for
385
- `DEBUG`, so leaving logging off has no runtime cost. Each record carries the
386
- compiled SQL as the message plus an `extra` dict with `sql`, `params`, and
387
- `duration_ms`.
411
+ Logging is installed on each database engine and covers reads, writes, bulk,
412
+ raw SQL and streaming. It does not compile statements again. Disabled logging
413
+ skips timing and frame inspection; enabled logging resolves the user frame
414
+ across the async greenlet bridge.
415
+
416
+ Each record carries `sql`, driver-format `params`, `duration_ms`, `db_name`,
417
+ `dialect`, `executemany`, `rowcount`, `success`, and `error_type`. Parameters may
418
+ be a dictionary, tuple or a sequence of parameter sets. `hide_parameters=True`
419
+ in `init_db()` makes `params` null, including on failure; raw SQL literals are
420
+ not redacted. Errors include only the exception class, not its message.
421
+
422
+ Records count driver calls, not ORM methods or returned rows. Timing excludes
423
+ pool checkout, compilation, later fetching, hydration and commit. `rowcount` can
424
+ be `-1` when unknown or null on failure. Driver failures and cancellation are
425
+ logged without replacing the original exception; ordinary handler failures do
426
+ not affect the database operation.
388
427
 
389
428
  ### Public API
390
429
 
@@ -10,6 +10,17 @@
10
10
 
11
11
  ## Common Usage
12
12
 
13
+ ### Application metadata and migrations
14
+
15
+ - Declare `__registry__ = ModelRegistry()` on an abstract application base before
16
+ defining models to isolate tables. Import it from `sqlobjects.metadata`.
17
+ - Subclasses inherit the registry; omitting it preserves the shared default.
18
+ - Pass the registry directly to Alembic as `target_metadata`, after importing all
19
+ application models. Set an explicit ownership filter for reflected tables.
20
+ - `create_tables()` creates missing tables; use Alembic revisions for schema changes.
21
+ - Migration revisions use historical Core table definitions, not current models
22
+ or ORM signals. Review autogenerated changes and add explicit data backfills.
23
+
13
24
  ### Basic Model
14
25
 
15
26
  ```python
@@ -89,6 +100,13 @@ class User(ObjectModel):
89
100
  ]
90
101
  ```
91
102
 
103
+ Automatic constraint and SQLObjects index names are limited to 63 UTF-8 bytes,
104
+ using a readable prefix and a stable hash when needed. Short, non-conflicting
105
+ names remain unchanged. Explicit names and SQLAlchemy convention names retain
106
+ control over their own naming rules. Partial-index identity includes bound values.
107
+ When upgrading an existing schema with long or conflicting generated names, inspect
108
+ the physical names and write a migration; pin names explicitly to preserve them.
109
+
92
110
  ### Named & Composite Foreign Keys
93
111
 
94
112
  For composite foreign keys, custom constraint names, or explicit referential
@@ -297,6 +315,13 @@ class User(ObjectModel):
297
315
  ]
298
316
  ```
299
317
 
318
+ Index order, expressions, sort direction, collation and dialect options are part
319
+ of an index definition. Keep both composite orders when both query patterns need
320
+ them. Use SQLAlchemy `Index` in `Config.indexes` for expressions. Deduplication
321
+ removes equivalent definitions; a unique index only replaces a plain index with
322
+ matching expressions and options. Conditional DDL indexes are preserved.
323
+ See [index definitions](../features/02-model-definition.md#index-definitions-and-deduplication).
324
+
300
325
  ## Troubleshooting
301
326
 
302
327
  ### Field Not in Constructor
@@ -111,10 +111,39 @@ users = await User.objects.annotate(
111
111
  ).all()
112
112
  ```
113
113
 
114
+ `aggregate()` evaluates filtered/joined rows after DISTINCT and LIMIT/OFFSET.
115
+ Hydration hints (`only()`/`defer()`) do not hide aggregate inputs. It shares its
116
+ statement with SQL rendering, scalar subqueries and EXPLAIN. Use
117
+ `.scalar_subquery()` for a single aggregate; single-field expressions also work
118
+ in column comparisons. Empty inputs keep SQL defaults (COUNT zero, SUM/AVG null).
119
+
120
+ For annotation inputs use `func.sum(sqlalchemy.column("alias"))`. After ordinary
121
+ DISTINCT, joined/scalar inputs must already be projected through `annotate()`;
122
+ adding an unselected input would change deduplication and raises `QueryError`.
123
+ Field-specific DISTINCT remains PostgreSQL-only. With `group_by()`, `aggregate()`
124
+ summarizes the resulting group rows, preserving HAVING and slices. Use grouping
125
+ keys or `sqlalchemy.column("annotation_alias")` as outer aggregate inputs; raw
126
+ model fields outside GROUP BY raise `QueryError`. Annotation aliases must not
127
+ shadow model columns. HAVING without explicit grouping and row locking are rejected.
128
+
114
129
  ### Grouping
115
130
 
116
- Grouped aggregation returns **one row per group**, not model instances — use
117
- values-mode: list the grouping columns and aggregate aliases in `.values()`.
131
+ Use `values()` to return individual groups. Use `aggregate()` to summarize them:
132
+
133
+ ```python
134
+ from sqlalchemy import column
135
+
136
+ summary = await User.objects.annotate(member_count=func.count()).group_by("department").aggregate(
137
+ departments=func.count(), average_members=func.avg(column("member_count"))
138
+ )
139
+ ```
140
+
141
+ `departments` counts groups. Order by an annotation alias (for example
142
+ `order_by("-member_count")`) before slicing to aggregate the selected groups.
143
+ Grouping expressions retain their SQL and table identity.
144
+
145
+ For **one row per group**, use values-mode: list the grouping columns and
146
+ aggregate aliases in `.values()`.
118
147
 
119
148
  ```python
120
149
  # Group by with aggregation → list[dict], one dict per group
@@ -207,7 +236,7 @@ count = await User.objects.skip_default_ordering().count()
207
236
 
208
237
  ```python
209
238
  # Scalar subquery (single value)
210
- avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type="scalar")
239
+ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).scalar_subquery()
211
240
  older_users = await User.objects.filter(User.age > avg_age).all()
212
241
 
213
242
  # EXISTS subquery (boolean condition)
@@ -452,7 +481,7 @@ users = await User.objects.only(
452
481
  ).order_by("-created_at").limit(10).offset(20).all()
453
482
 
454
483
  # Subquery
455
- avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type="scalar")
484
+ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).scalar_subquery()
456
485
  older_users = await User.objects.filter(User.age > avg_age).all()
457
486
 
458
487
  # Performance optimization
@@ -69,26 +69,48 @@ comments = await Comment.objects.select_related("post__author").all()
69
69
 
70
70
  ### Advanced prefetch_related
71
71
 
72
+ Dynamic relationships (`lazy="dynamic"`) cannot be eagerly loaded. See the
73
+ dynamic collection contract below before choosing this strategy.
74
+
75
+ Custom queryset keys must name declared relationships. Filtering and ordering are
76
+ supported; sliced querysets and arbitrary output aliases are rejected.
77
+
72
78
  ```python
73
- # Custom QuerySet for filtering and ordering
74
79
  users = await User.objects.prefetch_related(
75
- published_posts=Post.objects.filter(Post.is_published == True)
76
- .order_by('-created_at')
77
- .limit(5)
80
+ posts=Post.objects.filter(Post.is_published == True).order_by('-created_at')
78
81
  ).all()
79
82
 
80
- # Access prefetched data
81
83
  for user in users:
82
- recent_posts = await user.published_posts.fetch()
84
+ published_posts = await user.load_relation("posts")
83
85
 
84
- # Multiple advanced prefetch configurations
85
86
  users = await User.objects.prefetch_related(
86
- active_posts=Post.objects.filter(Post.status == "active"),
87
- draft_posts=Post.objects.filter(Post.status == "draft"),
88
- recent_comments=Comment.objects.order_by('-created_at').limit(10)
87
+ posts=Post.objects.filter(Post.status == "active"),
88
+ comments=Comment.objects.order_by('-created_at')
89
89
  ).all()
90
90
  ```
91
91
 
92
+ ### Dynamic Collections
93
+
94
+ - Define a one-to-many or many-to-many relationship with `lazy="dynamic"`; use
95
+ `RelatedQuerySet["Model"]` from `sqlobjects.fields` for its annotation.
96
+ - Query with `await parent.children.filter(...).all()`, `.count()`, `.exists()`,
97
+ projections, slices or `async for`. Query construction does not execute SQL.
98
+ - `.fetch()` and `load_relation()` requery without caching a list. Synchronous
99
+ iteration, `len()` and truthiness are rejected.
100
+ - New queries use the parent's current keys and database/session binding.
101
+ Existing QuerySets keep their original conditions and binding.
102
+ - A complete parent primary key is required. Load deferred relation keys before
103
+ constructing a query; null reference values yield an empty query.
104
+ - `remote_fields` selects the child FK when several point to the parent. Composite
105
+ FK mappings and non-primary references are supported. Existing M2M tables use
106
+ membership subqueries to prevent duplicate targets.
107
+ - Custom join conditions and scalar dynamic relationships are rejected. Use
108
+ `uselist=True` with `remote_fields` for self-referential child collections.
109
+ - QuerySet writes affect target rows, not M2M links. This proxy does not supply
110
+ relationship add/remove/set or manager creation methods.
111
+
112
+ See the [dynamic collection examples](../features/05-relationships.md#dynamic-collections).
113
+
92
114
  ### Accessing Relationships
93
115
 
94
116
  ```python
@@ -131,7 +153,7 @@ posts = await Post.objects.select_related(Post.author).all()
131
153
 
132
154
  # Good: Filtered prefetch
133
155
  users = await User.objects.prefetch_related(
134
- recent_posts=Post.objects.filter(
156
+ posts=Post.objects.filter(
135
157
  Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
136
158
  ).order_by('-created_at')
137
159
  ).all()
@@ -349,7 +371,7 @@ posts = await Post.objects.select_related("author").defer(
349
371
 
350
372
  # Filter prefetched relationships
351
373
  users = await User.objects.prefetch_related(
352
- recent_posts=Post.objects.filter(
374
+ posts=Post.objects.filter(
353
375
  Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
354
376
  ).order_by('-created_at').limit(10)
355
377
  ).all()
@@ -477,11 +499,11 @@ posts = await Post.objects.select_related("author").prefetch_related("comments",
477
499
 
478
500
  # Advanced prefetch with filtering
479
501
  users = await User.objects.prefetch_related(
480
- recent_posts=Post.objects.filter(
502
+ posts=Post.objects.filter(
481
503
  Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
482
- ).order_by('-created_at').limit(5)
504
+ ).order_by('-created_at')
483
505
  ).all()
484
506
 
485
507
  for user in users:
486
- recent_posts = await user.recent_posts.fetch()
508
+ recent_posts = await user.load_relation("posts")
487
509
  ```
@@ -10,6 +10,23 @@
10
10
 
11
11
  ## Common Usage
12
12
 
13
+ ### Commit callbacks
14
+
15
+ - `after_*` signals describe operation completion, not transaction commit.
16
+ - Use `await context.on_commit(callback)` for external effects from an instance or bulk
17
+ signal, or `await session.on_commit(callback)` / `await on_commit(callback)`
18
+ from `sqlobjects.session` in application code.
19
+ - Pass a callable. Sync functions and awaitable return values run inline after
20
+ successful commit, in registration order. Rollback discards pending callbacks,
21
+ including those registered in a rolled-back savepoint.
22
+ - Manager `create()`, bulk methods and QuerySet writes provide transaction
23
+ boundaries for their hooks. For direct instance `save()`, use `ctx_session()`
24
+ when registering from `before_*`. Outside a transaction registration executes immediately.
25
+ - `robust=True` logs ordinary callback errors and continues. Callback errors never
26
+ undo an already committed transaction; cancellation is not swallowed.
27
+ - Open a new session for database work in callbacks. Use an outbox if delivery
28
+ must survive a process crash between commit and callback execution.
29
+
13
30
  ### Field-level Validation
14
31
 
15
32
  ```python
@@ -55,6 +72,10 @@ class User(ObjectModel):
55
72
 
56
73
  ### Instance-level Signals
57
74
 
75
+ `objects.create()` emits save/create instance hooks around an INSERT, including
76
+ when a primary key is supplied. Before hooks run before validation and SQL;
77
+ after hooks see the persisted instance. Sync handlers may return an awaitable.
78
+
58
79
  ```python
59
80
  from sqlobjects.model import ObjectModel
60
81
  from sqlobjects.signals import SignalContext
@@ -104,6 +125,17 @@ class User(ObjectModel):
104
125
 
105
126
  ### Bulk Operation Signals
106
127
 
128
+ Manager bulk methods emit class hooks once per batch, with no instance hooks.
129
+ Create/update also emit generic bulk-save hooks. Before counts are input sizes;
130
+ after counts match each batch's successful result count. Empty input emits no
131
+ hooks. QuerySet update/delete hooks run once per call; before counts are unknown,
132
+ and only QuerySet update supplies uniform `update_data`.
133
+
134
+ Use `context.session` for work in the batch transaction and `context.on_commit()`
135
+ for effects after its commit. Hook failures propagate even with `IGNORE` or
136
+ `COLLECT`; earlier committed batches remain stored. See the
137
+ [full signal contract](../features/06-validation-signals.md#bulk-operation-signals).
138
+
107
139
  ```python
108
140
  class User(ObjectModel):
109
141
  @classmethod
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "sqlobjects"
3
- version = "2.0.1"
3
+ version = "2.1.0"
4
4
  description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -37,6 +37,9 @@ dependencies = [
37
37
  "sqlalchemy[asyncio]>=2.0.44",
38
38
  ]
39
39
 
40
+ [project.optional-dependencies]
41
+ migrations = ["alembic>=1.16.5"]
42
+
40
43
  [project.scripts]
41
44
  sqlobjects-install-rules = "sqlobjects._install_rules:main"
42
45
 
@@ -55,7 +58,8 @@ dev = [
55
58
  "setuptools>=82.0.0",
56
59
  ]
57
60
  test = [
58
- "aiomysql>=0.3.2",
61
+ "alembic>=1.16.5",
62
+ "aiomysql[rsa]>=0.3.2",
59
63
  "aiosqlite>=0.22.1",
60
64
  "asyncpg>=0.31.0",
61
65
  "pytest>=9.0.2",
@@ -93,7 +97,7 @@ version_files = ["sqlobjects/__init__.py:__version__"]
93
97
  update_changelog_on_bump = true
94
98
 
95
99
  [tool.pyright]
96
- include = ["sqlobjects", "tests"]
100
+ include = ["sqlobjects", "tests", "examples/migrations"]
97
101
  exclude = ["**/__pycache__"]
98
102
  pythonVersion = "3.12"
99
103
  reportMissingImports = "error"
@@ -144,4 +148,4 @@ python_files = ["test_*.py", "*_test.py"]
144
148
  addopts = [
145
149
  "--strict-markers",
146
150
  "-v"
147
- ]
151
+ ]
@@ -19,7 +19,7 @@ from .queryset import Q, QuerySet
19
19
  from .sql_logging import ObjectLogger, get_caller_frame
20
20
 
21
21
 
22
- __version__ = "2.0.1"
22
+ __version__ = "2.1.0"
23
23
 
24
24
  __all__ = [
25
25
  # Core classes
@@ -355,35 +355,30 @@ class CascadeExecutor:
355
355
  ) -> "ObjectModel":
356
356
  """Execute save operation with cascade handling."""
357
357
  if session is None:
358
- session = get_session()
359
-
360
- # Save root instance first to get primary key
361
- await instance._save_internal(validate=validate, session=session) # noqa
362
-
363
- # Process cascade relationships if needed
364
- if hasattr(instance, "_state_manager"):
365
- cascade_relationships = instance._state_manager.get_cascade_relationships() # noqa
366
- if cascade_relationships:
367
- await self._process_cascade_relationships(instance, session)
358
+ session = get_session(readonly=False)
368
359
 
360
+ async with session.transaction() as transaction:
361
+ await instance._save_internal(validate=validate, session=transaction)
362
+ if instance._state_manager.get_cascade_relationships():
363
+ await self._process_cascade_relationships(instance, transaction)
369
364
  return instance
370
365
 
371
366
  async def execute_delete_operation(
372
367
  self, target, cascade_strategy: str = "auto", session: "AsyncSession | None" = None
373
368
  ) -> int:
374
369
  """Execute delete operation with cascade handling."""
370
+ is_queryset = hasattr(target, "_table") and hasattr(target, "_model_class")
375
371
  if session is None:
376
- session = get_session()
377
-
378
- # Handle QuerySet deletion
379
- if hasattr(target, "_table") and hasattr(target, "_model_class"):
380
- return await self._execute_queryset_delete(target, cascade_strategy, session)
381
-
382
- # Handle single instance deletion
383
- if has_cascade_delete_relations(target.__class__):
384
- await self._delete_related_objects(target, session)
385
- await target._delete_internal(session=session) # noqa
386
- return 1
372
+ session = target._executor._get_session("delete") if is_queryset else target.get_session(readonly=False)
373
+ assert session is not None
374
+ async with session.transaction() as transaction:
375
+ if is_queryset:
376
+ target._validate_write_query()
377
+ return await self._execute_queryset_delete(target.using(transaction), cascade_strategy, transaction)
378
+ if has_cascade_delete_relations(target.__class__):
379
+ await self._delete_related_objects(target, transaction)
380
+ await target._delete_internal(session=transaction)
381
+ return 1
387
382
 
388
383
  @staticmethod
389
384
  async def execute_update_operation(queryset, values: dict, session: "AsyncSession | None" = None) -> int:
@@ -404,7 +399,7 @@ class CascadeExecutor:
404
399
  if not instances:
405
400
  return
406
401
  if session is None:
407
- session = get_session()
402
+ session = get_session(readonly=False)
408
403
 
409
404
  # Filter valid instances
410
405
  valid_instances = [
@@ -440,7 +435,7 @@ class CascadeExecutor:
440
435
  if not instances:
441
436
  return
442
437
  if session is None:
443
- session = get_session()
438
+ session = get_session(readonly=False)
444
439
  valid_instances = []
445
440
  for instance in instances:
446
441
  if not hasattr(instance, "save"):
@@ -464,7 +459,7 @@ class CascadeExecutor:
464
459
  if not instances:
465
460
  return
466
461
  if session is None:
467
- session = get_session()
462
+ session = get_session(readonly=False)
468
463
  valid_instances = []
469
464
  for instance in instances:
470
465
  if not hasattr(instance, "delete"):
@@ -486,7 +481,7 @@ class CascadeExecutor:
486
481
  if not instances or not update_data:
487
482
  return
488
483
  if session is None:
489
- session = get_session()
484
+ session = get_session(readonly=False)
490
485
  valid_instances = []
491
486
  for instance in instances:
492
487
  if not hasattr(instance, "save"):
@@ -529,19 +524,15 @@ class CascadeExecutor:
529
524
 
530
525
  batch_size = 50 if total_count > 100 else total_count
531
526
  deleted_count = 0
532
- offset = 0
533
-
534
527
  while True:
535
- batch = await queryset.offset(offset).limit(batch_size).all()
528
+ batch = await queryset.limit(batch_size).all()
536
529
  if not batch:
537
530
  break
538
531
 
539
532
  for instance in batch:
540
- await instance.using(session).delete(cascade=False)
533
+ await instance.using(session).delete(cascade=True)
541
534
  deleted_count += 1
542
535
 
543
- offset += batch_size
544
-
545
536
  return deleted_count
546
537
 
547
538
  async def _delete_with_fast_cascade(self, queryset, session: "AsyncSession") -> int:
@@ -54,10 +54,12 @@ class SessionMiddleware:
54
54
  await self.app(scope, receive, send)
55
55
  if not self.readonly:
56
56
  await session.commit()
57
- except Exception:
57
+ except BaseException:
58
58
  if not self.readonly:
59
59
  await session.rollback()
60
60
  raise
61
61
  finally:
62
- await session.close()
63
- _SessionContextManager.reset_session(token)
62
+ try:
63
+ await session.close()
64
+ finally:
65
+ _SessionContextManager.reset_session(token)