📝 update database.md

RF-Tar-Railt · RF-Tar-Railt · commit 1c6e5ead12e9 · 2025-08-24T13:45:29.000+08:00
diff --git a/tutorial/entari/database.md b/tutorial/entari/database.md
@@ -50,24 +50,42 @@ plugins:
 - `username`: 数据库用户名 (仅在使用 MySQL/PostgreSQL 等远程数据库时需要)
 - `password`: 数据库密码 (仅在使用 MySQL/PostgreSQL 等远程数据库时需要)
 - `query`: 数据库连接参数 (仅在使用 MySQL/PostgreSQL 等远程数据库时需要)
-- `options`: SQLAlchemy 的其他选项。参见 [Engine Creation API](https://docs.sqlalchemy.org/en/21/core/engines.html#engine-creation-api)
-
-若不传入配置项，则默认使用 SQLite 数据库，并将数据库文件存储在当前目录下。
+- `options`: 数据库连接其他选项。参见 [Engine Creation API](https://docs.sqlalchemy.org/en/21/core/engines.html#engine-creation-api)
+- `session_options`: 会话选项。参见 [Session](https://docs.sqlalchemy.org/en/21/orm/session_api.html#sqlalchemy.orm.Session.__init__)
+- `binds`: 绑定多个数据库配置，用于为不同插件下的ORM模型指定不同的数据库连接。
+    ```yaml:no-line-numbers title=entari.yml
+    plugins:
+      database:
+        type: sqlite
+        name: main.db
+        binds:
+          entari_plugin_record:  # 为 entari_plugin_record 插件下的模型指定单独的数据库连接
+            type: postgresql
+            host: localhost
+            port: 5432
+            username: user
+            password: pass
+    ```
+- `create_table_at`: 指定在数据库服务的哪个生命周期阶段创建表。可选值有 `preparing`, `prepared` 和 `blocking`.
+
+- 若不传入配置项，则默认使用 SQLite 数据库，并将数据库文件存储在当前目录下。
 
 ## 定义模型
 
 `database` 插件使用 SQLAlchemy 的 ORM 功能来定义模型。你可以通过继承 `database.Base` 类来定义你的模型类。
 
+假设我们要定义一个存储天气信息的模型：
+
 ```python title=my_plugin.py
 from entari_plugin_database import Base, Mapped, mapped_column
 
 class Weather(Base):
-    __tablename__ = "weather"
-    
     location: Mapped[str] = mapped_column(primary_key=True)
     weather: Mapped[str]
 ```
 
+其中，`primary_key=True` 意味着此列 (location) 是主键，即内容是唯一的且非空的。 每一个模型必须有至少一个主键。
+
 我们可以用以下代码检查模型生成的数据库模式是否正确：
 
 ```python
@@ -77,51 +95,230 @@ print(CreateTable(Weather.__table__))
 ```
 
 ```sql
-CREATE TABLE weather (
+CREATE TABLE my_plugin_weather (
     location VARCHAR NOT NULL,
     weather VARCHAR NOT NULL,
-    CONSTRAINT pk_weather PRIMARY KEY (location)
+    CONSTRAINT pk_my_plugin_weather PRIMARY KEY (location)
 )
 ```
 
+可以注意到表名是 `my_plugin_weather` 而不是 `Weather` 或者 `weather`。 这是因为数据库插件会自动为模型生成一个表名，规则是：`<插件模块名>_<类名小写>`。
+
+你也可以通过指定 `__tablename__` 属性，或传入关键字来自定义表名：
+
+:::code-group
+
+```python title=my_plugin.py [指定 __tablename__]
+from entari_plugin_database import Base, Mapped, mapped_column
+
+class Weather(Base):
+    __tablename__ = "custom_weather"  # 自定义表名
+    location: Mapped[str] = mapped_column(primary_key=True)
+    weather: Mapped[str]
+```
+
+```python title=my_plugin.py [传入关键字]
+from entari_plugin_database import Base, Mapped, mapped_column
+
+class Weather(Base, tablename="custom_weather"):  # 自定义表名
+    location: Mapped[str] = mapped_column(primary_key=True)
+    weather: Mapped[str]
+```
+:::
+
 
 ## 使用会话
 
-`database` 插件通过 `SqlalchemyService` 提供数据库会话服务。
+在 `SQLAlchemy` 中，操作数据库需要通过会话 (Session) 来进行。 关于如何通过会话使用 SQLAlchemy 的 ORM 功能，你可以参考 [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/en/21/orm/quickstart.html)。
 
-你可以通过依赖注入的方式获取 `SqlalchemyService` 实例，并使用它来获取数据库会话。
+`database` 插件通过 `SqlalchemyService` 提供数据库会话服务。 你可以通过依赖注入的方式获取 `SqlalchemyService` 实例，并使用它来获取数据库会话。
 
 :::code-group
 
 ```python title=my_plugin.py [ORM]
-from arclet.entari import Session, command
-from entari_plugin_database import SqlalchemyService
-from sqlalchemy import select
+from arclet.entari import command
+from entari_plugin_database import SqlalchemyService, select
 
 @command.on("get_weather {location}")
-async def on_message(location: str, session: Session, db: SqlalchemyService):
+async def on_message(location: str, db: SqlalchemyService):
     async with db.get_session() as db_session:
         # 在这里使用 SQLAlchemy 的会话进行数据库操作
         result = await db_session.scalars(select(Weather).where(Weather.location == location))
         data = result.all()
-        await session.send(f"Data: {data}")
+        return f"Data: {data}"
 ```
 
-
 ```python title=my_plugin.py [SQL语句]
-from arclet.entari import Session, command
+from arclet.entari import command
 from entari_plugin_database import SqlalchemyService
 from sqlalchemy import text
 
 @command.on("get_weather {location}")
-async def on_message(location: str, session: Session, db: SqlalchemyService):
+async def on_message(location: str, db: SqlalchemyService):
     async with db.get_session() as db_session:
         # 在这里使用 SQLAlchemy 的会话进行数据库操作
         result = await db_session.execute(text("SELECT * FROM weather WHERE location=:location"), {"location": location})
         data = result.fetchall()
-        await session.send(f"Data: {data}")
+        return f"Data: {data}"
+```
+
+:::
+
+
+又或者，你也可以通过直接依赖注入 `AsyncSession` 来获取数据库会话：
+
+```python title=my_plugin.py
+from arclet.entari import command
+from entari_plugin_database import AsyncSession, select
+
+@command.on("get_weather {location}")
+async def on_message(location: str, db_session: AsyncSession):
+    # 在这里使用 SQLAlchemy 的会话进行数据库操作
+    result = await db_session.scalars(select(Weather).where(Weather.location == location))
+    data = result.all()
+    return f"Data: {data}"
+```
+
+直接依赖注入 `AsyncSession` 时，获取到的会话已经是一个上下文管理器，你不需要再使用 `async with` 来管理它。
+
+:::info
+
+`AsyncSession` 的生命周期与单个订阅者同步，即每次命令或事件触发时，每个订阅者都会创建一个新的 `AsyncSession` 实例，并在处理完成后关闭它。
+
+:::
+
+## 依赖注入
+
+在上面的示例中，我们都是通过会话获得数据的。 不过，我们也可以通过依赖注入获得数据：
+
+```python title=my_plugin.py {6-8}
+from arclet.entari import Param, command
+from entari_plugin_database import SQLDepends, select
+
+@command.command("get_weather <location:str>")
+async def on_message(
+    weather: Weather = SQLDepends(
+        select(Weather).where(Weather.location == Param("location"))
+    ),
+):
+    return f"Data: {weather}"
+```
+
+其中，SQLDepends 是一个特殊的依赖注入，它会根据类型标注和 SQL 语句提供数据，SQL 语句中也可以有子依赖。
+但不建议使用 `select` 以外的语句，因为语句可能没有返回值（`returning` 除外），而且代码不清晰。
+
+不同的类型标注也会获得不同形式的数据：
+
+```python title=my_plugin.py {1,7-9}
+from collections.abc import Sequence
+from arclet.entari import Param, command
+from entari_plugin_database import SQLDepends, select
+
+@command.command("get_weather <location:str>")
+async def on_message(
+    weathers: Sequence[Weather] = SQLDepends(
+        select(Weather).where(Weather.location == Param("location"))
+    ),
+):
+    return "Data\n" + "\n".join(f"- {weather}" for weather in weathers)
 ```
 
+:::tip
+
+`Param` 也是一类 `Depends`, 等同于 `Depends(lambda <name>: <name>)` 或 `Depends(lambda ctx: ctx[<name>])`。
+
 :::
 
-关于如何使用 SQLAlchemy 的 ORM 功能，你可以参考 [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/en/21/orm/quickstart.html)。
+类型标注将决定依赖注入的实际的数据结构，主要影响以下几个层面：
+- 迭代器（`session.execute()`）或异步迭代器（`session.stream()`）
+- 标量（`session.execute().scalars()`）或元组（`session.execute()`）
+- 单个（`session.execute().one_or_none()`）或全部（`session.execute() / session.execute().all()`）
+- 连续（`session().execute()`）或分块（`session.execute().partitions()`）
+
+具体而言：
+
+:::code-group
+
+```python:no-line-numbers [Iterator]
+async def _(rows_partitions: AsyncIterator[Sequence[tuple[Model, ...]]]):
+    # 等价于 rows_partitions = await (await session.stream(sql).partitions())
+
+    async for partition in rows_partitions:
+        for row in partition:
+            print(row[0], row[1], ...)
+
+async def _(row_partitions: Iterator[Sequence[tuple[Model, ...]]]):
+    # 等价于 row_partitions = await session.execute(sql).partitions()
+
+    for partition in rows_partitions:
+        for row in partition:
+            print(row[0], row[1], ...)
+
+async def _(model_partitions: AsyncIterator[Sequence[Model]]):
+    # 等价于 model_partitions = await (await session.stream(sql).scalars().partitions())
+
+    async for partition in model_partitions:
+        for model in partition:
+            print(model)
+
+async def _(model_partitions: Iterator[Sequence[Model]]):
+    # 等价于 model_partitions = await (await session.execute(sql).scalars().partitions())
+
+    for partition in model_partitions:
+        for model in partition:
+            print(model)
+```
+
+```python:no-line-numbers [Result/ScalarResult]
+async def _(rows: sa_async.AsyncResult[tuple[Model, ...]]):
+    # 等价于 rows = await session.stream(sql)
+
+    async for row in rows:
+        print(row[0], row[1], ...)
+
+async def _(rows: sa.Result[tuple[Model, ...]]):
+    # 等价于 rows = await session.execute(sql)
+
+    for row in rows:
+        print(row[0], row[1], ...)
+
+async def _(models: sa_async.AsyncScalarResult[Model]):
+    # 等价于 models = await session.stream(sql).scalars()
+
+    async for model in models:
+        print(model)
+
+async def _(models: sa.ScalarResult[Model]):
+    # 等价于 models = await session.execute(sql).scalars()
+
+    for model in models:
+        print(model)
+```
+
+```python:no-line-numbers [Sequence]
+async def _(rows: Sequence[tuple[Model, ...]]):
+    # 等价于 rows = await (await session.stream(sql).all())
+
+    for row in rows:
+        print(row[0], row[1], ...)
+
+async def _(models: Sequence[Model]):
+    # 等价于 models = await (await session.stream(sql).scalars().all())
+
+    for model in models:
+        print(model)
+```
+
+```python:no-line-numbers [Model/tuple[Model, ...]]
+async def _(row: tuple[Model, ...]):
+    # 等价于 row = await (await session.stream(sql).one_or_none())
+
+    if row:
+        print(row[0], row[1], ...)
+
+async def _(model: Model | None):
+    # 等价于 model = await (await session.stream(sql).scalars().one_or_none())
+    if model:
+        print(model)
+```
+:::
diff --git a/tutorial/entari/index.md b/tutorial/entari/index.md
@@ -77,12 +77,13 @@ pip install entari-cli
 
 ```shell:no-line-numbers
 $ entari config new --help
-用法: entari config new [-d] [-P NAMES]
+用法: entari config new [-d]
 
 新建一个 Entari 配置文件
 
 选项:
   -d, --dev             是否生成开发用配置文件
+  -h, --help            显示帮助信息
 ```
 
 `config new` 指令会根据当前环境选择一个合适的文件格式。
@@ -272,23 +273,30 @@ app.run()
 如同配置文件一样，插件也是 Entari 的重要组成部分。它们可以扩展 Entari 的功能，提供更多的事件响应器、命令、定时任务等。
 Entari 内置了一些插件，例如 `echo`、`inspect`、`help` 等。你可以在配置文件中启用它们，也可以通过代码加载它们。
 
-想要创建一个新的插件，你可以使用 `entari plugin new` 命令来生成一个插件模板:
+想要创建一个新的插件，你可以使用 `entari new` 命令来生成一个插件模板:
 
 ```shell:no-line-numbers
-$ entari plugin new --help
-用法: entari plugin new [-S] [-A] [-f]
+$ entari new --help
+用法: entari new [-S] [-A] [-f] [-D] [-O] [-p NUM] [-py PATH] [--pip-args PARAMS]
 
 新建一个 Entari 插件
+基础指令: entari new [NAME]
 
 选项:
   -S, --static          是否为静态插件
   -A, --application     是否为应用插件
   -f, --file            是否为单文件插件
+  -D, --disabled        是否插件初始禁用
+  -O, --optional        是否仅存储插件配置而不加载插件
+  -p, --priority NUM    插件加载优先级
+  -py, --python PATH    指定 Python 解释器路径
+  --pip-args PARAMS     传递给 pip 的额外参数
+  -h, --help            显示帮助信息
 ```
 
 其中对于 `--application` 选项，若你正在新建单个插件项目，则忽略这个选项；若你正在创建一个本地插件，则需要使用这个选项。
 
-假设我们通过 `entari plugin new my_plugin --application --file` 创建了一个名为 `my_plugin` 的插件，那么它的目录结构大致如下:
+假设我们通过 `entari new my_plugin --application --file` 创建了一个名为 `my_plugin` 的插件，那么它的目录结构大致如下:
 
 ```text:no-line-numbers
 project/
@@ -939,7 +947,7 @@ async def on_message(session: Session):
 ```
 
 ```shell:no-line-numbers
-2025-06-30 00:44:14 INFO    | [core] Entari version 0.13.1
+2025-06-30 00:44:14 INFO    | [core] Entari version 0.15.0
 2025-06-30 00:44:14 SUCCESS | [plugin] loaded plugin 'arclet.entari.builtins.auto_reload'
 2025-06-30 00:44:14 SUCCESS | [plugin] loaded plugin 'my_plugin'
 ...
