modify: 说明文档

README.md

@@ -1,6 +1,6 @@
 # chongming-database
 
-异步 SQLite 数据库封装，基于 `aiosqlite` + `SQLModel`（SQLAlchemy），提供简洁的初始化与会话管理接口。
+异步 SQLite 数据库封装，基于 `aiosqlite` + `SQLModel`（SQLAlchemy），提供简洁的初始化与会话管理接口，内置多进程并发安全。
 
 ---
 
@@ -20,30 +20,27 @@ uv pip install -e utils/database
 from pathlib import Path
 from chongming_database import Database
 
-# 创建实例
 db = Database(Path("data/storage/chongming/app.db"))
+await db.initialize()     # 创建引擎 + 自动建表
 
-# 初始化（创建引擎 + 自动建表）
-await db.initialize()
-
-# 获取异步会话
 async with db.get_session() as session:
-    # 使用 SQLModel / SQLAlchemy 进行查询
     result = await session.execute(...)
-    ...
 
-# 关闭连接
-await db.dispose()
+await db.dispose()         # 关闭连接
 ```
 
 ### 方法说明
 
-| 方法          | 签名                 | 说明                                                                                                                                              |
-| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `__init__`    | `(db_path: Path)`    | 传入 SQLite 文件路径，自动创建父目录                                                                                                              |
-| `initialize`  | `async () -> None`   | 创建异步 SQLAlchemy 引擎（`sqlite+aiosqlite:///`），执行 `SQLModel.metadata.create_all` 自动建表，构建 `sessionmaker`（`expire_on_commit=False`） |
-| `get_session` | `() -> AsyncSession` | 返回一个新的异步会话。如果 `initialize()` 未调用则抛出 `RuntimeError`                                                                             |
-| `dispose`     | `async () -> None`   | 关闭异步引擎并清除内部状态                                                                                                                        |
+| 方法          | 签名                 | 说明                                                                                                                             |
+| ------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `__init__`    | `(db_path: Path)`    | 传入 SQLite 文件路径，自动创建父目录                                                                                             |
+| `initialize`  | `async () -> None`   | 创建异步引擎（`sqlite+aiosqlite:///`），`SQLModel.metadata.create_all` 自动建表，构建 `sessionmaker`（`expire_on_commit=False`） |
+| `get_session` | `() -> AsyncSession` | 返回新的异步会话；未初始化则抛 `RuntimeError`                                                                                    |
+| `dispose`     | `async () -> None`   | 关闭异步引擎并清除内部状态                                                                                                       |
+
+### 多进程安全
+
+`initialize()` 使用 `checkfirst=True` 检查表是否存在，并捕获 `OperationalError("already exists")` 作为兜底，确保多个进程并发启动时不会因建表冲突而崩溃。
 
 ---
 
@@ -81,9 +78,26 @@ finally:
     await db.dispose()
 ```
 
+### 插件中的典型用法
+
+```python
+# src/plugins/<name>/__init__.py
+from pathlib import Path
+from chongming_database import Database
+from .global_var import set_db
+
+async def create_workers(session, config, count, worker_manager):
+    db_path = Path(config.get("data_dir", "./data")) / "<name>.db"
+    db = Database(db_path)
+    await db.initialize()
+    set_db(db)
+    ...
+```
+
 ---
 
 ## 依赖
 
 - `aiosqlite` — 异步 SQLite 驱动
-- `sqlmodel` — SQLAlchemy + Pydantic 融合 ORM
+- `sqlmodel` — SQLAlchemy + Pydantic ORM
+- `sqlalchemy` — 异步引擎支持