5.0 KiB
| sidebar_position | description |
|---|---|
| 2 | 用户指南 |
用户指南
nonebot-plugin-orm 功能强大且复杂，使用上有一定难度。
不过，对于用户而言，只需要掌握部分功能即可。
:::caution 注意
请注意区分插件的项目名（如：nonebot-plugin-wordcloud）和模块名（如：nonebot_plugin_wordcloud）。nonebot-plugin-orm 中统一使用插件模块名。参见 插件命名规范。
:::
示例
创建新机器人
我们想要创建一个机器人，并安装 nonebot-plugin-wordcloud 插件，只需要执行以下命令：
nb init # 初始化项目文件夹
pip install nonebot-plugin-orm[sqlite] # 安装 nonebot-plugin-orm，并附带 SQLite 支持
nb plugin install nonebot-plugin-wordcloud # 安装插件
# nb orm heads # 查看有什么插件使用到了数据库（可选）
nb orm upgrade # 升级数据库
# nb orm check # 检查一下数据库模式是否与模型定义一致（可选）
nb run # 启动机器人
卸载插件
我们已经安装了 nonebot-plugin-wordcloud 插件，但是现在想要卸载它，并且删除它的数据，只需要执行以下命令：
nb plugin uninstall nonebot-plugin-wordcloud # 卸载插件
# nb orm heads # 查看有什么插件使用到了数据库。（可选）
nb orm downgrade nonebot_plugin_wordcloud@base # 降级数据库，删除数据
# nb orm check # 检查一下数据库模式是否与模型定义一致（可选）
CLI
接下来，让我们了解下示例中出现的 CLI 命令的含义：
heads
显示所有的分支头。一般一个分支对应一个插件。
nb orm heads
输出格式为 <迁移 ID> (<插件模块名>) (<头部类型>)：
46327b837dd8 (nonebot_plugin_chatrecorder) (head)
9492159f98f7 (nonebot_plugin_user) (head)
71a72119935f (nonebot_plugin_session_orm) (effective head)
ade8cdca5470 (nonebot_plugin_wordcloud) (head)
upgrade
升级数据库。每次安装新的插件或更新插件版本后，都需要执行此命令。
nb orm upgrade <插件模块名>@<迁移 ID>
其中，<插件模块名>@<迁移 ID> 是可选参数。如果不指定，则会将所有分支升级到最新版本，这也是最常见的用法：
nb orm upgrade
downgrade
降级数据库。当需要回滚插件版本或删除插件时，可以执行此命令。
nb orm downgrade <插件模块名>@<迁移 ID>
其中，<迁移 ID> 也可以是 base，即回滚到初始状态。常用于卸载插件后删除其数据：
nb orm downgrade <插件模块名>@base
check
检查数据库模式是否与模型定义一致。机器人启动前会自动运行此命令（ALEMBIC_STARTUP_CHECK=true 时），并在检查失败时阻止启动。
nb orm check
配置
sqlalchemy_database_url
默认数据库连接 URL。参见 数据库驱动和后端 和 引擎配置 — SQLAlchemy 2.0 文档。
SQLALCHEMY_DATABASE_URL=dialect+driver://username:password@host:port/database
sqlalchemy_bind
bind keys（一般为插件模块名）到数据库连接 URL、create_async_engine() 参数字典或 AsyncEngine 实例的字典。
例如，我们想要让 nonebot-plugin-wordcloud 插件使用一个 SQLite 数据库，并开启 Echo 选项 便于 debug，而其他插件使用默认的 PostgreSQL 数据库，可以这样配置：
SQLALCHEMY_BINDS='{
"": "postgresql+psycopg://scott:tiger@localhost/mydatabase",
"nonebot_plugin_wordcloud": {
"url": "sqlite+aiosqlite://",
"echo": true
}
}'
sqlalchemy_engine_options
create_async_engine() 默认参数字典。
SQLALCHEMY_ENGINE_OPTIONS='{
"pool_size": 5,
"max_overflow": 10,
"pool_timeout": 30,
"pool_recycle": 3600,
"echo": true
}'
sqlalchemy_echo
开启 Echo 选项 和 Echo Pool 选项 便于 debug。
SQLALCHEMY_ECHO=true
:::caution 注意
以上配置之间有覆盖关系，遵循特殊优先于一般的原则，具体为 sqlalchemy_database_url > sqlalchemy_bind > sqlalchemy_echo > sqlalchemy_engine_options。
但覆盖顺序并非显而易见，出于清晰考虑，请只配置必要的选项。
:::