Skip to main content

nonebot

NoneBot Plugin ORM

✨ NoneBot 数据库支持插件 ✨

license pypi python

安装

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)

Source distribution for nonebot-plugin-orm 0.8.4
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)

Table of built distributions (wheels) for nonebot-plugin-orm 0.8.4
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.8.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page