Package: nonebot-plugin-datastore
NoneBot Plugin DataStore✨ NoneBot 数据存储插件 ✨安装使用 nb-clinbplugininstallnonebot-plugin-datastore使用 pippipinstallnonebot-plugin-datastore使用方式先在插件代码最前面声明依赖fromnonebotimportrequirerequire("nonebot_plugin_datastore")插件数据相关功能fromnonebot_plugin_datastoreimportget_plugin_dataplugin_data=get_plugin_data()# 获取插件缓存目录plugin_data.cache_dir# 获取插件配置目录plugin_data.config_dir# 获取插件数据目录plugin_data.data_dir# 读取配置awaitplugin_data.config.get(key)# 存储配置awaitplugin_data.config.set(key,value)数据库相关功能，详细用法见SQLAlchemyfromnonebotimporton_commandfromnonebot.paramsimportDependsfromsqlalchemy.ext.asyncio.sessionimportAsyncSessionfromsqlalchemy.ormimportMapped,mapped_columnfromnonebot_plugin_datastoreimportget_plugin_data,get_session# 定义模型Model=get_plugin_data().ModelclassExample(Model):"""示例模型"""id:Mapped[int]=mapped_column(primary_key=True)message:Mapped[str]matcher=on_command("test")# 数据库相关操作@matcher.handle()asyncdefhandle(session:AsyncSession=Depends(get_session)):example=Example(message="matcher")session.add(example)awaitsession.commit()# 因为 driver.on_startup 无法保证函数运行顺序# 如需在 NoneBot 启动时且数据库初始化后运行的函数# 请使用 post_db_init 而不是 Nonebot 的 on_startupfromnonebot_plugin_datastore.dbimportpost_db_init@post_db_initasyncdefdo_something():pass命令行支持（需安装nb-cli 1.0+）如果使用 pipx 安装的 nb-cli，则需要运行pip install nonebot-plugin-datastore[cli]安装命令行所需依赖。数据存储路径# 获取当前数据存储路径nbdatastoredir# 获取指定插件的数据存储路径nbdatastoredir--nameplugin_name数据库管理，详细用法见Alembic生成迁移文件# 生成项目内所有启用数据库插件的迁移文件（不包括 site-packages 中的插件）nbdatastoremigrate# 生成指定插件的迁移文件nbdatastoremigrate--nameplugin_name-mexample升级插件数据库# 升级所有启用数据库插件的数据库nbdatastoreupgrade# 升级指定插件的数据库nbdatastoreupgrade--nameplugin_name# 升级至指定版本nbdatastoreupgrade--nameplugin_namerevision降级插件数据库# 降级所有启用数据库插件的数据库nbdatastoredowngrade# 降级指定插件的数据库nbdatastoredowngrade--nameplugin_name# 降级至指定版本nbdatastoredowngrade--nameplugin_namerevision注意数据库迁移推荐启动机器人前运行nb datastore upgrade升级数据库至最新版本。因为当前插件自动迁移依赖NoneBot的on_startup钩子，很容易受到其他插件影响。这里推荐tiangolo/uvicorn-gunicorn镜像，通过配置prestart.sh可确保启动机器人前运行迁移脚本。具体的例子可参考CoolQBot。MySQL 数据库连接丢失当使用MySQL时，你可能会遇到2013: lost connection to mysql server during query的报错。如果遇到这种错误，可以尝试设置pool_recycle为一个小于数据库超时的值。或者设置pool_pre_ping为True。DATASTORE_ENGINE_OPTIONS={"pool_recycle": 3600}
DATASTORE_ENGINE_OPTIONS={"pool_pre_ping": true}详细介绍可查看SQLAlchemy文档的dealing-with-disconnects章节。SQLite 数据库已锁定使用SQLite数据库时，如果在写入时遇到(sqlite3.OperationalError) database is locked错误。可尝试将poolclass设置为StaticPool，保持有且仅有一个连接。不过这样设置之后，在程序运行期间，你的数据库文件都将被占用。不同插件间表的关联关系datastore 默认会给每个插件的 Base 模型提供独立的 registry，所以不同插件间的表无法建立关联关系。如果你需要与其他插件的表建立关联关系，请在需要关联的两个插件中都调用 use_global_registry 函数使用全局 registry。# 定义模型db=get_plugin_data()db.use_global_registry()classExample(db.Model):"""实例函数"""id:Mapped[int]=mapped_column(primary_key=True)message:Mapped[str]tests:Mapped["Test"]=relationship(back_populates="example")classTest(db.Model):id:Mapped[int]=mapped_column(primary_key=True)example_id:Mapped[int]=mapped_column(ForeignKey("plugin_example.id"))example:Mapped[Example]=relationship(back_populates="tests")# 注意，为了避免不同插件的模型同名而报错，请一定要加上这一行，避免如下报错# sqlalchemy.exc.InvalidRequestError: Multiple classes found for path "Test" in the registry of this declarative base. Please use a fully module-qualified path.Example.tests=relationship(Test,back_populates="example")配置项配置方式：直接在NoneBot全局配置文件中添加以下配置项即可。datastore_cache_dir类型:Path默认:macOS: ~/Library/Caches/nonebot2Unix: ~/.cache/nonebot2 (XDG default)Windows: C:\Users<username>\AppData\Local\nonebot2\Cache说明: 缓存目录datastore_config_dir类型:Path默认:macOS: same as user_data_dirUnix: ~/.config/nonebot2Win XP (roaming): C:\Documents and Settings<username>\Local Settings\Application Data\nonebot2Win 7 (roaming): C:\Users<username>\AppData\Roaming\nonebot2说明: 配置目录datastore_data_dir类型:Path默认:macOS: ~/Library/Application Support/nonebot2Unix: ~/.local/share/nonebot2 or in $XDG_DATA_HOME, if definedWin XP (not roaming): C:\Documents and Settings<username>\Application Data\nonebot2Win 7 (not roaming): C:\Users<username>\AppData\Local\nonebot2说明: 数据目录datastore_enable_database类型:bool默认:True说明: 是否启动数据库datastore_database_url类型:str默认:sqlite+aiosqlite:///data_dir/data.db说明: 数据库连接字符串，默认使用 SQLite 数据库datastore_database_echo类型:bool默认:False说明:echo和echo_pool的默认值，是否显示数据库执行的语句与其参数列表，还有连接池的相关信息datastore_engine_options类型:dict[str, Any]默认:{}说明: 向sqlalchemy.ext.asyncio.create_async_engine()传递的参数datastore_config_provider类型:str默认:~json说明: 选择存放配置的类型，当前支持 json, yaml, toml, database 四种类型，也可设置为实现ConfigProvider的自定义类型。鸣谢NoneBot Plugin LocalStore: 提供了默认的文件存储位置Flask-SQLAlchemy: 借鉴了数据库的实现思路Flask-Alembic: 借鉴了命令行的实现思路