sqlobjects 2.0.0__py3-none-any.whl → 2.1.0__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 (42) hide show
  1. sqlobjects/__init__.py +1 -1
  2. sqlobjects/cascade.py +22 -31
  3. sqlobjects/contrib/asgi.py +5 -3
  4. sqlobjects/database/manager.py +44 -30
  5. sqlobjects/expressions/aggregate.py +144 -83
  6. sqlobjects/expressions/scalar.py +5 -9
  7. sqlobjects/fields/__init__.py +2 -0
  8. sqlobjects/fields/core.py +3 -2
  9. sqlobjects/fields/proxies.py +78 -30
  10. sqlobjects/fields/relations/descriptors.py +4 -2
  11. sqlobjects/fields/relations/prefetch.py +62 -63
  12. sqlobjects/fields/relations/utils.py +50 -11
  13. sqlobjects/internal/results.py +1 -1
  14. sqlobjects/metadata.py +124 -29
  15. sqlobjects/mixins.py +24 -5
  16. sqlobjects/model.py +45 -72
  17. sqlobjects/objects/bulk.py +159 -245
  18. sqlobjects/objects/core.py +62 -58
  19. sqlobjects/objects/upsert.py +85 -8
  20. sqlobjects/queries/builder.py +77 -145
  21. sqlobjects/queries/dialect.py +4 -4
  22. sqlobjects/queries/executor.py +105 -209
  23. sqlobjects/queryset.py +64 -45
  24. sqlobjects/session.py +342 -38
  25. sqlobjects/signals.py +60 -33
  26. sqlobjects/sql_logging.py +100 -11
  27. sqlobjects/utils/naming.py +17 -1
  28. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/01-database-session-guide.md +44 -5
  29. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/02-model-definition-guide.md +25 -0
  30. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/03-query-operations-guide.md +33 -4
  31. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/05-relationships-guide.md +37 -15
  32. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/06-validation-signals-guide.md +32 -0
  33. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/METADATA +9 -2
  34. sqlobjects-2.1.0.dist-info/RECORD +75 -0
  35. sqlobjects-2.0.0.dist-info/RECORD +0 -75
  36. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/04-crud-operations-guide.md +0 -0
  37. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/07-performance-guide.md +0 -0
  38. {sqlobjects-2.0.0.data → sqlobjects-2.1.0.data}/data/share/sqlobjects/rules/README.md +0 -0
  39. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/WHEEL +0 -0
  40. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/entry_points.txt +0 -0
  41. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/licenses/LICENSE +0 -0
  42. {sqlobjects-2.0.0.dist-info → sqlobjects-2.1.0.dist-info}/top_level.txt +0 -0
@@ -1,7 +1,3 @@
1
- import asyncio
2
- import gc
3
- import logging
4
- import time
5
1
  from collections.abc import AsyncGenerator
6
2
  from typing import Any, TypeVar, overload
7
3
 
@@ -14,8 +10,6 @@ from sqlalchemy import (
14
10
  update,
15
11
  )
16
12
 
17
- from ..sql_logging import _sql_logger
18
-
19
13
 
20
14
  _T = TypeVar("_T")
21
15
 
@@ -108,27 +102,56 @@ class QueryExecutor:
108
102
 
109
103
  return result
110
104
 
111
- async def iterator(self, query, chunk_size: int = 1000) -> AsyncGenerator[Any, None]:
112
- """Async iterator for processing large datasets in chunks."""
113
- offset = 0
114
- processed_chunks = 0
115
-
116
- while True:
117
- chunk_query = query.offset(offset).limit(chunk_size)
118
- chunk = await self._execute_query(chunk_query, "all")
119
-
120
- if not isinstance(chunk, list) or not chunk:
121
- break
105
+ async def iterator(
106
+ self, query, chunk_size: int = 1000, *, builder=None, model_class=None
107
+ ) -> AsyncGenerator[Any, None]:
108
+ """Stream the original query and hydrate each bounded partition."""
109
+ from ..session import AsyncSession
122
110
 
123
- for item in chunk:
124
- yield item
125
-
126
- offset += len(chunk)
127
- processed_chunks += 1
128
-
129
- # Periodic memory cleanup
130
- if processed_chunks % 10 == 0:
131
- gc.collect()
111
+ if chunk_size <= 0:
112
+ raise ValueError("chunk_size must be positive")
113
+ session = self._get_session("all")
114
+ owned = session.readonly or session.auto_commit
115
+ if owned and getattr(query, "_for_update_arg", None) is not None and session.bind.dialect.name != "sqlite":
116
+ from ..exceptions import TransactionError
117
+
118
+ raise TransactionError("select_for_update/select_for_share requires an explicit transaction")
119
+ if owned:
120
+ session = AsyncSession(session.db_name, readonly=False, auto_commit=False)
121
+ if (
122
+ builder
123
+ and (builder.prefetch_relationships or builder.prefetch_configs)
124
+ and session.bind.dialect.name == "mysql"
125
+ ):
126
+ from ..exceptions import QueryError
127
+
128
+ raise QueryError("MySQL streaming cannot prefetch using the same connection; use explicit pagination")
129
+ result = None
130
+ try:
131
+ result = await session.stream(query.execution_options(yield_per=chunk_size))
132
+ async for rows in result.partitions(chunk_size):
133
+ instances = (
134
+ [self._row_to_instance(row, model_class, db_or_session=session.db_name) for row in rows]
135
+ if model_class
136
+ else rows
137
+ )
138
+ if builder and model_class:
139
+ loader = QueryExecutor(session)
140
+ if builder.prefetch_relationships:
141
+ await loader._handle_prefetch_relationships(instances, builder.prefetch_relationships)
142
+ if builder.prefetch_configs:
143
+ await loader._handle_prefetch(instances, builder.prefetch_configs)
144
+ for instance in instances:
145
+ yield instance
146
+ finally:
147
+ try:
148
+ if result is not None:
149
+ await result.close()
150
+ finally:
151
+ if owned:
152
+ # Generator finalization may run in another task; the owned
153
+ # session is internal, so release it without the owner check.
154
+ await session._dispose()
132
155
 
133
156
  async def explain(self, query, analyze: bool = False, verbose: bool = False) -> str:
134
157
  """Execute EXPLAIN for SQLAlchemy query object.
@@ -151,6 +174,7 @@ class QueryExecutor:
151
174
  dialect = DialectHandler.create(session)
152
175
 
153
176
  # Compile query to SQL
177
+ session._validate_statement_dialect(query)
154
178
  compiled = query.compile(dialect=session.bind.dialect, compile_kwargs={"literal_binds": True})
155
179
  sql_str = str(compiled)
156
180
 
@@ -167,18 +191,16 @@ class QueryExecutor:
167
191
  @staticmethod
168
192
  def _build_query_by_type(query, query_type: str, **kwargs):
169
193
  """Build query based on execution type."""
170
- froms = query.get_final_froms()
171
- from_table = froms[0] if froms else query.table
172
-
173
194
  if query_type == "count":
174
- return (
175
- select(func.count()).select_from(from_table).where(query.whereclause)
176
- if query.whereclause is not None
177
- else select(func.count()).select_from(from_table)
178
- )
195
+ return select(func.count()).select_from(query.order_by(None).subquery())
179
196
  elif query_type == "exists":
180
197
  return select(exists(query))
181
- elif query_type == "update":
198
+ if query_type not in {"update", "delete", "values", "values_list"} or kwargs.get("prebuilt"):
199
+ return query
200
+
201
+ froms = query.get_final_froms()
202
+ from_table = froms[0] if froms else query.table
203
+ if query_type == "update":
182
204
  table = from_table
183
205
  update_query = update(table).values(**kwargs.get("values", {}))
184
206
  if query.whereclause is not None:
@@ -191,10 +213,6 @@ class QueryExecutor:
191
213
  delete_query = delete_query.where(query.whereclause)
192
214
  return delete_query
193
215
  elif query_type in ("values", "values_list"):
194
- if kwargs.get("prebuilt"):
195
- # Query was already built with the exact requested fields
196
- # (including annotations and GROUP BY) — execute as-is
197
- return query
198
216
  fields = kwargs.get("fields", [])
199
217
  if fields:
200
218
  table = from_table
@@ -206,13 +224,6 @@ class QueryExecutor:
206
224
  new_query = new_query.order_by(*query._order_by) # noqa
207
225
  return new_query
208
226
  return query
209
- elif query_type == "aggregate":
210
- aggregations = kwargs.get("aggregations", [])
211
- table = from_table
212
- agg_query = select(*aggregations).select_from(table)
213
- if query.whereclause is not None:
214
- agg_query = agg_query.where(query.whereclause)
215
- return agg_query
216
227
  else: # "all"
217
228
  return query
218
229
 
@@ -238,39 +249,25 @@ class QueryExecutor:
238
249
  else: # exists
239
250
  return False
240
251
 
241
- # Compile SQL for logging only when the logger is active (avoids overhead)
242
- _logging_active = _sql_logger.isEnabledFor(logging.DEBUG)
243
- sql_str = ""
244
- params: dict = {}
245
- t0 = 0.0
246
- if _logging_active:
247
- try:
248
- compiled = query.compile(
249
- dialect=session.bind.dialect,
250
- compile_kwargs={"literal_binds": False},
251
- )
252
- sql_str = str(compiled)
253
- params = dict(compiled.params) if compiled.params else {}
254
- except Exception:
255
- sql_str = str(query)
256
- params = {}
257
- t0 = time.perf_counter()
252
+ if getattr(query, "_for_update_arg", None) is not None and session.bind.dialect.name != "sqlite":
253
+ if session.readonly or session.auto_commit:
254
+ from ..exceptions import TransactionError
258
255
 
256
+ raise TransactionError("select_for_update/select_for_share requires an explicit transaction")
259
257
  result = await session.execute(query)
260
258
 
261
- if _logging_active:
262
- duration_ms = (time.perf_counter() - t0) * 1000
263
- _sql_logger.debug(
264
- sql_str,
265
- extra={"sql": sql_str, "params": params, "duration_ms": duration_ms},
266
- )
267
-
268
259
  if query_type == "all":
269
260
  rows = result.fetchall()
270
261
  if model_class:
271
262
  return [
272
263
  self._row_to_instance(
273
- row, model_class, deferred_fields, query_deferred, field_deferred, relationships
264
+ row,
265
+ model_class,
266
+ deferred_fields,
267
+ query_deferred,
268
+ field_deferred,
269
+ relationships,
270
+ session.db_name,
274
271
  )
275
272
  for row in rows
276
273
  ]
@@ -313,152 +310,51 @@ class QueryExecutor:
313
310
 
314
311
  @staticmethod
315
312
  def _row_to_instance(
316
- row, model_class, deferred_fields=None, query_deferred=None, field_deferred=None, relationships=None
313
+ row,
314
+ model_class,
315
+ deferred_fields=None,
316
+ query_deferred=None,
317
+ field_deferred=None,
318
+ relationships=None,
319
+ db_or_session=None,
317
320
  ):
318
- """Convert SQLAlchemy Row to model instance with deferred field support and relationships."""
319
- # Convert Row to dictionary
320
- data = dict(row._mapping) # noqa
321
-
322
- # Separate main model data from related model data and annotate fields
323
- main_data = {}
324
- related_data = {}
325
- annotate_data = {} # Store annotate fields
326
-
327
- # Get all field names from model
328
- all_fields = set(model_class._get_field_names()) # noqa
329
-
330
- for key, value in data.items():
331
- if "__" in key:
332
- # This is a related field (e.g., "author__username")
333
- relation_name, field_name = key.split("__", 1)
334
- if relation_name not in related_data:
335
- related_data[relation_name] = {}
336
- related_data[relation_name][field_name] = value
337
- elif key in all_fields:
338
- # This is a main model field
339
- main_data[key] = value
321
+ """Hydrate model state and nested joined objects without construction defaults."""
322
+ data = dict(row._mapping) if hasattr(row, "_mapping") else row
323
+ main_data, related_data, annotations = {}, {}, {}
324
+ fields = set(model_class._get_field_names())
325
+ for name, value in data.items():
326
+ if name in fields:
327
+ main_data[name] = value
328
+ elif "__" in name:
329
+ relation, field = name.split("__", 1)
330
+ related_data.setdefault(relation, {})[field] = value
340
331
  else:
341
- # This is an annotate field (not in model definition)
342
- annotate_data[key] = value
343
-
344
- # Calculate actual deferred fields based on what was loaded vs what should be deferred
345
- loaded_fields = set(main_data.keys())
346
-
347
- # Determine which fields should be deferred:
348
- # 1. Fields explicitly deferred in query (.defer() calls)
349
- # 2. Fields marked as deferred=True in field definitions (but only if not explicitly loaded)
350
- actual_deferred_fields = set()
351
-
352
- # Add query-level deferred fields (from .defer() calls)
353
- if query_deferred:
354
- actual_deferred_fields.update(query_deferred)
355
-
356
- # Add field-level deferred fields (from field definitions) only if they weren't explicitly loaded
357
- if field_deferred:
358
- # Only defer field-level deferred fields if they weren't loaded in this query
359
- for field in field_deferred:
360
- if field not in loaded_fields:
361
- actual_deferred_fields.add(field)
362
-
363
- # Remove deferred fields from main_data
364
- for field in actual_deferred_fields:
365
- main_data.pop(field, None)
366
-
367
- # Create model instance
368
- instance = model_class.from_dict(main_data, validate=False)
369
-
370
- # Set deferred field state
371
- instance._state_manager.set_deferred_fields(actual_deferred_fields) # noqa
372
- instance._state_manager.mark_from_database(True) # noqa
373
-
374
- # Attach annotate fields as dynamic attributes
375
- for key, value in annotate_data.items():
376
- setattr(instance, key, value)
377
-
378
- # Create and attach related objects
379
- if related_data and relationships:
380
- for relation_name in relationships:
381
- if relation_name in related_data:
382
- # Find the related model class
383
- related_model_class = QueryExecutor._find_related_model_class(model_class, relation_name)
384
- if related_model_class:
385
- # Create related instance
386
- related_instance = related_model_class.from_dict(related_data[relation_name], validate=False)
387
- # Attach to main instance
388
- setattr(instance, relation_name, related_instance)
389
-
332
+ annotations[name] = value
333
+ instance = model_class._from_database(main_data, db_or_session)
334
+ for name, value in annotations.items():
335
+ setattr(instance, name, value)
336
+ for name, values in related_data.items():
337
+ related_model = QueryExecutor._find_related_model_class(model_class, name)
338
+ if related_model is None:
339
+ raise ValueError(f"Cannot hydrate unknown relationship {model_class.__name__}.{name}")
340
+ pk = list(related_model.get_table().primary_key)
341
+ related = (
342
+ None
343
+ if pk and all(values.get(col.name) is None for col in pk)
344
+ else QueryExecutor._row_to_instance(values, related_model, db_or_session=db_or_session)
345
+ )
346
+ instance._update_cache(name, related)
390
347
  return instance
391
348
 
392
349
  async def _handle_prefetch(self, instances, prefetch_configs):
393
- """Handle prefetch_related with custom QuerySet configurations."""
394
- if not instances or not prefetch_configs:
395
- return instances
396
-
397
- instance_ids = [instance.id for instance in instances if hasattr(instance, "id")]
398
- if not instance_ids:
399
- return instances
400
-
401
- # Execute all prefetch queries concurrently
402
- tasks = [
403
- self._single_prefetch(field_name, queryset, instance_ids)
404
- for field_name, queryset in prefetch_configs.items()
405
- ]
406
- prefetch_results = await asyncio.gather(*tasks)
407
-
408
- # Associate results with instances
409
- for field_name, related_objects in prefetch_results:
410
- related_map = self._group_by_foreign_key(related_objects)
411
- for instance in instances:
412
- instance_id = getattr(instance, "id", None)
413
- setattr(instance, field_name, related_map.get(instance_id, []))
350
+ from ..fields.relations.prefetch import PrefetchHandler
414
351
 
352
+ if instances:
353
+ await PrefetchHandler(self._get_session("all")).handle_prefetch_relationships(
354
+ instances, prefetch_configs.keys(), prefetch_configs
355
+ )
415
356
  return instances
416
357
 
417
- @staticmethod
418
- async def _single_prefetch(field_name, queryset, instance_ids):
419
- """Execute single prefetch query."""
420
- # Assume foreign key field follows pattern: {model_name}_id
421
- # This is a simplified implementation - in practice, you'd need relationship metadata
422
- foreign_key_field = f"{queryset._model_class.__name__.lower()}_id" # noqa
423
-
424
- try:
425
- # Try to find the foreign key column
426
- if hasattr(queryset._table.c, foreign_key_field): # noqa
427
- fk_column = getattr(queryset._table.c, foreign_key_field) # noqa
428
- else:
429
- # Fallback to common patterns
430
- for col_name in queryset._table.c.keys(): # noqa
431
- if col_name.endswith("_id"):
432
- fk_column = queryset._table.c[col_name] # noqa
433
- break
434
- else:
435
- return field_name, []
436
-
437
- related_objects = await queryset.filter(fk_column.in_(instance_ids)).all()
438
- return field_name, related_objects
439
- except Exception: # noqa
440
- # If prefetch fails, return empty list
441
- return field_name, []
442
-
443
- @staticmethod
444
- def _group_by_foreign_key(related_objects):
445
- """Group related objects by foreign key."""
446
- grouped = {}
447
- for obj in related_objects:
448
- # Try to find the foreign key value
449
- fk_value = None
450
- for attr_name in dir(obj):
451
- if attr_name.endswith("_id") and not attr_name.startswith("_"):
452
- fk_value = getattr(obj, attr_name, None)
453
- break
454
-
455
- if fk_value is not None:
456
- if fk_value not in grouped:
457
- grouped[fk_value] = []
458
- grouped[fk_value].append(obj)
459
-
460
- return grouped
461
-
462
358
  async def _handle_prefetch_relationships(self, instances, prefetch_relationships):
463
359
  """Handle prefetch_related relationships using PrefetchHandler.
464
360
 
sqlobjects/queryset.py CHANGED
@@ -1,5 +1,6 @@
1
1
  import re
2
2
  from collections.abc import AsyncGenerator
3
+ from contextlib import aclosing
3
4
  from datetime import date, datetime
4
5
  from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar, Union
5
6
 
@@ -20,7 +21,7 @@ from sqlalchemy import (
20
21
  )
21
22
  from sqlalchemy.sql.selectable import Subquery
22
23
 
23
- from .exceptions import DoesNotExist, MultipleObjectsReturned
24
+ from .exceptions import DoesNotExist, MultipleObjectsReturned, QueryError
24
25
  from .expressions import (
25
26
  AggregateExpression,
26
27
  AllExpression,
@@ -449,6 +450,7 @@ class QuerySet(Generic[T]):
449
450
  # comments = await Comment.objects.select_related(Comment.post.author).all()
450
451
  """
451
452
  relationship_paths = [self._get_relationship_path(f) for f in fields]
453
+ self._validate_relationships(relationship_paths)
452
454
  new_builder = self._builder.add_relationships(*relationship_paths)
453
455
  return self._create_new_queryset(new_builder)
454
456
 
@@ -471,15 +473,14 @@ class QuerySet(Generic[T]):
471
473
 
472
474
  # Advanced prefetch with filtering and ordering
473
475
  users = await User.objects.prefetch_related(
474
- published_posts=Post.objects.filter(Post.is_published == True)
476
+ posts=Post.objects.filter(Post.is_published == True)
475
477
  .order_by('-created_at')
476
- .limit(5)
477
478
  ).all()
478
479
 
479
480
  # Mixed usage
480
481
  users = await User.objects.prefetch_related(
481
482
  User.profile, # Field expression
482
- recent_posts=Post.objects.filter(
483
+ posts=Post.objects.filter(
483
484
  Post.created_at >= datetime.now() - timedelta(days=30)
484
485
  ).order_by('-created_at')
485
486
  ).all()
@@ -487,7 +488,7 @@ class QuerySet(Generic[T]):
487
488
  relationship_paths = [self._get_relationship_path(f) for f in fields]
488
489
 
489
490
  # Validate relationships using the same logic as select_related
490
- self._validate_relationships(relationship_paths)
491
+ self._validate_relationships(relationship_paths + list(queryset_configs))
491
492
 
492
493
  new_builder = self._builder.add_prefetch_relationships(*relationship_paths)
493
494
  if queryset_configs:
@@ -503,30 +504,27 @@ class QuerySet(Generic[T]):
503
504
  Raises:
504
505
  ValueError: If any relationship path is invalid
505
506
  """
506
- for relationship_path in relationship_paths:
507
- # Basic format validation
508
- if not relationship_path or not relationship_path.replace("_", "").replace("__", "").isalnum():
509
- raise ValueError(f"Invalid relationship path format: '{relationship_path}'")
510
-
511
- # Check for obviously invalid patterns
512
- if relationship_path.startswith("__") or relationship_path.endswith("__"):
513
- raise ValueError(f"Invalid relationship path: '{relationship_path}'")
514
-
515
- # Check for obviously non-existent relationships
516
- path_parts = relationship_path.split("__")
517
- first_part = path_parts[0]
518
-
519
- # Check if it's obviously invalid (like "nonexistent_relation")
520
- if first_part.startswith("nonexistent"):
521
- available_relations = [
522
- col.name[:-3]
523
- for col in self._table.c # noqa
524
- if col.name.endswith("_id") and col.foreign_keys # noqa
525
- ]
526
- raise ValueError(
527
- f"Invalid relationship '{first_part}' in path '{relationship_path}'. "
528
- f"Available relationships: {available_relations}"
529
- )
507
+ from .fields.relations.utils import RelationshipAnalyzer
508
+
509
+ for path in relationship_paths:
510
+ model: Any = self._model_class
511
+ for name in path.split("__"):
512
+ descriptor = getattr(model, "_relationships", {}).get(name)
513
+ if descriptor is not None and descriptor.property.lazy == "dynamic":
514
+ raise ValueError(
515
+ f"Cannot eager-load dynamic relationship '{name}' in path '{path}'; query it explicitly"
516
+ )
517
+ info = RelationshipAnalyzer.analyze_relationship(model, name)
518
+ if not info:
519
+ available = {
520
+ col.name[:-3] for col in model.get_table().c if col.foreign_keys and col.name.endswith("_id")
521
+ }
522
+ available.update(getattr(model, "_relationships", {}))
523
+ raise ValueError(
524
+ f"Invalid relationship '{name}' in path '{path}' on {model.__name__}. "
525
+ f"Available relationships: {sorted(available)}"
526
+ )
527
+ model = info["related_model"]
530
528
 
531
529
  # Advanced query building
532
530
 
@@ -628,8 +626,10 @@ class QuerySet(Generic[T]):
628
626
  for field in fields:
629
627
  if isinstance(field, str):
630
628
  processed_fields.append(field)
631
- elif hasattr(field, "resolve"): # SQLAlchemy expressions
629
+ elif isinstance(field, ColumnElement) or hasattr(field, "resolve"):
632
630
  processed_fields.append(field)
631
+ elif hasattr(field, "__clause_element__"):
632
+ processed_fields.append(field.__clause_element__())
633
633
  else: # Field expressions
634
634
  processed_fields.append(self._get_field_name(field))
635
635
 
@@ -823,9 +823,9 @@ class QuerySet(Generic[T]):
823
823
  def aggregate(self, **kwargs) -> AggregateExpression:
824
824
  """Create aggregation expression that can be executed or used as subquery.
825
825
 
826
- Returns a single row aggregated over all matching rows. Incompatible
827
- with group_by() — for per-group aggregation use
828
- ``annotate(...).group_by(...).values(*group_fields, *aliases)``.
826
+ Returns a single row aggregated after filtering, grouping, distinct() and
827
+ slicing. For grouped input, reference grouping keys or annotation aliases;
828
+ use ``values(*group_fields, *aliases)`` to return each group's results.
829
829
 
830
830
  Args:
831
831
  **kwargs: Aggregation expressions with aliases
@@ -834,7 +834,7 @@ class QuerySet(Generic[T]):
834
834
  AggregateExpression that can be awaited or used in comparisons
835
835
 
836
836
  Raises:
837
- QueryError: If the queryset has GROUP BY clauses
837
+ QueryError: If the queryset has row locking or HAVING without GROUP BY
838
838
 
839
839
  Examples:
840
840
  # Direct execution
@@ -844,14 +844,10 @@ class QuerySet(Generic[T]):
844
844
  avg_age = User.objects.aggregate(avg_age=User.age.avg())
845
845
  older_users = await User.objects.filter(User.age > avg_age).all()
846
846
  """
847
- if self._builder.group_clauses:
848
- from .exceptions import QueryError
849
-
850
- raise QueryError(
851
- "aggregate() returns a single row and ignores GROUP BY. "
852
- "Use .annotate(...).group_by(...).values(*group_fields, *aggregate_aliases) "
853
- "for per-group aggregation."
854
- )
847
+ if self._builder.having_conditions and not self._builder.group_clauses:
848
+ raise QueryError("aggregate() requires group_by() when using HAVING")
849
+ if self._builder.lock_mode:
850
+ raise QueryError("aggregate() does not support row locking; lock model rows in a transaction first")
855
851
  return AggregateExpression(self._builder, kwargs, self._executor)
856
852
 
857
853
  def count(self) -> CountExpression:
@@ -994,8 +990,11 @@ class QuerySet(Generic[T]):
994
990
  async def iterator(self, chunk_size: int = 1000) -> AsyncGenerator[T, None]:
995
991
  """Async iterator for processing large datasets in chunks."""
996
992
  query = self._builder.build(self._table)
997
- async for item in self._executor.iterator(query, chunk_size):
998
- yield item
993
+ async with aclosing(
994
+ self._executor.iterator(query, chunk_size, builder=self._builder, model_class=self._model_class)
995
+ ) as stream:
996
+ async for item in stream:
997
+ yield item
999
998
 
1000
999
  async def raw(self, sql: str, params: dict | None = None) -> list[T]:
1001
1000
  """Execute raw SQL query and return model instances."""
@@ -1018,7 +1017,9 @@ class QuerySet(Generic[T]):
1018
1017
  filtered_data = {k: v for k, v in data.items() if k in table_columns}
1019
1018
 
1020
1019
  if filtered_data:
1021
- instances.append(self._model_class.from_dict(filtered_data)) # type: ignore[reportAttributeAccessIssue]
1020
+ instances.append(
1021
+ self._model_class._from_database(filtered_data, session.db_name) # type: ignore[reportAttributeAccessIssue]
1022
+ )
1022
1023
 
1023
1024
  return instances
1024
1025
 
@@ -1241,6 +1242,7 @@ class QuerySet(Generic[T]):
1241
1242
  @emit_signals(Operation.UPDATE, is_bulk=True)
1242
1243
  async def update(self, **values) -> int:
1243
1244
  """Perform bulk update on objects matching query conditions."""
1245
+ self._validate_write_query()
1244
1246
  from .cascade import CascadeExecutor
1245
1247
 
1246
1248
  executor = CascadeExecutor()
@@ -1262,9 +1264,26 @@ class QuerySet(Generic[T]):
1262
1264
  """
1263
1265
  from .cascade import CascadeExecutor
1264
1266
 
1267
+ self._validate_write_query()
1265
1268
  executor = CascadeExecutor()
1266
1269
  return await executor.execute_delete_operation(self, cascade_strategy=cascade)
1267
1270
 
1271
+ def _validate_write_query(self) -> None:
1272
+ """Reject clauses that cannot safely be translated into a direct write."""
1273
+ builder = self._builder
1274
+ if builder.limits is not None or builder.offset_value is not None:
1275
+ raise QueryError("Cannot update or delete a sliced queryset (limit/offset)")
1276
+ if (
1277
+ builder.group_clauses
1278
+ or builder.having_conditions
1279
+ or builder.is_distinct
1280
+ or builder.joins
1281
+ or builder.relationships
1282
+ ):
1283
+ raise QueryError(
1284
+ "Cannot update or delete a grouped, distinct or joined queryset; filter by primary keys instead"
1285
+ )
1286
+
1268
1287
  # ========================================
1269
1288
 
1270
1289
  def subquery(