Skip to main content
Version: 2.3.0

用户指南

nonebot-plugin-orm 功能强大且复杂,使用上有一定难度。 不过,对于用户而言,只需要掌握部分功能即可。

注意

请注意区分插件的项目名(如: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
注意

以上配置之间有覆盖关系,遵循特殊优先于一般的原则,具体为 sqlalchemy_database_url > sqlalchemy_bind > sqlalchemy_echo > sqlalchemy_engine_options。 但覆盖顺序并非显而易见,出于清晰考虑,请只配置必要的选项。