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