NoneBot Plugin ORM

✨ NoneBot 数据库支持插件 ✨

安装

pip install nonebot-plugin-orm
poetry add nonebot-plugin-orm
pdm add nonebot-plugin-orm
# 无需配置、开箱即用的默认依赖
pip install nonebot-plugin-orm[default]
# 特定数据库后端的依赖
pip install nonebot-plugin-orm[mysql]
pip install nonebot-plugin-orm[postgresql]
pip install nonebot-plugin-orm[sqlite]
# 特定数据库驱动的依赖
pip install nonebot-plugin-orm[asyncmy]
pip install nonebot-plugin-orm[aiomysql]
pip install nonebot-plugin-orm[psycopg]
pip install nonebot-plugin-orm[asyncpg]
pip install nonebot-plugin-orm[aiosqlite]

使用方式

ORM

Model 依赖注入

fromnonebot.adaptersimportEventfromnonebot.paramsimportDependsfromnonebotimportrequire, on_messagefromsqlalchemy.ormimportMapped, mapped_columnrequire("nonebot_plugin_orm")
fromnonebot_plugin_ormimportModel, async_scoped_sessionmatcher=on_message()
defget_user_id(event: Event) ->str:
returnevent.get_user_id()
classUser(Model):
id: Mapped[int] =mapped_column(primary_key=True)
user_id: Mapped[str] =Depends(get_user_id)
@matcher.handle()asyncdef_(event: Event, sess: async_scoped_session, user: User|None):
ifuser:
awaitmatcher.finish(f"Hello, {user.user_id}")
sess.add(User(user_id=get_user_id(event)))
awaitsess.commit()
awaitmatcher.finish("Hello, new user!")

SQL 依赖注入

fromsqlalchemyimportselectfromnonebot.adaptersimportEventfromnonebot.paramsimportDependsfromnonebotimportrequire, on_messagefromsqlalchemy.ormimportMapped, mapped_columnrequire("nonebot_plugin_orm")
fromnonebot_plugin_ormimportModel, SQLDepends, async_scoped_sessionmatcher=on_message()
defget_session_id(event: Event) ->str:
returnevent.get_session_id()
classSession(Model):
id: Mapped[int] =mapped_column(primary_key=True)
session_id: Mapped[str]
@matcher.handle()asyncdef_(
event: Event,
sess: async_scoped_session,
session: Session|None=SQLDepends(
select(Session).where(Session.session_id==Depends(get_session_id))
),
):
ifsession:
awaitmatcher.finish(f"Hello, {session.session_id}")
sess.add(Session(session_id=get_session_id(event)))
awaitsess.commit()
awaitmatcher.finish("Hello, new user!")

CLI

依赖 NB CLI

$ nb orm
Usage: nb orm [OPTIONS] COMMAND [ARGS]...
Options:
-c, --config FILE 可选的配置文件；默认为 ALEMBIC_CONFIG 环境变量的值，或者 "alembic.ini"（如果存在）
-n, --name TEXT .ini 文件中用于 Alembic 配置的小节的名称 [default: alembic]
-x TEXT 自定义 env.py 脚本使用的其他参数，例如：-x setting1=somesetting -x
setting2=somesetting
-q, --quite 不要输出日志到标准输出
--help Show this message and exit.
Commands:
branches 显示所有的分支。
check 检查数据库是否与模型定义一致。
current 显示当前的迁移。
downgrade 回退到先前版本。
edit 使用 $EDITOR 编辑迁移脚本。
ensure_version 创建版本表。
heads 显示所有的分支头。
history 显示迁移的历史。
init 初始化脚本目录。
list_templates 列出所有可用的模板。
merge 合并多个迁移。创建一个新的迁移脚本。
revision 创建一个新迁移脚本。
show 显示迁移的信息。
stamp 将数据库标记为特定的迁移版本，不运行任何迁移。
upgrade 升级到较新版本。

配置项

sqlalchemy_database_url

默认数据库连接 URL。 参见：Engine Configuration — SQLAlchemy 2.0 Documentation

SQLALCHEMY_DATABASE_URL=sqlite+aiosqlite://

sqlalchemy_binds

bind keys 到 AsyncEngine 选项的映射。值可以是数据库连接 URL、AsyncEngine 选项字典或者 AsyncEngine 实例。

SQLALCHEMY_BINDS='{ "": "sqlite+aiosqlite://", "nonebot_plugin_user": { "url": "postgresql+asyncpg://scott:tiger@localhost/mydatabase", "echo": true }}'

sqlalchemy_echo

所有 AsyncEngine 的 echo 和 echo_pool 选项的默认值。用于快速调试连接和 SQL 生成问题。

SQLALCHEMY_ECHO=true

sqlalchemy_engine_options

所有 AsyncEngine 的默认选项字典。 参见：Engine Configuration — SQLAlchemy 2.0 Documentation

SQLALCHEMY_ENGINE_OPTIONS='{ "pool_size": 5, "max_overflow": 10, "pool_timeout": 30, "pool_recycle": 3600, "echo": true}'

sqlalchemy_session_options

AsyncSession 的选项字典。 参见：Session API — SQLAlchemy 2.0 Documentation

SQLALCHEMY_SESSION_OPTIONS='{ "autoflush": false, "autobegin": true, "expire_on_commit": true}'

alembic_config

配置文件路径或 AlembicConfig 实例。

ALEMBIC_CONFIG=alembic.ini

alembic_script_location

脚本目录路径。

ALEMBIC_SCRIPT_LOCATION=migrations

alembic_version_locations

迁移脚本目录路径或分支标签到迁移脚本目录路径的映射。

ALEMBIC_VERSION_LOCATIONS=migrations/versions
ALEMBIC_VERSION_LOCATIONS='{ "": "migrations/versions", "nonebot_plugin_user": "src/nonebot_plugin_user/versions", "nonebot_plugin_chatrecorder": "migrations/versions/nonebot_plugin_chatrecorder"}'

alembic_context

MigrationContext 的选项字典。 参见：Runtime Objects — Alembic 1.12.0 documentation

ALEMBIC_CONTEXT='{ "render_as_batch": true}'

alembic_startup_check

是否在启动时检查数据库与模型定义的一致性。

ALEMBIC_STARTUP_CHECK=true