sqlobjects 2.0.1__tar.gz → 2.1.1__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 (86) hide show
  1. {sqlobjects-2.0.1/sqlobjects.egg-info → sqlobjects-2.1.1}/PKG-INFO +17 -8
  2. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/README.md +14 -7
  3. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/01-database-session-guide.md +54 -7
  4. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/02-model-definition-guide.md +25 -0
  5. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/03-query-operations-guide.md +47 -13
  6. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/04-crud-operations-guide.md +1 -1
  7. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/05-relationships-guide.md +48 -23
  8. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/06-validation-signals-guide.md +47 -12
  9. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/07-performance-guide.md +3 -3
  10. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/pyproject.toml +9 -5
  11. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/__init__.py +1 -1
  12. sqlobjects-2.1.1/sqlobjects/_compat.py +61 -0
  13. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/cascade.py +22 -31
  14. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/asgi.py +5 -3
  15. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/manager.py +44 -30
  16. sqlobjects-2.1.1/sqlobjects/expressions/aggregate.py +173 -0
  17. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/scalar.py +5 -9
  18. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/__init__.py +2 -0
  19. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/core.py +5 -4
  20. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/proxies.py +78 -30
  21. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/descriptors.py +4 -2
  22. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/prefetch.py +62 -63
  23. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/utils.py +50 -11
  24. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/results.py +1 -1
  25. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/metadata.py +110 -37
  26. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/mixins.py +24 -5
  27. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/model.py +45 -72
  28. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/bulk.py +159 -245
  29. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/core.py +62 -58
  30. sqlobjects-2.1.1/sqlobjects/objects/upsert.py +155 -0
  31. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/builder.py +77 -145
  32. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/dialect.py +4 -4
  33. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/executor.py +105 -209
  34. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queryset.py +64 -45
  35. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/session.py +342 -38
  36. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/signals.py +60 -33
  37. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/sql_logging.py +107 -11
  38. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/naming.py +17 -1
  39. {sqlobjects-2.0.1 → sqlobjects-2.1.1/sqlobjects.egg-info}/PKG-INFO +17 -8
  40. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/SOURCES.txt +1 -1
  41. sqlobjects-2.1.1/sqlobjects.egg-info/requires.txt +4 -0
  42. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/tests/test_config.py +5 -5
  43. sqlobjects-2.0.1/CHANGELOG.md +0 -293
  44. sqlobjects-2.0.1/sqlobjects/expressions/aggregate.py +0 -112
  45. sqlobjects-2.0.1/sqlobjects/objects/upsert.py +0 -78
  46. sqlobjects-2.0.1/sqlobjects.egg-info/requires.txt +0 -1
  47. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/LICENSE +0 -0
  48. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/README.md +0 -0
  49. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/setup.cfg +0 -0
  50. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/_install_rules.py +0 -0
  51. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/__init__.py +0 -0
  52. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/fastapi.py +0 -0
  53. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/__init__.py +0 -0
  54. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/config.py +0 -0
  55. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/exceptions.py +0 -0
  56. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/__init__.py +0 -0
  57. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/base.py +0 -0
  58. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/cte.py +0 -0
  59. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/explain.py +0 -0
  60. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/function.py +0 -0
  61. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/mixins.py +0 -0
  62. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/subquery.py +0 -0
  63. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/terminal.py +0 -0
  64. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/window.py +0 -0
  65. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/functions.py +0 -0
  66. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/__init__.py +0 -0
  67. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/managers.py +0 -0
  68. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/strategies.py +0 -0
  69. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/shortcuts.py +0 -0
  70. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/__init__.py +0 -0
  71. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/base.py +0 -0
  72. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/comparators.py +0 -0
  73. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/registry.py +0 -0
  74. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/utils.py +0 -0
  75. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/__init__.py +0 -0
  76. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/operations.py +0 -0
  77. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/__init__.py +0 -0
  78. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/py.typed +0 -0
  79. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/__init__.py +0 -0
  80. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/__init__.py +0 -0
  81. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/inspect.py +0 -0
  82. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/pattern.py +0 -0
  83. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/validators.py +0 -0
  84. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/dependency_links.txt +0 -0
  85. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/entry_points.txt +0 -0
  86. {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sqlobjects
3
- Version: 2.0.1
3
+ Version: 2.1.1
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>
@@ -24,7 +24,9 @@ Classifier: Typing :: Typed
24
24
  Requires-Python: >=3.12
25
25
  Description-Content-Type: text/markdown
26
26
  License-File: LICENSE
27
- Requires-Dist: sqlalchemy[asyncio]>=2.0.44
27
+ Requires-Dist: sqlalchemy[asyncio]<2.2,>=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
@@ -176,7 +178,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
176
178
  # Single database transaction
177
179
  async with ctx_session() as session:
178
180
  user = await User.objects.using(session).create(username="bob")
179
- posts = await user.posts.using(session).all()
181
+ posts = await Post.objects.using(session).filter(author_id=user.id).all()
180
182
  # Automatic commit on success, rollback on error
181
183
 
182
184
  # Multi-database transactions
@@ -300,10 +302,12 @@ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type
300
302
  older_users = await User.objects.filter(User.age > avg_age).all()
301
303
 
302
304
  # Manual joins and locking
303
- posts = await Post.objects.join(
304
- User, # Using Model class (recommended)
305
- Post.author_id == User.id
306
- ).select_for_update(nowait=True).all()
305
+ # Row locks need an explicit transaction on PostgreSQL/MySQL
306
+ async with ctx_session():
307
+ posts = await Post.objects.join(
308
+ User, # Using Model class (recommended)
309
+ Post.author_id == User.id
310
+ ).select_for_update(nowait=True).all()
307
311
 
308
312
  # Raw SQL when needed
309
313
  users = await User.objects.raw(
@@ -352,6 +356,10 @@ uv run pytest tests/performance/ # Performance tests
352
356
  uv run pytest --cov=sqlobjects
353
357
  ```
354
358
 
359
+ Performance tests verify results, query counts and object release while recording
360
+ timing and memory observations. See the [benchmark instructions](tests/performance/README.md)
361
+ for reproducible runs and JUnit measurement reports.
362
+
355
363
  ## 🤝 Contributing
356
364
 
357
365
  We welcome contributions! Please see our development guidelines:
@@ -385,7 +393,8 @@ See our [TODO.md](TODO.md) for planned features:
385
393
  - **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
386
394
  - **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
387
395
  - **Query optimization**: index suggestions and slow-query analysis tools
388
- - **Migrations**: model-diff migration generation and batched data-migration tooling
396
+ - **Migrations**: native migration orchestration and batched data-migration tooling;
397
+ [Alembic autogeneration and async execution](docs/features/09-migrations.md) are available now.
389
398
 
390
399
  Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
391
400
  query analysis, cascade operations, SQL logging, and high-performance bulk
@@ -147,7 +147,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
147
147
  # Single database transaction
148
148
  async with ctx_session() as session:
149
149
  user = await User.objects.using(session).create(username="bob")
150
- posts = await user.posts.using(session).all()
150
+ posts = await Post.objects.using(session).filter(author_id=user.id).all()
151
151
  # Automatic commit on success, rollback on error
152
152
 
153
153
  # Multi-database transactions
@@ -271,10 +271,12 @@ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type
271
271
  older_users = await User.objects.filter(User.age > avg_age).all()
272
272
 
273
273
  # Manual joins and locking
274
- posts = await Post.objects.join(
275
- User, # Using Model class (recommended)
276
- Post.author_id == User.id
277
- ).select_for_update(nowait=True).all()
274
+ # Row locks need an explicit transaction on PostgreSQL/MySQL
275
+ async with ctx_session():
276
+ posts = await Post.objects.join(
277
+ User, # Using Model class (recommended)
278
+ Post.author_id == User.id
279
+ ).select_for_update(nowait=True).all()
278
280
 
279
281
  # Raw SQL when needed
280
282
  users = await User.objects.raw(
@@ -323,6 +325,10 @@ uv run pytest tests/performance/ # Performance tests
323
325
  uv run pytest --cov=sqlobjects
324
326
  ```
325
327
 
328
+ Performance tests verify results, query counts and object release while recording
329
+ timing and memory observations. See the [benchmark instructions](tests/performance/README.md)
330
+ for reproducible runs and JUnit measurement reports.
331
+
326
332
  ## 🤝 Contributing
327
333
 
328
334
  We welcome contributions! Please see our development guidelines:
@@ -356,7 +362,8 @@ See our [TODO.md](TODO.md) for planned features:
356
362
  - **Database management**: connection health checks, dynamic default-database switching, connection-pool monitoring
357
363
  - **Advanced SQL**: additional aggregate functions (array / JSON aggregation)
358
364
  - **Query optimization**: index suggestions and slow-query analysis tools
359
- - **Migrations**: model-diff migration generation and batched data-migration tooling
365
+ - **Migrations**: native migration orchestration and batched data-migration tooling;
366
+ [Alembic autogeneration and async execution](docs/features/09-migrations.md) are available now.
360
367
 
361
368
  Already implemented: window functions, CTEs (including recursive), `EXPLAIN`
362
369
  query analysis, cascade operations, SQL logging, and high-performance bulk
@@ -374,4 +381,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
374
381
 
375
382
  ---
376
383
 
377
- **SQLObjects** - Modern async ORM for Python 3.12+
384
+ **SQLObjects** - Modern async ORM for Python 3.12+
@@ -48,7 +48,7 @@ from sqlobjects.session import ctx_session, ctx_sessions
48
48
  # Single database transaction
49
49
  async with ctx_session() as session:
50
50
  user = await User.objects.using(session).create(username="bob")
51
- posts = await user.posts.using(session).all()
51
+ posts = await user.load_relation("posts")
52
52
  # Auto-commit on success, rollback on exception
53
53
 
54
54
  # Multi-database transaction
@@ -88,6 +88,38 @@ 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
+ - After an SQL error in an explicit transaction, call `rollback()` or wrap the
118
+ risky statement in `async with await session.begin_nested():`; otherwise later
119
+ statements raise `TransactionError`. Readonly sessions are unaffected by a failed
120
+ query. On an implicit (auto-commit) session the transaction opened by
121
+ `begin_nested()` commits when its outermost savepoint ends.
122
+
91
123
  ### ✅ Do
92
124
 
93
125
  - **Use context managers** for explicit transaction control
@@ -171,7 +203,7 @@ async with ctx_session() as session:
171
203
  # All operations share the same connection
172
204
  users = await User.objects.using(session).all()
173
205
  for user in users:
174
- await user.posts.using(session).all()
206
+ await user.load_relation("posts") # Uses the loading session
175
207
  ```
176
208
 
177
209
  ### Read/Write Separation
@@ -347,7 +379,7 @@ async def get_user(user_id: int, session: AsyncSession = Depends(get_db_session)
347
379
  ## SQL Logging
348
380
 
349
381
  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
382
+ module. Driver cursor executions are logged at `DEBUG` level to the logger named
351
383
  **`sqlobjects.sql`**. This logger is an `ObjectLogger` (installed automatically
352
384
  on import) that rewrites each record's caller fields — `pathname`, `filename`,
353
385
  `funcName`, `lineno` — to the first user-code frame, skipping internal
@@ -381,10 +413,25 @@ handler.setFormatter(logging.Formatter("%(pathname)s:%(lineno)d - %(message)s"))
381
413
  sql_logger.addHandler(handler)
382
414
  ```
383
415
 
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`.
416
+ Logging is installed on each database engine and covers reads, writes, bulk,
417
+ raw SQL and streaming. It does not compile statements again. Disabled logging
418
+ skips timing and frame inspection; enabled logging resolves the user frame
419
+ across the async greenlet bridge.
420
+
421
+ Each record carries `sql`, driver-format `params`, `duration_ms`, `db_name`,
422
+ `dialect`, `executemany`, `rowcount`, `success`, `error_type`, and
423
+ `driver_error_type`. Parameters may
424
+ be a dictionary, tuple or a sequence of parameter sets. `hide_parameters=True`
425
+ in `init_db()` makes `params` null, including on failure; raw SQL literals are
426
+ not redacted. Errors include only exception classes, not messages: `error_type` is the
427
+ SQLAlchemy class and is stable across drivers, `driver_error_type` is the
428
+ driver's own class and is not.
429
+
430
+ Records count driver calls, not ORM methods or returned rows. Timing excludes
431
+ pool checkout, compilation, later fetching, hydration and commit. `rowcount` can
432
+ be `-1` when unknown or null on failure. Driver failures and cancellation are
433
+ logged without replacing the original exception; ordinary handler failures do
434
+ not affect the database operation.
388
435
 
389
436
  ### Public API
390
437
 
@@ -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)
@@ -285,17 +314,22 @@ posts = await Post.objects.outerjoin(
285
314
  ### Row Locking
286
315
 
287
316
  ```python
288
- # Pessimistic locking (FOR UPDATE)
289
- user = await User.objects.filter(
290
- User.id == 1
291
- ).select_for_update(nowait=True).first()
292
-
293
- # Shared locking (FOR SHARE)
294
- users = await User.objects.filter(
295
- User.department == "sales"
296
- ).select_for_share(skip_locked=True).all()
317
+ # Row locks require an explicit transaction on PostgreSQL/MySQL
318
+ async with ctx_session():
319
+ # Pessimistic locking (FOR UPDATE)
320
+ user = await User.objects.filter(
321
+ User.id == 1
322
+ ).select_for_update(nowait=True).first()
323
+
324
+ # Shared locking (FOR SHARE)
325
+ users = await User.objects.filter(
326
+ User.department == "sales"
327
+ ).select_for_share(skip_locked=True).all()
297
328
  ```
298
329
 
330
+ Outside SQLite, `select_for_update()` / `select_for_share()` must run inside an
331
+ explicit transaction; the lock is held until that transaction ends.
332
+
299
333
  ### Date/Time Extraction
300
334
 
301
335
  ```python
@@ -452,7 +486,7 @@ users = await User.objects.only(
452
486
  ).order_by("-created_at").limit(10).offset(20).all()
453
487
 
454
488
  # Subquery
455
- avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).subquery(query_type="scalar")
489
+ avg_age = User.objects.aggregate(avg_age=func.avg(User.age)).scalar_subquery()
456
490
  older_users = await User.objects.filter(User.age > avg_age).all()
457
491
 
458
492
  # Performance optimization
@@ -337,7 +337,7 @@ await User.objects.bulk_create(data, batch_size=100) # SQLite
337
337
  async with ctx_session() as session:
338
338
  # Quick database operations only
339
339
  user = await User.objects.using(session).create(username="alice")
340
- await user.posts.using(session).create(title="Post")
340
+ await Post.objects.using(session).create(title="Post", author_id=user.id)
341
341
  # Transaction commits here
342
342
 
343
343
  # Don't hold transactions during I/O
@@ -58,7 +58,7 @@ for post in posts:
58
58
  # prefetch_related (separate query) - for reverse relationships
59
59
  users = await User.objects.prefetch_related("posts").all()
60
60
  for user in users:
61
- posts = await user.posts.fetch() # No N+1 queries
61
+ posts = await user.load_relation("posts") # Prefetched list, no query
62
62
 
63
63
  # Combined loading
64
64
  posts = await Post.objects.select_related("author").prefetch_related("comments").all()
@@ -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()
@@ -140,7 +162,9 @@ users = await User.objects.prefetch_related(
140
162
  ### ❌ Don't
141
163
 
142
164
  - **Don't use select_related** for reverse relationships (use prefetch_related)
143
- - **Don't forget to fetch()** lazy-loaded relationships
165
+ - **Don't forget to load** lazy relationships with `load_relation()`; after
166
+ `select_related`/`prefetch_related` the attribute is already an entity or list and
167
+ has no `.fetch()`
144
168
  - **Don't cause N+1 queries** by not using loading strategies
145
169
  - **Don't mix loading strategies** incorrectly
146
170
 
@@ -178,7 +202,7 @@ class Book(ObjectModel):
178
202
 
179
203
  # Usage
180
204
  author = await Author.objects.prefetch_related("books").get(Author.id == 1)
181
- books = await author.books.fetch()
205
+ books = await author.load_relation("books") # Prefetched list, no extra query
182
206
  ```
183
207
 
184
208
  ### One-to-One
@@ -211,7 +235,7 @@ class Course(ObjectModel):
211
235
 
212
236
  # Usage
213
237
  student = await Student.objects.prefetch_related("courses").get(Student.id == 1)
214
- courses = await student.courses.fetch()
238
+ courses = await student.load_relation("courses") # Prefetched list, no extra query
215
239
  ```
216
240
 
217
241
  ### Self-Referential
@@ -347,11 +371,11 @@ posts = await Post.objects.select_related("author").defer(
347
371
  "author__bio" # Heavy field from related model
348
372
  ).all()
349
373
 
350
- # Filter prefetched relationships
374
+ # Filter prefetched relationships (slicing the prefetch queryset is rejected)
351
375
  users = await User.objects.prefetch_related(
352
- recent_posts=Post.objects.filter(
376
+ posts=Post.objects.filter(
353
377
  Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
354
- ).order_by('-created_at').limit(10)
378
+ ).order_by('-created_at')
355
379
  ).all()
356
380
  ```
357
381
 
@@ -394,9 +418,10 @@ users = await User.objects.prefetch_related("posts").all()
394
418
 
395
419
  **Solution**:
396
420
  ```python
397
- # Use fetch() for lazy-loaded relationships
421
+ # Use load_relation() for lazy relationships (works whether or not the
422
+ # relationship was eagerly loaded; .fetch() exists only on the lazy proxy)
398
423
  post = await Post.objects.get(Post.id == 1)
399
- author = await post.author.fetch() # Explicit load
424
+ author = await post.load_relation("author") # Explicit load
400
425
 
401
426
  # Or use select_related
402
427
  post = await Post.objects.select_related("author").get(Post.id == 1)
@@ -477,11 +502,11 @@ posts = await Post.objects.select_related("author").prefetch_related("comments",
477
502
 
478
503
  # Advanced prefetch with filtering
479
504
  users = await User.objects.prefetch_related(
480
- recent_posts=Post.objects.filter(
505
+ posts=Post.objects.filter(
481
506
  Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
482
- ).order_by('-created_at').limit(5)
507
+ ).order_by('-created_at')
483
508
  ).all()
484
509
 
485
510
  for user in users:
486
- recent_posts = await user.recent_posts.fetch()
511
+ recent_posts = await user.load_relation("posts")
487
512
  ```
@@ -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
@@ -201,7 +233,9 @@ async def before_save(self, context: SignalContext):
201
233
  self.updated_at = datetime.now(timezone.utc) # Fast
202
234
 
203
235
  async def after_save(self, context: SignalContext):
204
- asyncio.create_task(self.process_large_file()) # Background task
236
+ # after_* hooks run before the transaction commits; defer external side
237
+ # effects until the commit succeeds
238
+ await context.on_commit(self.process_large_file)
205
239
  ```
206
240
 
207
241
  ## Signal Execution Flow
@@ -291,22 +325,23 @@ class User(ObjectModel):
291
325
  ### Signal Performance
292
326
 
293
327
  ```python
294
- # Group related operations
328
+ # ORM writes that belong to the same transaction: await them sequentially.
329
+ # Hooks run inside the operation's session, which belongs to the current task;
330
+ # asyncio.create_task()/gather() would run them in other tasks and raise
331
+ # TransactionError.
295
332
  async def after_create(self, context: SignalContext):
296
- await asyncio.gather(
297
- self.send_welcome_email(),
298
- self.create_default_preferences(),
299
- self.log_user_creation()
300
- )
333
+ await self.create_default_preferences()
334
+ await self.log_user_creation()
301
335
 
302
- # Background tasks for non-critical operations
336
+ # External side effects: defer until the transaction has committed.
337
+ # after_* hooks fire before commit, so a rollback would otherwise leave
338
+ # emails sent or indexes updated for data that never persisted.
303
339
  async def after_save(self, context: SignalContext):
304
- # Critical operations (blocking)
305
340
  self.updated_at = datetime.now(timezone.utc)
306
-
307
- # Non-critical operations (background)
341
+
308
342
  if not context.is_bulk:
309
- asyncio.create_task(self.update_search_index())
343
+ await context.on_commit(self.update_search_index)
344
+ await context.on_commit(self.send_welcome_email)
310
345
  ```
311
346
 
312
347
  ### Validation Performance
@@ -66,7 +66,7 @@ for post in posts:
66
66
  # prefetch_related for reverse relationships (fast - 2 queries)
67
67
  users = await User.objects.prefetch_related("posts").all()
68
68
  for user in users:
69
- posts = await user.posts.fetch() # No N+1 queries
69
+ posts = await user.load_relation("posts") # Returns the prefetched list, no query
70
70
  ```
71
71
 
72
72
  ### Query Optimization
@@ -106,7 +106,7 @@ async with ctx_session() as session:
106
106
  # All operations share the same connection
107
107
  users = await User.objects.using(session).all()
108
108
  for user in users:
109
- await user.posts.using(session).all()
109
+ await user.load_relation("posts") # Uses the loading session
110
110
  ```
111
111
 
112
112
  ## Best Practices
@@ -297,7 +297,7 @@ print(f"Query took {duration:.3f} seconds")
297
297
  start = time.time()
298
298
  posts = await Post.objects.all()
299
299
  for post in posts[:10]:
300
- author = await post.author.fetch()
300
+ author = await post.load_relation("author")
301
301
  time_without = time.time() - start
302
302
 
303
303
  # With select_related