📝 docs: update README.md

README.md

@@ -1 +1,216 @@
-# nonebot-plugin-orm
+<!-- markdownlint-disable MD033 MD041 -->
+<p align="center">
+  <a href="https://nonebot.dev/"><img src="https://nonebot.dev/logo.png" width="200" height="200" alt="nonebot"></a>
+</p>
+
+<div align="center">
+
+# NoneBot Plugin ORM
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable-next-line MD036 -->
+_✨ NoneBot 数据库支持插件 ✨_
+<!-- prettier-ignore-end -->
+
+</div>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/nonebot/plugin-orm/master/LICENSE">
+    <img src="https://img.shields.io/github/license/nonebot/plugin-orm.svg" alt="license">
+  </a>
+  <a href="https://pypi.org/project/nonebot-plugin-orm/">
+    <img src="https://img.shields.io/pypi/v/nonebot-plugin-orm.svg" alt="pypi">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="python">
+</p>
+
+## 安装
+
+```shell
+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
+
+```python
+from nonebot import require
+from nonebot.params import Depends
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.ext.asyncio import async_scoped_session
+
+require("nonebot_plugin_orm")
+
+from nonebot_plugin_orm import Model, get_scoped_session
+
+
+class MyModel(Model):
+    id: Mapped[int] = mapped_column(primary_key=True)
+    data: Mapped[str]
+
+
+@matcher.handle()
+async def handler(session: async_scoped_session = Depends(get_scoped_session)):
+    session.add(MyModel(data="data"))
+    await session.commit()
+```
+
+### CLI
+
+```properties
+$ 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](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)
+
+```properties
+SQLALCHEMY_DATABASE_URL=sqlite+aiosqlite://
+```
+
+### sqlalchemy_binds
+
+bind keys 到 `AsyncEngine` 选项的映射。值可以是数据库连接 URL、`AsyncEngine` 选项字典或者 `AsyncEngine` 实例。
+
+```properties
+SQLALCHEMY_BINDS='{
+    "": "sqlite+aiosqlite://",
+    "nonebot_plugin_user": {
+        "url": "postgresql+asyncpg://scott:tiger@localhost/mydatabase",
+        "echo": true
+    }
+}'
+```
+
+### sqlalchemy_echo
+
+所有 `AsyncEngine` 的 `echo` 和 `echo_pool` 选项的默认值。用于快速调试连接和 SQL 生成问题。
+
+```properties
+SQLALCHEMY_ECHO=true
+```
+
+### sqlalchemy_engine_options
+
+所有 `AsyncEngine` 的默认选项字典。
+参见：[Engine Configuration — SQLAlchemy 2.0 Documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#engine-configuration)
+
+```properties
+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](https://docs.sqlalchemy.org/en/20/orm/session_api.html#sqlalchemy.orm.Session.__init__)
+
+```properties
+SQLALCHEMY_SESSION_OPTIONS='{
+    "autoflush": false,
+    "autobegin": true,
+    "expire_on_commit": true
+}'
+```
+
+### alembic_config
+
+配置文件路径或 `AlembicConfig` 实例。
+
+```properties
+ALEMBIC_CONFIG=alembic.ini
+```
+
+### alembic_script_location
+
+脚本目录路径。
+
+```properties
+ALEMBIC_SCRIPT_LOCATION=migrations
+```
+
+### alembic_version_locations
+
+迁移脚本目录路径或分支标签到迁移脚本目录路径的映射。
+
+```properties
+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](https://alembic.sqlalchemy.org/en/latest/api/runtime.html#alembic.runtime.environment.EnvironmentContext.configure)
+
+```properties
+ALEMBIC_CONTEXT='{
+    "render_as_batch": true
+}'
+```
+
+### alembic_startup_check
+
+是否在启动时检查数据库与模型定义的一致性。
+
+```properties
+ALEMBIC_STARTUP_CHECK=true
+```