nonebot2/website/versioned_docs/version-2.3.3/best-practice/database/user.md
noneflow[bot] eeaf823ea9 🔖 Release 2.3.3
2024-08-18 03:57:17 +00:00

5.0 KiB
Raw Blame History

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。 但覆盖顺序并非显而易见,出于清晰考虑,请只配置必要的选项。 :::