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.
- {sqlobjects-2.0.1/sqlobjects.egg-info → sqlobjects-2.1.1}/PKG-INFO +17 -8
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/README.md +14 -7
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/01-database-session-guide.md +54 -7
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/02-model-definition-guide.md +25 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/03-query-operations-guide.md +47 -13
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/04-crud-operations-guide.md +1 -1
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/05-relationships-guide.md +48 -23
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/06-validation-signals-guide.md +47 -12
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/07-performance-guide.md +3 -3
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/pyproject.toml +9 -5
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/__init__.py +1 -1
- sqlobjects-2.1.1/sqlobjects/_compat.py +61 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/cascade.py +22 -31
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/asgi.py +5 -3
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/manager.py +44 -30
- sqlobjects-2.1.1/sqlobjects/expressions/aggregate.py +173 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/scalar.py +5 -9
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/__init__.py +2 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/core.py +5 -4
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/proxies.py +78 -30
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/descriptors.py +4 -2
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/prefetch.py +62 -63
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/utils.py +50 -11
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/results.py +1 -1
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/metadata.py +110 -37
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/mixins.py +24 -5
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/model.py +45 -72
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/bulk.py +159 -245
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/core.py +62 -58
- sqlobjects-2.1.1/sqlobjects/objects/upsert.py +155 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/builder.py +77 -145
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/dialect.py +4 -4
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/executor.py +105 -209
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queryset.py +64 -45
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/session.py +342 -38
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/signals.py +60 -33
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/sql_logging.py +107 -11
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/naming.py +17 -1
- {sqlobjects-2.0.1 → sqlobjects-2.1.1/sqlobjects.egg-info}/PKG-INFO +17 -8
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/SOURCES.txt +1 -1
- sqlobjects-2.1.1/sqlobjects.egg-info/requires.txt +4 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/tests/test_config.py +5 -5
- sqlobjects-2.0.1/CHANGELOG.md +0 -293
- sqlobjects-2.0.1/sqlobjects/expressions/aggregate.py +0 -112
- sqlobjects-2.0.1/sqlobjects/objects/upsert.py +0 -78
- sqlobjects-2.0.1/sqlobjects.egg-info/requires.txt +0 -1
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/LICENSE +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/docs/rules/README.md +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/setup.cfg +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/_install_rules.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/contrib/fastapi.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/database/config.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/exceptions.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/base.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/cte.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/explain.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/function.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/mixins.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/subquery.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/terminal.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/expressions/window.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/functions.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/managers.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/relations/strategies.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/shortcuts.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/base.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/comparators.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/types/registry.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/fields/utils.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/internal/operations.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/objects/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/py.typed +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/queries/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/__init__.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/inspect.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/utils/pattern.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects/validators.py +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/dependency_links.txt +0 -0
- {sqlobjects-2.0.1 → sqlobjects-2.1.1}/sqlobjects.egg-info/entry_points.txt +0 -0
- {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.
|
|
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]
|
|
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
|
|
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
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
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**:
|
|
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
|
|
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
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
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**:
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
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
|
-
|
|
117
|
-
|
|
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)).
|
|
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
|
-
#
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
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)).
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
84
|
+
published_posts = await user.load_relation("posts")
|
|
83
85
|
|
|
84
|
-
# Multiple advanced prefetch configurations
|
|
85
86
|
users = await User.objects.prefetch_related(
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
376
|
+
posts=Post.objects.filter(
|
|
353
377
|
Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
|
|
354
|
-
).order_by('-created_at')
|
|
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
|
|
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
|
|
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
|
-
|
|
505
|
+
posts=Post.objects.filter(
|
|
481
506
|
Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
|
|
482
|
-
).order_by('-created_at')
|
|
507
|
+
).order_by('-created_at')
|
|
483
508
|
).all()
|
|
484
509
|
|
|
485
510
|
for user in users:
|
|
486
|
-
recent_posts = await user.
|
|
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
|
-
|
|
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
|
-
#
|
|
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
|
|
297
|
-
|
|
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
|
-
#
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
300
|
+
author = await post.load_relation("author")
|
|
301
301
|
time_without = time.time() - start
|
|
302
302
|
|
|
303
303
|
# With select_related
|