安装
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 依赖注入
from nonebot.adapters import Event
from nonebot.params import Depends
from nonebot import require, on_message
from sqlalchemy.orm import Mapped, mapped_column
require("nonebot_plugin_orm")
from nonebot_plugin_orm import Model, async_scoped_session
matcher = on_message()
def get_user_id(event: Event) -> str:
return event.get_user_id()
class User(Model):
id: Mapped[int] = mapped_column(primary_key=True)
user_id: Mapped[str] = Depends(get_user_id)
@matcher.handle()
async def _(event: Event, sess: async_scoped_session, user: User | None):
if user:
await matcher.finish(f"Hello, {user.user_id}")
sess.add(User(user_id=get_user_id(event)))
await sess.commit()
await matcher.finish("Hello, new user!")
SQL 依赖注入
from sqlalchemy import select
from nonebot.adapters import Event
from nonebot.params import Depends
from nonebot import require, on_message
from sqlalchemy.orm import Mapped, mapped_column
require("nonebot_plugin_orm")
from nonebot_plugin_orm import Model, SQLDepends, async_scoped_session
matcher = on_message()
def get_session_id(event: Event) -> str:
return event.get_session_id()
class Session(Model):
id: Mapped[int] = mapped_column(primary_key=True)
session_id: Mapped[str]
@matcher.handle()
async def _(
event: Event,
sess: async_scoped_session,
session: Session
| None = SQLDepends(
select(Session).where(Session.session_id == Depends(get_session_id))
),
):
if session:
await matcher.finish(f"Hello, {session.session_id}")
sess.add(Session(session_id=get_session_id(event)))
await sess.commit()
await matcher.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
Metadata
Release files for nonebot-plugin-orm 0.8.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nonebot_plugin_orm-0.8.4.tar.gz | 26.3 kB | With provenance | Details for nonebot_plugin_orm-0.8.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nonebot_plugin_orm-0.8.4-py3-none-any.whl | Python 3 | none | any | Details for nonebot_plugin_orm-0.8.4-py3-none-any.whl |
Total release size: 58.1 kB
Release files / nonebot_plugin_orm-0.8.4.tar.gz
| Download URL | nonebot_plugin_orm-0.8.4.tar.gz |
|---|---|
| Size | 26.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
724737ffa23c7c959ab5687eb27f8c02e8167fd0efef1c1b09e5ef84da0e927b
|
|
BLAKE2b-256 checksum How to use checksums |
f8ceabffce111b2d9afd050279f15931fb83260c2244990c9df3a18e1ca1aea7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / nonebot_plugin_orm-0.8.4-py3-none-any.whl
| Download URL | nonebot_plugin_orm-0.8.4-py3-none-any.whl |
|---|---|
| Size | 31.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d96ed0e9204dce46eeb4003c122e724a00f287116394d269cc4089e03c1d2f9
|
|
BLAKE2b-256 checksum How to use checksums |
32b0b1693461f1dc69524585e9a804e9882da9ee1af8353c00d6bd58f7fffd5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for nonebot-plugin-orm 0.8.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for nonebot_plugin_orm-0.8.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.