sqlobjects 2.0.1__py3-none-any.whl → 2.1.1__py3-none-any.whl

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 (43) hide show
  1. sqlobjects/__init__.py +1 -1
  2. sqlobjects/_compat.py +61 -0
  3. sqlobjects/cascade.py +22 -31
  4. sqlobjects/contrib/asgi.py +5 -3
  5. sqlobjects/database/manager.py +44 -30
  6. sqlobjects/expressions/aggregate.py +144 -83
  7. sqlobjects/expressions/scalar.py +5 -9
  8. sqlobjects/fields/__init__.py +2 -0
  9. sqlobjects/fields/core.py +5 -4
  10. sqlobjects/fields/proxies.py +78 -30
  11. sqlobjects/fields/relations/descriptors.py +4 -2
  12. sqlobjects/fields/relations/prefetch.py +62 -63
  13. sqlobjects/fields/relations/utils.py +50 -11
  14. sqlobjects/internal/results.py +1 -1
  15. sqlobjects/metadata.py +110 -37
  16. sqlobjects/mixins.py +24 -5
  17. sqlobjects/model.py +45 -72
  18. sqlobjects/objects/bulk.py +159 -245
  19. sqlobjects/objects/core.py +62 -58
  20. sqlobjects/objects/upsert.py +85 -8
  21. sqlobjects/queries/builder.py +77 -145
  22. sqlobjects/queries/dialect.py +4 -4
  23. sqlobjects/queries/executor.py +105 -209
  24. sqlobjects/queryset.py +64 -45
  25. sqlobjects/session.py +342 -38
  26. sqlobjects/signals.py +60 -33
  27. sqlobjects/sql_logging.py +107 -11
  28. sqlobjects/utils/naming.py +17 -1
  29. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/01-database-session-guide.md +54 -7
  30. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/02-model-definition-guide.md +25 -0
  31. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/03-query-operations-guide.md +47 -13
  32. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/04-crud-operations-guide.md +1 -1
  33. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/05-relationships-guide.md +48 -23
  34. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/06-validation-signals-guide.md +47 -12
  35. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/07-performance-guide.md +3 -3
  36. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/METADATA +17 -8
  37. sqlobjects-2.1.1.dist-info/RECORD +76 -0
  38. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/WHEEL +1 -1
  39. sqlobjects-2.0.1.dist-info/RECORD +0 -75
  40. {sqlobjects-2.0.1.data → sqlobjects-2.1.1.data}/data/share/sqlobjects/rules/README.md +0 -0
  41. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/entry_points.txt +0 -0
  42. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/licenses/LICENSE +0 -0
  43. {sqlobjects-2.0.1.dist-info → sqlobjects-2.1.1.dist-info}/top_level.txt +0 -0
sqlobjects/signals.py CHANGED
@@ -121,6 +121,10 @@ class SignalContext:
121
121
  """
122
122
  return self.instance is not None
123
123
 
124
+ async def on_commit(self, callback: Callable[[], Any], *, robust: bool = False) -> None:
125
+ """Defer an effect until this signal's database transaction commits."""
126
+ await self.session.on_commit(callback, robust=robust)
127
+
124
128
 
125
129
  class SignalMixin:
126
130
  """Mixin class that provides signal handling capabilities to model classes.
@@ -225,15 +229,44 @@ def emit_signals(operation: Operation, is_bulk: bool = False):
225
229
  """
226
230
 
227
231
  def decorator(func: F) -> F:
232
+ signature = inspect.signature(func)
233
+
228
234
  @functools.wraps(func)
229
235
  async def wrapper(*args, **kwargs):
230
- # Extract self/cls and session from arguments
231
236
  self_or_cls = args[0]
232
- session = _extract_session(self_or_cls, kwargs)
237
+ arguments = signature.bind_partial(*args, **kwargs)
238
+ session = _extract_session(self_or_cls, arguments.arguments)
239
+
240
+ if is_bulk and hasattr(self_or_cls, "_executor"):
241
+ # QuerySet write signals share the same transaction as the SQL.
242
+ self_or_cls._validate_write_query()
243
+ async with session.transaction() as transaction:
244
+ arguments.arguments[next(iter(signature.parameters))] = self_or_cls.using(transaction)
245
+ return await invoke(arguments, transaction)
246
+ if (
247
+ not is_bulk
248
+ and "session" in signature.parameters
249
+ and getattr(session, "auto_commit", False)
250
+ and not getattr(session, "readonly", True)
251
+ ):
252
+ # Instance writes on an implicit session own one transaction that
253
+ # spans the hooks and the SQL, so context.on_commit() runs after
254
+ # the row is actually committed rather than before it is written.
255
+ async with session.transaction() as transaction:
256
+ arguments.arguments["session"] = transaction
257
+ return await invoke(arguments, transaction)
258
+ return await invoke(arguments, session)
259
+
260
+ async def invoke(arguments, session):
261
+ self_or_cls = arguments.args[0]
233
262
 
234
263
  # Create signal context with original operation
235
264
  context = _create_signal_context(
236
- operation=operation, session=session, self_or_cls=self_or_cls, is_bulk=is_bulk, kwargs=kwargs
265
+ operation=operation,
266
+ session=session,
267
+ self_or_cls=self_or_cls,
268
+ is_bulk=is_bulk,
269
+ kwargs=arguments.arguments,
237
270
  )
238
271
 
239
272
  # For SAVE operations, determine actual CREATE/UPDATE type
@@ -246,20 +279,10 @@ def emit_signals(operation: Operation, is_bulk: bool = False):
246
279
  # Emit pre signal
247
280
  await _emit_pre_signal(self_or_cls, context, is_bulk)
248
281
 
249
- try:
250
- # Execute original method
251
- result = await func(*args, **kwargs)
252
-
253
- # Update context with result if needed
254
- _update_context_with_result(context, result)
255
-
256
- # Emit post signal
257
- await _emit_post_signal(self_or_cls, context, is_bulk)
258
-
259
- return result
260
-
261
- except Exception:
262
- raise
282
+ result = await func(*arguments.args, **arguments.kwargs)
283
+ _update_context_with_result(context, result)
284
+ await _emit_post_signal(self_or_cls, context, is_bulk)
285
+ return result
263
286
 
264
287
  return wrapper # type: ignore
265
288
 
@@ -294,19 +317,24 @@ def _extract_session(self_or_cls, kwargs) -> Any:
294
317
  Database session for the operation
295
318
  """
296
319
  # Try to get session from kwargs first
297
- if "session" in kwargs:
320
+ if kwargs.get("session") is not None:
298
321
  return kwargs["session"]
299
322
 
323
+ if hasattr(self_or_cls, "get_session"):
324
+ return self_or_cls.get_session(readonly=False)
325
+
300
326
  # Try to get session from instance/class - support both property and method
301
327
  if hasattr(self_or_cls, "_session"):
302
328
  session_attr = self_or_cls._session # noqa
303
329
  # Handle both property and method cases
304
330
  return session_attr() if callable(session_attr) else session_attr
305
331
  elif hasattr(self_or_cls, "_get_session"):
306
- return self_or_cls._get_session() # noqa
332
+ return self_or_cls._get_session(readonly=False) # noqa
333
+ elif hasattr(self_or_cls, "_executor"):
334
+ return self_or_cls._executor._get_session("update") # noqa
307
335
 
308
336
  # Fallback to default session
309
- return get_session()
337
+ return get_session(readonly=False)
310
338
 
311
339
 
312
340
  def _create_signal_context(operation: Operation, session, self_or_cls, is_bulk: bool, kwargs: dict) -> SignalContext:
@@ -324,7 +352,9 @@ def _create_signal_context(operation: Operation, session, self_or_cls, is_bulk:
324
352
  """
325
353
  if is_bulk:
326
354
  # Bulk operation context - support ObjectsManager and QuerySet
327
- if hasattr(self_or_cls, "_model"):
355
+ if hasattr(self_or_cls, "_model_class"):
356
+ model_class = self_or_cls._model_class # noqa
357
+ elif hasattr(self_or_cls, "_model"):
328
358
  model_class = self_or_cls._model # noqa
329
359
  elif hasattr(self_or_cls, "__table__"):
330
360
  model_class = self_or_cls.__class__
@@ -421,29 +451,26 @@ async def _emit_signal(target, timing: str, context: SignalContext) -> None:
421
451
  save_signal_name = f"{timing}_{bulk_prefix}save"
422
452
  save_handler = getattr(target, save_signal_name, None)
423
453
  if save_handler and callable(save_handler):
424
- if inspect.iscoroutinefunction(save_handler):
425
- await save_handler(context)
426
- else:
427
- save_handler(context)
454
+ result = save_handler(context)
455
+ if inspect.isawaitable(result):
456
+ await result
428
457
 
429
458
  # Then emit specific CREATE/UPDATE signal
430
459
  specific_signal_name = f"{timing}_{bulk_prefix}{context.actual_operation.value}"
431
460
  specific_handler = getattr(target, specific_signal_name, None)
432
461
  if specific_handler and callable(specific_handler):
433
- if inspect.iscoroutinefunction(specific_handler):
434
- await specific_handler(context)
435
- else:
436
- specific_handler(context)
462
+ result = specific_handler(context)
463
+ if inspect.isawaitable(result):
464
+ await result
437
465
  else:
438
466
  # For non-SAVE operations, emit the specific signal
439
467
  signal_name = f"{timing}_{bulk_prefix}{context.operation.value}"
440
468
  handler = getattr(target, signal_name, None)
441
469
 
442
470
  if handler and callable(handler):
443
- if inspect.iscoroutinefunction(handler):
444
- await handler(context)
445
- else:
446
- handler(context)
471
+ result = handler(context)
472
+ if inspect.isawaitable(result):
473
+ await result
447
474
 
448
475
 
449
476
  def _update_context_with_result(context: SignalContext, result):
sqlobjects/sql_logging.py CHANGED
@@ -15,9 +15,15 @@ from __future__ import annotations
15
15
  import inspect
16
16
  import logging
17
17
  import os
18
- from collections.abc import Mapping
18
+ from collections.abc import Iterator, Mapping
19
+ from time import perf_counter
20
+ from types import FrameType
19
21
  from typing import Any
20
22
 
23
+ from greenlet import getcurrent
24
+ from sqlalchemy import event
25
+ from sqlalchemy.engine import Engine
26
+
21
27
 
22
28
  __all__ = ["get_caller_frame", "ObjectLogger"]
23
29
 
@@ -57,6 +63,23 @@ def _should_skip_frame(
57
63
  return False
58
64
 
59
65
 
66
+ def _caller_frames() -> Iterator[FrameType]:
67
+ """Walk Python frames, including parents suspended by SQLAlchemy's greenlet."""
68
+ current = getcurrent()
69
+ frame = inspect.currentframe()
70
+ try:
71
+ while True:
72
+ while frame is not None:
73
+ yield frame
74
+ frame = frame.f_back
75
+ current = current.parent
76
+ if current is None:
77
+ break
78
+ frame = current.gr_frame
79
+ finally:
80
+ del frame
81
+
82
+
60
83
  def _find_user_frame(
61
84
  extra_skip_packages: list[str] | None = None,
62
85
  ) -> inspect.FrameInfo | None:
@@ -66,10 +89,10 @@ def _find_user_frame(
66
89
  FrameInfo instead of a formatted string. Returns None if no frame found.
67
90
  """
68
91
  extra_skip_prefixes: tuple[str, ...] = tuple(extra_skip_packages) if extra_skip_packages else ()
69
- for frame_info in inspect.stack():
70
- module = frame_info.frame.f_globals.get("__name__", "")
71
- if not _should_skip_frame(frame_info.filename, module, extra_skip_prefixes):
72
- return frame_info
92
+ for frame in _caller_frames():
93
+ module = frame.f_globals.get("__name__", "")
94
+ if not _should_skip_frame(frame.f_code.co_filename, module, extra_skip_prefixes):
95
+ return inspect.FrameInfo(frame, *inspect.getframeinfo(frame, context=0))
73
96
  return None
74
97
 
75
98
 
@@ -97,12 +120,12 @@ def get_caller_frame(
97
120
  extra_skip_prefixes: tuple[str, ...] = tuple(extra_skip_packages) if extra_skip_packages else ()
98
121
  frames: list[str] = []
99
122
 
100
- for frame_info in inspect.stack():
101
- module = frame_info.frame.f_globals.get("__name__", "")
102
- if _should_skip_frame(frame_info.filename, module, extra_skip_prefixes):
123
+ for frame in _caller_frames():
124
+ module = frame.f_globals.get("__name__", "")
125
+ if _should_skip_frame(frame.f_code.co_filename, module, extra_skip_prefixes):
103
126
  continue
104
- rel_path = _relative_path(frame_info.filename)
105
- frames.append(f"{rel_path}:{frame_info.lineno} in {frame_info.function}")
127
+ rel_path = _relative_path(frame.f_code.co_filename)
128
+ frames.append(f"{rel_path}:{frame.f_lineno} in {frame.f_code.co_name}")
106
129
  if len(frames) >= max_frames:
107
130
  break
108
131
 
@@ -196,5 +219,78 @@ def _install_object_logger(name: str) -> ObjectLogger:
196
219
  return logger
197
220
 
198
221
 
199
- # Module-level instance — imported by executor.py and usable by callers
222
+ # Module-level instance shared by all database engines and usable by callers.
200
223
  _sql_logger: ObjectLogger = _install_object_logger("sqlobjects.sql")
224
+
225
+
226
+ def _install_query_logging(engine: Engine, db_name: str) -> None:
227
+ """Observe physical cursor executions without recompilation or row fetching."""
228
+ timing_key = "_sqlobjects_query_timing"
229
+
230
+ def start(context, statement, parameters, executemany):
231
+ if context is not None and _sql_logger.isEnabledFor(logging.DEBUG):
232
+ setattr(
233
+ context,
234
+ timing_key,
235
+ (perf_counter(), statement, None if engine.hide_parameters else parameters, executemany),
236
+ )
237
+
238
+ def do_execute(cursor, statement, parameters, context):
239
+ start(context, statement, parameters, False)
240
+
241
+ def do_executemany(cursor, statement, parameters, context):
242
+ start(context, statement, parameters, True)
243
+
244
+ def do_execute_no_params(cursor, statement, context):
245
+ start(context, statement, None, False)
246
+
247
+ def emit(context, cursor=None, error=None, driver_error=None):
248
+ if context is None:
249
+ return
250
+ timing = context.__dict__.pop(timing_key, None)
251
+ if timing is None or not _sql_logger.isEnabledFor(logging.DEBUG):
252
+ return
253
+ started, statement, parameters, executemany = timing
254
+ duration_ms = (perf_counter() - started) * 1000
255
+ try:
256
+ _sql_logger.debug(
257
+ statement,
258
+ extra={
259
+ "sql": statement,
260
+ "params": None if engine.hide_parameters else parameters,
261
+ "duration_ms": duration_ms,
262
+ "db_name": db_name,
263
+ "dialect": engine.dialect.name,
264
+ "executemany": executemany,
265
+ "rowcount": cursor.rowcount if cursor is not None and error is None else None,
266
+ "success": error is None,
267
+ "error_type": type(error).__name__ if error is not None else None,
268
+ "driver_error_type": type(driver_error).__name__ if driver_error is not None else None,
269
+ },
270
+ )
271
+ except Exception:
272
+ # Diagnostics must not roll back a successful write or replace a DB error.
273
+ pass
274
+
275
+ def after_execute(conn, cursor, statement, parameters, context, executemany):
276
+ emit(context, cursor)
277
+
278
+ def handle_error(exception_context):
279
+ # The driver exception class differs across drivers and SQLAlchemy versions
280
+ # (asyncpg reports UniqueViolationError on 2.1, IntegrityError on 2.0), so
281
+ # error_type uses SQLAlchemy's own class when the error was wrapped.
282
+ # Non-DBAPI errors such as CancelledError are not wrapped.
283
+ original = exception_context.original_exception
284
+ emit(
285
+ exception_context.execution_context,
286
+ error=exception_context.sqlalchemy_exception or original,
287
+ driver_error=original,
288
+ )
289
+
290
+ # Dialect events receive each batch's actual SQL/params. For insertmanyvalues,
291
+ # after_cursor_execute receives the original unbatched statement/params.
292
+ event.listen(engine, "do_execute", do_execute)
293
+ event.listen(engine, "do_executemany", do_executemany)
294
+ event.listen(engine, "do_execute_no_params", do_execute_no_params)
295
+ event.listen(engine, "after_cursor_execute", after_execute)
296
+ event.listen(engine, "handle_error", handle_error)
@@ -1,7 +1,23 @@
1
+ import hashlib
1
2
  import re
2
3
 
3
4
 
4
- __all__ = ["to_snake_case", "to_camel_case"]
5
+ __all__ = ["to_snake_case", "to_camel_case", "schema_name"]
6
+
7
+
8
+ def schema_name(name: str, *, disambiguator: str | None = None) -> str:
9
+ """Keep generated schema identifiers within PostgreSQL's 63-byte limit.
10
+
11
+ The same physical name is used on every supported backend and in migrations.
12
+ Hash the complete name so identifiers sharing a long prefix remain distinct.
13
+ """
14
+ encoded = name.encode("utf-8")
15
+ if len(encoded) <= 63 and disambiguator is None:
16
+ return name
17
+ identity = encoded if disambiguator is None else encoded + b"\0" + disambiguator.encode("utf-8")
18
+ digest = hashlib.sha256(identity).hexdigest()[:10]
19
+ prefix = encoded[:52].decode("utf-8", errors="ignore")
20
+ return f"{prefix}_{digest}"
5
21
 
6
22
 
7
23
  def to_snake_case(name: str) -> str:
@@ -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