cloudoll 4.2.1__tar.gz → 4.3.0__tar.gz

{cloudoll-4.2.1 → cloudoll-4.3.0}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.3.0
+
+### ORM queries and writes
+
+- Add explicit LEFT/INNER/RIGHT JOIN kinds, query-level DISTINCT, `one_dict()`
+  for projected/aggregate rows, and non-consuming `exists()` checks.
+- Add parameterized scalar/IN and EXISTS/NOT EXISTS subqueries with snapshot
+  semantics and datasource/dialect compatibility checks.
+- Add read-only table aliases for self-joins, non-recursive CTEs, and
+  UNION/UNION ALL with branch-local and outer pagination semantics.
+- Add atomic expression-valued updates and transaction-owned `for_update()`
+  row locks, including mutually exclusive NOWAIT and SKIP LOCKED options.
+- Add single-statement `upsert()` with explicit update fields; PostgreSQL
+  supports conflict targets, while MySQL explicitly rejects that option.
+- Export `Relation` and `Subquery` types. Reject writes against aliases,
+  CTE/UNION sources and joined queries rather than silently ignoring sources.
+
+### Documentation and verification
+
+- Expand grouping/HAVING, aggregates, default datasource usage and query
+  result contracts. Normal application CRUD defaults to entity APIs without
+  unnecessary `.use(db)` or handwritten SQL.
+- Update bundled AI guidance and version-matched examples, including locking,
+  unique constraints, snapshots and unsupported advanced combinations.
+- Add MySQL 8.4/PostgreSQL 16 integration coverage for query sources, upserts,
+  concurrency, rollback and row-lock contention. Aurora remains unverified.
+
 ## 4.2.1
 
 - Correct the AI initialization regression test to compare the original bytes

{cloudoll-4.2.1 → cloudoll-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudoll
-Version: 4.2.1
+Version: 4.3.0
 Summary: Assist in quickly creating distributable microservices based on aiohttp, with a focus on simplicity and ease of use.
 Author-email: Qiu <smallerqiu@gmail.com>
 License-Expression: MIT
@@ -54,7 +54,7 @@ Dynamic: license-file
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.3.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -71,8 +71,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
+python -m pip install 'cloudoll==4.3.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -87,7 +87,7 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.2.1 and receives a random JWT secret. Controllers
+The generated project targets 4.3.0 and receives a random JWT secret. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -172,8 +172,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.2.1 → cloudoll-4.3.0}/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-Cloudoll 4.2.1 is an aiohttp-based Python library for routing, middleware,
+Cloudoll 4.3.0 is an aiohttp-based Python library for routing, middleware,
 templates, sessions, JWT, database access and application scaffolding.
 
 ## AI-assisted development
@@ -19,8 +19,8 @@ does not have `cloudoll ai --help`, consult its matching README and source first
 Python 3.9+ is required. Install only the optional drivers you use:
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
+python -m pip install 'cloudoll==4.3.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
 ```
 
 The AWS extra requires Python 3.10+. Aurora remains untested; see
@@ -35,7 +35,7 @@ python -m pip install -r requirements.txt
 cloudoll start -n myapp
 ```
 
-The generated project targets 4.2.1 and receives a random JWT secret. Controllers
+The generated project targets 4.3.0 and receives a random JWT secret. Controllers
 and authentication middleware are examples: replace demo credentials and supply
 your own authorization and upload policies before deployment.
 
@@ -120,8 +120,8 @@ python -m ruff check cloudoll tests
 python -m mypy
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
 ```
 
 Native integration tests require explicitly configured disposable databases.

{cloudoll-4.2.1 → cloudoll-4.3.0}/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动注册、中间件、模板渲染、会话管理、JWT、数据库访问及命令行脚手架，帮助快速构建 Web 应用和微服务。
 
-本文适用于 Cloudoll 4.2.1。从 3.x 升级前请阅读下方迁移说明。
+本文适用于 Cloudoll 4.3.0。从 3.x 升级前请阅读下方迁移说明。
 
 ## AI 辅助开发
 
@@ -25,10 +25,10 @@ Cloudoll 是一个基于 aiohttp 的 Python Web 开发库，提供路由自动
 
 ## 安装
 
-安装 4.2.1：
+安装 4.3.0：
 
 ```sh
-python -m pip install 'cloudoll==4.2.1'
+python -m pip install 'cloudoll==4.3.0'
 ```
 
 在当前仓库目录安装源码：
@@ -41,16 +41,16 @@ python -m pip install -e .
 
 ```sh
 # MySQL
-python -m pip install 'cloudoll[mysql]==4.2.1'
+python -m pip install 'cloudoll[mysql]==4.3.0'
 
 # PostgreSQL
-python -m pip install 'cloudoll[postgres]==4.2.1'
+python -m pip install 'cloudoll[postgres]==4.3.0'
 
 # AWS 数据库驱动
-python -m pip install 'cloudoll[aws]==4.2.1'
+python -m pip install 'cloudoll[aws]==4.3.0'
 
 # Redis / Memcached 会话或 Redis 数据库
-python -m pip install 'cloudoll[cache]==4.2.1'
+python -m pip install 'cloudoll[cache]==4.3.0'
 ```
 
 源码开发时可用 `python -m pip install -e '.[mysql,postgres,cache,dev]'` 安装。
@@ -546,8 +546,8 @@ cloudoll restart -n myapp
 python -m pip install -e '.[mysql,postgres,cache,dev]'
 python -m pytest -q -m 'not integration' -k 'not aws'
 python -m build
-python tests/check_wheel.py dist/cloudoll-4.2.1-py3-none-any.whl
-python tests/check_release.py dist/cloudoll-4.2.1-py3-none-any.whl
+python tests/check_wheel.py dist/cloudoll-4.3.0-py3-none-any.whl
+python tests/check_release.py dist/cloudoll-4.3.0-py3-none-any.whl
 ```
 
 最后一条命令用于验证构建出的 wheel，版本号变化后请调整文件名。测试使用模拟数据库连接及本机 HTTP 服务；真实数据库连接和 AWS 故障切换需要单独的集成环境。

cloudoll-4.3.0/cloudoll/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.3.0"

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/AGENTS.md

@@ -5,3 +5,7 @@ Before building or changing a Cloudoll application, read `.agents/skills/cloudol
 Official documentation is bundled with the installed library: `python -m cloudoll.cli ai list`, `ai read <topic>`, and `ai search <query>`. These commands work offline without MCP. Read `structure`, `config`, `router`, and `validation` before designing an application; read `database` before database work. Consult the installed source when resolving a signature discrepancy; report the discrepancy rather than inventing an API.
 
 Prefer the documented scaffold, auto-discovered controllers/middlewares, YAML configuration, framework-owned database lifecycle, typed request validation, and ORM for ordinary CRUD. Low-level alternatives require a task-specific reason. Never silently replace Cloudoll's architecture with patterns from another framework.
+
+Ordinary CRUD, joins, filters, aliases, counts and pagination use entity/Query APIs. With initialized application datasources and `orm.default`, omit `.use(db)` in routes and services; explicit binding is for intentional overrides or context-free scripts/tests. Before using raw SQL, verify and state the specific ORM capability gap, not merely that the query contains JOIN or COUNT.
+
+Grouping, HAVING and aggregate expressions are also supported. Consult the installed database topic for the full capability inventory; 4.3.0 additions must not be assumed available in an older installed release.

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/docs/ai.md

@@ -49,6 +49,8 @@ python -m cloudoll.cli ai search transaction
 .agents/skills/cloudoll/SKILL.md，再通过 cloudoll ai read 查阅相关文档。
 新项目遵循自动发现的 controllers/middlewares、YAML 配置、框架管理的
 数据库生命周期、类型化参数校验和 ORM。若需要偏离默认方案，先说明理由。
+普通 CRUD、联表、筛选、计数和分页用实体 API；配置 orm.default 后，
+应用代码默认省略 .use(db)。原始 SQL 须先确认并说明当前 ORM 的具体能力缺口。
 完成后说明查阅的主题、测试结果和未验证的部分。
 ```
 

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/docs/changelog.md

@@ -6,10 +6,27 @@ icon: logs
 
 # 更新日志
 
-按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.2.1 文档为准，历史功能不代表当前仍保留相同 API。
+按版本倒序记录 Cloudoll 的主要变化。当前使用方法请以本站 4.3.0 文档为准，历史功能不代表当前仍保留相同 API。
 
 历史版本日期为对应源码提交日期。各版本源码可通过表格中的链接查看。
 
+## 4.3.0
+
+### ORM 查询与写入
+
+- JOIN 新增显式 LEFT/INNER/RIGHT 类型，默认保持 LEFT；增加查询级 `distinct()`、保留聚合与别名列的 `one_dict()`、不消费查询的 `exists()`。
+- 新增参数化 IN、标量、EXISTS/NOT EXISTS 子查询，创建时快照 SQL 与参数，并校验数据源和方言。
+- 新增 `Model.alias()` 表别名和自连接、非递归 CTE、UNION/UNION ALL；区分分支分页与合并结果分页，保留正确计数语义。
+- 新增表达式原子更新和 `for_update()` 行锁，支持 NOWAIT、SKIP LOCKED；事务由调用方管理，不自动重试。
+- 新增单条原子 `upsert()`，显式指定更新列；PostgreSQL 支持冲突目标，MySQL 明确拒绝不能实现的冲突目标选项。
+- 导出 `Relation`、`Subquery` 类型；明确拒绝别名、CTE、UNION 和 JOIN 查询的直接写入，避免静默忽略查询源。
+
+### 文档与验证
+
+- 补齐 GROUP BY、HAVING、聚合、返回类型和默认数据源示例；普通应用 CRUD 优先实体 API，不必重复 `.use(db)`。
+- 同步 AI 指引与随包文档，说明行锁、唯一约束、版本适用范围和高级查询限制。
+- 增加 MySQL 8.4 / PostgreSQL 16 真实数据库测试，覆盖并发 upsert、回滚、锁竞争、CTE 和 UNION。Aurora 仍未经过真实环境验证。
+
 ## 4.2.1
 
 - 修正 AI 初始化测试对 Windows CRLF 换行的错误假设，继续验证原有内容保留和重复初始化不变。

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/docs/database.md

@@ -6,12 +6,27 @@ icon: database
 
 # 数据库与 ORM
 
-本页介绍 Cloudoll 4.1.0 的原生 MySQL/PostgreSQL 接口，包括保存点、流式查询与 SQL 日志。从 3.x 升级请先阅读[升级说明](/migration)。
+本页介绍 Cloudoll 4.3.0 的原生 MySQL/PostgreSQL 接口，包括保存点、流式查询与 SQL 日志。从 3.x 升级请先阅读[升级说明](/migration)。
+
+## 应用代码默认使用实体
+
+配置好 `database` 和 `orm.default`、数据库由框架初始化后，在路由及其调用的业务服务中直接写
+`User.select()`、`User.where(...).update(...)`，**默认省略 `.use(db)`**。
+服务拆分为独立类或函数，不会自动丢失当前应用上下文；不必仅为普通 ORM 查询传递 db 参数。
+
+筛选、排序、分页、别名、计数和联表都是 ORM 已有能力，不是改写原始 SQL 的理由：
+`select`、`where`、`join`、`order_by`、`limit`、`offset`、字段 `like` / `As` / `count`、
+查询 `count`、`one`、`one_model`、`all`，以及 `insert`、`update`、`delete`。
+Python API 的准确拼写是 `order_by` 和大写 `As`，不是 `orderby` / `as`。
+
+只有确实需要覆盖引擎时才用 `.use(engine)`；独立脚本/单元测试没有应用上下文时，
+先建立 `datasource_context` 或显式绑定。离线编译 SQL 使用 `.use(None).… .test()`。
+固定的第二数据源优先用模型 `__datasource__`，不是给每条查询重复传连接。
 
 ## 安装与连接
 
 ```sh
-python -m pip install 'cloudoll[mysql,postgres]==4.1.0'
+python -m pip install 'cloudoll[mysql,postgres]==4.3.0'
 ```
 
 Web 应用在 [database 配置](/config)中声明连接，由框架建立、关闭，通过 `request.app.db.别名` 获取。不要每个请求创建一个池，也不要在请求结束时关闭共享池。
@@ -122,16 +137,16 @@ with datasource_context({"blog": engine}, default="blog"):
 
 ## 查询与返回值
 
-以下片段均放在异步函数内，db 是已经建立的连接池，User 为上面的模型：
+以下片段在已初始化默认数据源的应用异步函数中执行，User 为上面的模型；无需传入 db：
 
 ```python
-user = await User.use(db).where(User.id == 1).one_model()
+user = await User.where(User.id == 1).one_model()
 if user is not None:
     print(user.name.value)
     print(user.to_dict(exclude_unset=True))
 
 rows = await (
-    User.use(db)
+    User
     .select(User.id, User.name)
     .where((User.id > 0) & (User.active == True))
     .order_by(User.id.desc())
@@ -157,7 +172,7 @@ use(db) 返回独立、可变的 Query，不改变模型类的全局数据库绑
 执行 one/all/写入操作会消费并重置查询条件。count() 不清空状态，忽略分页和排序，但保留 DISTINCT 投影语义。可这样分页：
 
 ```python
-query = User.use(db).where(User.active == True)
+query = User.where(User.active == True)
 total = await query.count()
 rows = await query.clone().order_by(User.id.asc()).limit(20).all()
 sql, params = query.test()
@@ -172,31 +187,242 @@ class Profile(Model):
     user_id = models.IntegerField()
     nickname = models.VarCharField(max_length=100)
 
-rows = await (
-    User.use(db)
+query = (
+    User
     .join(Profile, User.id == Profile.user_id)
     .select(User.id, User.name, Profile.nickname.As("nickname"))
-    .all()
+    .where(User.name.like("%Alice%"))
 )
+total = await query.count()
+rows = await query.clone().order_by(User.id.asc()).limit(20).offset(0).all()
 
 groups = await (
-    User.use(db)
+    User
     .select(User.active, User.id.count().As("total"))
     .group_by(User.active)
     .all()
 )
 ```
 
-当前 join 生成 LEFT JOIN；同名列应显式取别名。聚合查询不要同时选择未分组、未聚合的列。此处 Profile 示例也需要事先建表。
+join 默认生成 LEFT JOIN；4.3.0 可通过 kind 选择联表类型。同名列应显式取别名。聚合查询不要同时选择未分组、未聚合的列。此处 Profile 示例也需要事先建表。
+
+这里的 total 是匹配的联表行数；一对多关系可能使一个 User 出现多行，不能将它自动当成去重用户数。
+查询 `count()` 统计结果行，字段 `User.id.count().As("total")` 用于聚合投影，两者用途不同。
+
+### GROUP BY、HAVING 与已有表达式
+
+`where` 在分组前过滤行，`having` 在分组后过滤聚合结果。多次调用 where/having 会用 AND 累加。
+以下接口在 4.2.1 已可用：
+
+```python
+query = (
+    User.select(User.active, User.id.count().As("total"))
+    .where(User.email.not_null())
+    .group_by(User.active)
+    .having(User.id.count() >= 2)
+    .order_by(User.active.asc())
+)
+group_count = await query.count()  # 满足 HAVING 的分组数量，不是原始用户数
+groups = await query.clone().limit(20).offset(0).all()
+```
+
+字段还支持 `sum/avg/min/max`、`distinct`、`count_when/sum_when` 等条件聚合，
+以及 `In([...])`、`not_in([...])`、`between(a, b)`、`not_between(a, b)`、
+`is_null()`、`not_null()`、`like()`、`not_like()`。
+`count_when(condition)` 默认不匹配分支为 NULL；显式传 0 给不匹配分支仍会被 COUNT 计数。
+这些不是使用原始 SQL 的理由。字符串 SQL 条件/排序只接受可信开发者代码，不能拼接用户输入。
+
+## 4.3.0 新增查询能力
+
+本节接口从 **4.3.0** 开始提供，4.2.1 及更早版本不支持。
+以下示例沿用 User、Profile，并在已初始化的应用上下文中执行；使用前核对项目依赖版本。
+
+### 联表类型、去重与单行结果
+
+```python
+query = (
+    User.join(Profile, User.id == Profile.user_id, kind="inner")
+    .select(User.id, User.name).distinct()
+)
+total = await query.count()
+rows = await query.clone().order_by(User.id.asc()).limit(20).offset(0).all()
+summary = await User.select(User.id.count().As("total")).one_dict()
+present = await User.where(User.email == "alice@example.test").exists()
+```
+
+`join(..., kind="left" | "inner" | "right")` 默认仍是 LEFT JOIN，保持兼容。
+`distinct()` 对整行投影去重；字段 `User.id.distinct().count()` 生成 COUNT(DISTINCT ...)。
+`one_dict()` 返回字典或 None，不把别名/聚合列装进实体；原有 one/one_model 返回规则不变。
+`exists()` 返回布尔值，保留筛选、分组和 offset，最多读取一行且不消费原查询；它不保证并发唯一性。
+`count()` 忽略分页、排序和行锁，保留去重、分组与 HAVING。
+
+### 参数化子查询
+
+```python
+ids = Profile.select(Profile.user_id).where(Profile.nickname.like("%Alice%")).subquery()
+users = await User.where(User.id.In(ids)).all()
+related = Profile.where(Profile.user_id == User.id)
+users_with_profile = await User.where_exists(related).all()
+users_without_profile = await User.where_exists(related, negated=True).all()
+predicate = related.exists_expr()  # 表达式，不执行查询
+rows = await User.where((User.active == True) & predicate).all()
+summary = await User.select(
+    Profile.select(Profile.id.count()).subquery().As("profile_count")
+).one_dict()
+```
+
+`subquery()` / `exists_expr()` 在创建时快照 SQL 和绑定参数，后续修改原查询不影响快照。
+标量/IN 子查询须显式投影一列；标量查询返回多行时由数据库报错。
+不接受带锁子查询，不能混用不同方言或显式绑定的不同引擎。
+未绑定的离线查询并不选择数据库，执行始终使用外层数据源。
+同表自关联请使用下面的表别名，不能把同一个模型引用直接当作两张不同的表。
+
+### 表别名与自连接
+
+`Model.alias(name)` 返回只读 `Relation[Model]`，不改模型的表名或字段，也不会立即连接数据库。
+通过 `.c.字段名` 引用别名字段，`.query()` 创建使用默认/模型数据源的独立查询。
+独立脚本可显式 `.use(engine)`；`.use(None)` 只编译 SQL。
+
+```python
+class Employee(Model):
+    __table__ = "employees"
+    id = models.IntegerField(primary_key=True)
+    manager_id = models.IntegerField()
+    name = models.VarCharField(max_length=100)
+
+# employees 表须事先创建。
+employee = Employee.alias("employee")
+manager = Employee.alias("manager")
+rows = await (
+    employee.query()
+    .join(manager, employee.c.manager_id == manager.c.id)
+    .select(employee.c.id, employee.c.name, manager.c.name.As("manager_name"))
+    .order_by(employee.c.id.asc())
+    .all()
+)
+```
+
+`Employee.from_(employee)` 也可指定查询源；后续引用字段应使用该源的 `.c`。
+字段与命名空间属性冲突时用 `employee.c["names"]` / `employee.c["table"]`。
+标识符会引用转义，但动态列选择仍应由应用白名单控制。不同表引用须使用不同名称。
+以 Relation 为源时，`one()` / `one_dict()` 返回映射，`one_model()` 明确拒绝，避免将投影别名误装成实体。
+别名、CTE、UNION 和 JOIN 查询不支持直接写入；请通过原模型和明确的 where 条件操作。
+
+### CTE（公共表表达式）
+
+`.cte(name)` 将当前 SELECT 快照成非递归 CTE。可查询它，也可将它作为 JOIN 的一侧：
+
+```python
+totals = (
+    Profile.select(Profile.user_id, Profile.id.count().As("total"))
+    .group_by(Profile.user_id)
+    .having(Profile.id.count() >= 2)
+    .cte("profile_totals")
+)
+rows = await (
+    User.join(totals, User.id == totals.c.user_id, kind="inner")
+    .select(User.id, User.name, totals.c.total)
+    .all()
+)
+count = await totals.query().count()
+rows = await totals.query().order_by(totals.c.total.desc()).limit(20).all()
+```
+
+CTE 定义自动放在 WITH 中，参数按 SQL 出现顺序绑定。投影列须有唯一名称，
+聚合/运算列须 `.As("名称")`；JOIN 后的 `*` 不能用于创建 CTE，需显式选择列。
+修改原查询不会改变已创建的 CTE。支持基于已有 CTE 再创建新的 CTE，但当前不支持递归 CTE、
+数据修改 CTE 或 materialized 提示。一个 SELECT 中不允许重复 CTE 名称。
+CTE/UNION 查询源不支持 `for_update()`，也不能跨已绑定数据源或方言组合。
+
+### UNION 与 UNION ALL
+
+```python
+active = User.select(User.id, User.name).where(User.active == True)
+named = User.select(User.id, User.name).where(User.name.like("A%"))
+combined = active.union(named)  # 完整投影行去重
+total = await combined.count()
+rows = await (
+    combined.clone().order_by(combined.c.id.asc()).limit(20).offset(0).all()
+)
+all_rows = await active.union_all(named).all()  # 保留重复行
+```
+
+UNION 不消费或修改两侧查询，创建时快照；两侧投影列数须一致，并使用有名称的列。
+结果列名取左侧，数据类型是否兼容由数据库判断。聚合列请取别名，并通过 `combined.c.别名` 引用结果。
+两侧原有排序/分页保留在各自分支；UNION 之后的 where/order_by/limit/offset 作用于合并结果。
+`count()` 去掉合并结果的外层分页，保留分支分页和 UNION 的去重语义。
+除非明确排序，否则结果顺序不作保证。MySQL 的 CTE / 本文组合查询要求 MySQL 8 系列；实测版本见本节末尾。
+
+### Upsert（冲突时更新）
+
+```python
+changed = await User.upsert(
+    {"id": 1, "name": "Alice", "email": "alice@example.test"},
+    update_fields=["name", "email"],
+)
+
+# 仅 PostgreSQL：实际数据库须已为 email 建立对应唯一约束/唯一索引。
+changed = await User.upsert(
+    {"name": "Alice", "email": "alice@example.test"},
+    conflict_fields=["email"],
+    update_fields=["name"],
+)
+```
+
+`upsert(values, *, update_fields, conflict_fields=None)` 使用数据库单条原子 INSERT/冲突更新，
+不先 SELECT 再决定写入。`values` 是非空字典，插入时应用 ORM 默认值；更新只覆盖显式列出的
+`update_fields`，不会把未列出的字段（包括默认值或自动时间字段）顺便覆盖。
+更新列必须存在于应用默认值后的插入数据中；不允许更新主键，不接受 SQL 表达式值。
+
+PostgreSQL 使用 ON CONFLICT，默认冲突目标为模型主键，也可指定 `conflict_fields`；
+这些列必须包含在插入数据中、对应数据库的唯一约束，且不能同时列为更新列。
+MySQL 使用 ON DUPLICATE KEY UPDATE，**任意主键/唯一键冲突都可能触发更新**，
+不能选定某个冲突目标，所以传 `conflict_fields` 会明确报错，不会静默忽略。
+ORM 不自动创建唯一约束。租户隔离需正确设计唯一键；upsert 不替代授权检查。
+
+仅支持新建、无查询修饰的 Query；`where(...).upsert(...)` 会报错，不能把 where 误当成冲突更新的权限条件。
+返回布尔写入结果，不返回 ID、不区分插入/更新，也不自动刷新已有实体。
+MySQL 对值完全未变化的写入可能返回 False，不能将 False 等同于记录不存在。
+可在调用方事务内使用，异常按普通写入传播；不会自动重试。当前未提供批量 upsert 或冲突忽略模式。
+
+### 原子表达式更新与行锁
+
+```python
+class Inventory(Model):
+    __table__ = "inventory"
+    id = models.IntegerField(primary_key=True)
+    stock = models.IntegerField()
+
+# 表需提前建好；不要先读库存到 Python 再减。
+changed = await Inventory.where(
+    (Inventory.id == 1) & (Inventory.stock >= 2)
+).update(stock=Inventory.stock - 2)
+
+async with Inventory.transaction():
+    item = await Inventory.where(Inventory.id == 1).for_update().one_model()
+    if item is not None and item.stock.value >= 2:
+        await Inventory.where(Inventory.id == 1).update(stock=Inventory.stock - 2)
+```
+
+显式 `update(field=表达式)` 支持同表字段运算，常量参数绑定。where 中仍须保留权限、库存等条件。
+返回布尔写入结果，不新增影响行数契约；没有匹配行不会当成成功扣减。
+更新不自动刷新已加载实体，需重新查询；不允许将表达式赋给实体字段后用无参 update() 假装得到真实结果。
+不要依赖多字段 SET 的求值顺序，MySQL 与 PostgreSQL 对相互引用赋值的语义可能不同。
+
+`for_update(nowait=True)` 遇到锁竞争立即报错；
+`for_update(skip_locked=True)` 跳过已锁行，适合任务领取，不适合完整性报表。两选项互斥。
+调用方必须显式管理事务；不会自动开启事务或重试。锁查询不能使用只读 stream()。
+聚合、DISTINCT、外联表的锁定限制由数据库决定，示例只锁普通实体行。
+新增能力在原生 MySQL 8.4 / PostgreSQL 16 验证，不将该结果等同于 Aurora 验证。
 
 ## 写入与字段状态
 
 ```python
-ok, inserted_id = await User.use(db).insert(name="Alice", email=None)
-updated = await User.use(db).where(User.id == 1).update(name="Bob")
-deleted = await User.use(db).where(User.id == 2).delete()
+ok, inserted_id = await User.insert(name="Alice", email=None)
+updated = await User.where(User.id == 1).update(name="Bob")
+deleted = await User.where(User.id == 2).delete()
 
-batch_result = await User.use(db).insert_batch([
+batch_result = await User.insert_batch([
     {"name": "Carol", "email": None},
     {"name": "David", "email": None},
 ])
@@ -207,7 +433,7 @@ insert 返回 `(bool, id 或 None)`，不是直接返回 id，且不会自动回
 更新和删除必须提供 where 或可识别的主键，避免无意全表写入。查询失败直接抛异常，不会伪装成没有结果。
 
 ```python
-user = await User.use(db).select(User.id, User.name).where(User.id == 1).one_model()
+user = await User.select(User.id, User.name).where(User.id == 1).one_model()
 if user is not None:
     user.name = "Updated"
     print(user.dirty_fields)
@@ -232,15 +458,15 @@ print(draft.to_dict(exclude_unset=True))
 ## 事务与保存点
 
 ```python
-async with db.transaction():
-    await User.use(db).where(User.id == 1).update(name="Alice")
+async with User.transaction():
+    await User.where(User.id == 1).update(name="Alice")
     try:
-        async with db.savepoint():
-            await User.use(db).where(User.id == 2).update(name="Temporary")
+        async with User.transaction():  # 同一数据源的嵌套事务使用保存点
+            await User.where(User.id == 2).update(name="Temporary")
             raise ValueError("撤销内层操作")
     except ValueError:
         pass
-    await User.use(db).where(User.id == 3).update(name="Carol")
+    await User.where(User.id == 3).update(name="Carol")
 ```
 
 正常退出提交，异常退出回滚。savepoint() 要求已有事务；嵌套 transaction() 自动使用保存点。异常要在保存点块外捕获，让上下文先执行回滚。
@@ -252,7 +478,7 @@ async with db.transaction():
 ## 流式查询
 
 ```python
-query = User.use(db).order_by(User.id.asc())
+query = User.order_by(User.id.asc())
 async with query.stream(batch_size=500) as rows:
     async for row in rows:
         print(row["id"])  # 替换为逐行消费，不要把所有行收集到列表
@@ -266,6 +492,10 @@ batch_size 为正整数，query_timeout 限制每次打开/批量读取，不是
 
 ## 原始 SQL
 
+这是低层接口，不是业务 CRUD 的默认写法。先核对 ORM 是否能表达需要的查询语义；仅在版本化 DDL、数据库专有功能或当前 ORM 确实缺少能力时使用，并在调用处说明具体缺口。普通 JOIN、LIKE、COUNT、分页或“沿用现有 SQL”本身不构成缺口。改写时须保留 JOIN 类型、计数口径、权限条件及事务锁语义，不能机械替换。
+
+以下例子只演示低层接口参数绑定；其中的普通查询/更新在应用中应使用上文实体 API。db 是已初始化的引擎。
+
 ```python
 row = await db.one("SELECT id, name FROM users WHERE id = ?", [1])
 rows = await db.all("SELECT id, name FROM users WHERE id > ?", [0])
@@ -319,7 +549,7 @@ cloudoll gen -db postgres -c table -t users -p generated_models.py -env local
 from typing import Optional
 from cloudoll.orm import Query
 
-query: Query[User] = User.use(db).where(User.id == 1)
+query: Query[User] = User.where(User.id == 1)
 user: Optional[User] = await query.one_model()
 if user is not None:
     value = user.id.value

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/docs/start.md

@@ -9,7 +9,7 @@ path: /
 
 Cloudoll 是基于 aiohttp 的异步 Python Web 库，提供路由、模板、Session、ORM 和 CLI。
 
-> 本文档按 Cloudoll 4.2.1 源码更新，实际发布状态以 PyPI 为准。从 3.x 升级前，请先阅读[升级说明](/migration)，确认配置和 API 的兼容性变化。
+> 本文档按 Cloudoll 4.3.0 源码更新，实际发布状态以 PyPI 为准。从 3.x 升级前，请先阅读[升级说明](/migration)，确认配置和 API 的兼容性变化。
 
 ## 环境与安装
 
@@ -18,8 +18,8 @@ Cloudoll 是基于 aiohttp 的异步 Python Web 库，提供路由、模板、Se
 ```sh
 python3 -m venv .venv
 source .venv/bin/activate
-python -m pip install 'cloudoll==4.2.1'
-python -m pip install 'cloudoll[mysql,postgres,cache]==4.2.1'
+python -m pip install 'cloudoll==4.3.0'
+python -m pip install 'cloudoll[mysql,postgres,cache]==4.3.0'
 ```
 
 Windows PowerShell 激活命令为 `.venv\Scripts\Activate.ps1`。只使用 Web 功能时不需要安装数据库 extras。

{cloudoll-4.2.1 → cloudoll-4.3.0}/cloudoll/ai/manifest.json

@@ -1,10 +1,10 @@
 {
-  "version": "4.2.1",
+  "version": "4.3.0",
   "documents": {
     "ai": {
       "source": "src/views/ai.md",
       "url": "https://cloudoll.chuchur.com/ai",
-      "sha256": "752878a272bc9004b8fe83fc1ba2f26300d016a9dac1ab9565bc3c5938a304d7"
+      "sha256": "bb76e472ca409ef182bb8502efe392f17e6436292302631e88c75ecca2498e77"
     },
     "app-start": {
       "source": "src/views/app-start.md",
@@ -14,7 +14,7 @@
     "changelog": {
       "source": "src/views/changelog.md",
       "url": "https://cloudoll.chuchur.com/changelog",
-      "sha256": "c55d20ec3a246d1337a53962aa8602fba717f22fe7dd02c14df67b791366f3fc"
+      "sha256": "8231f060f194c398a03d9489e1d4490509c579e72eee5e2c38bfecf4066e3205"
     },
     "config": {
       "source": "src/views/config.md",
@@ -29,7 +29,7 @@
     "database": {
       "source": "src/views/database.md",
       "url": "https://cloudoll.chuchur.com/database",
-      "sha256": "de2000f356f27b3cfe89eccb00eb28c6d151871c2071bb8c742240aa35af2076"
+      "sha256": "02bb709d17ce16bf3374e5c8999b24e6485273ecd81670ce8143da4bd17359c3"
     },
     "deployment": {
       "source": "src/views/deployment.md",
@@ -84,7 +84,7 @@
     "start": {
       "source": "src/views/start.md",
       "url": "https://cloudoll.chuchur.com/",
-      "sha256": "162438f32bd4eec4efec6151c0eea52f5741aa02decf5bbcb06965695eae9fa1"
+      "sha256": "d3e3cf149ce952230b7b3057dce3aaa97405ebc21b489f7c0e2b80ee0dc4d89b"
     },
     "structure": {
       "source": "src/views/structure.md",