From 0e5ddb6dcca4d58e670e69405503da184cd8c45c Mon Sep 17 00:00:00 2001
From: RockChinQ <rockchinq@gmail.com>
Date: Wed, 8 Apr 2026 23:50:43 +0800
Subject: [PATCH] docs: add autogenerate and CLI tool docs for migrations
 (zh/en/ja)

---
 en/develop/dev-config.mdx | 31 ++++++++++++++++++++++++++++++-
 ja/develop/dev-config.mdx | 31 ++++++++++++++++++++++++++++++-
 zh/develop/dev-config.mdx | 31 ++++++++++++++++++++++++++++++-
 3 files changed, 90 insertions(+), 3 deletions(-)

diff --git a/en/develop/dev-config.mdx b/en/develop/dev-config.mdx
index e60272db0..47ebcc63d 100644
--- a/en/develop/dev-config.mdx
+++ b/en/develop/dev-config.mdx
@@ -83,7 +83,20 @@ src/langbot/pkg/persistence/alembic/versions/
 
 ### Creating a New Migration
 
-Create a new Python file in the `versions/` directory following the naming convention `NNNN_description.py`:
+The recommended way is to use **autogenerate**, which compares ORM models against the database schema and generates a migration script:
+
+```bash
+# Run from the project root (requires data/config.yaml)
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "describe your changes"
+```
+
+The generated file will appear in `src/langbot/pkg/persistence/alembic/versions/`. Review and edit the generated script to confirm the changes are correct before committing.
+
+<Info>
+Autogenerate can automatically detect column additions/removals, table changes, type changes, etc. However, for **data migrations** (e.g., modifying JSON field content), you need to manually add code to the generated script.
+</Info>
+
+You can also create migration files manually, following the naming convention `NNNN_description.py`:
 
 ```python
 """Describe your migration
@@ -160,3 +173,19 @@ Migrations run automatically when LangBot starts — no manual commands needed:
 ### CI Testing
 
 The repository includes a `test-migrations.yml` workflow that automatically tests migration scripts on both SQLite and PostgreSQL when `persistence/` related files change.
+
+### CLI Tool
+
+```bash
+# Autogenerate migration (compare ORM models against DB)
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"
+
+# Upgrade database
+uv run python -m langbot.pkg.persistence.alembic_runner upgrade
+
+# Show current revision
+uv run python -m langbot.pkg.persistence.alembic_runner current
+
+# Stamp revision (without running migrations)
+uv run python -m langbot.pkg.persistence.alembic_runner stamp head
+```
diff --git a/ja/develop/dev-config.mdx b/ja/develop/dev-config.mdx
index 7de30c7a4..29c25a32d 100644
--- a/ja/develop/dev-config.mdx
+++ b/ja/develop/dev-config.mdx
@@ -83,7 +83,20 @@ src/langbot/pkg/persistence/alembic/versions/
 
 ### 新しいマイグレーションの作成
 
-`versions/` ディレクトリに `NNNN_description.py` の命名規則に従ってPythonファイルを作成します：
+**autogenerate** を使用してマイグレーションスクリプトを自動生成することを推奨します。ORMモデルとデータベーススキーマの差分を比較して生成します：
+
+```bash
+# プロジェクトルートで実行（data/config.yaml が必要）
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "変更内容の説明"
+```
+
+生成されたファイルは `src/langbot/pkg/persistence/alembic/versions/` に作成されます。生成されたスクリプトを確認・編集し、変更が正しいことを確認してからコミットしてください。
+
+<Info>
+autogenerateは列の追加/削除、テーブルの変更、型の変更などを自動検出できます。ただし、**データマイグレーション**（JSONフィールドの内容変更など）は、生成されたスクリプトに手動でコードを追加する必要があります。
+</Info>
+
+手動でマイグレーションファイルを作成することもできます。命名規則 `NNNN_description.py` に従ってください：
 
 ```python
 """マイグレーションの説明
@@ -160,3 +173,19 @@ def upgrade() -> None:
 ### CIテスト
 
 リポジトリには`test-migrations.yml`ワークフローが含まれており、`persistence/`関連ファイルが変更された際に、SQLiteとPostgreSQLの両方でマイグレーションスクリプトが自動テストされます。
+
+### CLIツール
+
+```bash
+# マイグレーションを自動生成（ORMモデルとDBの差分を比較）
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "説明"
+
+# データベースをアップグレード
+uv run python -m langbot.pkg.persistence.alembic_runner upgrade
+
+# 現在のリビジョンを表示
+uv run python -m langbot.pkg.persistence.alembic_runner current
+
+# リビジョンをスタンプ（マイグレーションを実行せず）
+uv run python -m langbot.pkg.persistence.alembic_runner stamp head
+```
diff --git a/zh/develop/dev-config.mdx b/zh/develop/dev-config.mdx
index dea820ff6..a6e0caf98 100644
--- a/zh/develop/dev-config.mdx
+++ b/zh/develop/dev-config.mdx
@@ -83,7 +83,20 @@ src/langbot/pkg/persistence/alembic/versions/
 
 ### 创建新迁移
 
-在 `versions/` 目录下新建 Python 文件，遵循命名规范 `NNNN_description.py`：
+推荐使用 **autogenerate** 自动生成迁移脚本，它会对比 ORM 模型和数据库 schema 的差异：
+
+```bash
+# 在项目根目录下运行（需要已有 data/config.yaml）
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "描述你的变更"
+```
+
+生成的文件会出现在 `src/langbot/pkg/persistence/alembic/versions/` 目录下，请检查并编辑生成的脚本，确认变更无误后提交。
+
+<Info>
+autogenerate 能自动检测列的增删、表的增删、类型变更等。但对于**数据迁移**（如修改 JSON 字段的内容），需要手动在生成的脚本中添加代码。
+</Info>
+
+也可以手动创建迁移文件，遵循命名规范 `NNNN_description.py`：
 
 ```python
 """描述你的迁移
@@ -160,3 +173,19 @@ def upgrade() -> None:
 ### CI 测试
 
 仓库中包含 `test-migrations.yml` 工作流，当 `persistence/` 相关文件变更时会自动在 SQLite 和 PostgreSQL 上测试迁移脚本。
+
+### CLI 工具
+
+```bash
+# 自动生成迁移脚本（对比 ORM 模型和数据库）
+uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "描述"
+
+# 升级数据库
+uv run python -m langbot.pkg.persistence.alembic_runner upgrade
+
+# 查看当前版本
+uv run python -m langbot.pkg.persistence.alembic_runner current
+
+# 标记版本（不执行迁移）
+uv run python -m langbot.pkg.persistence.alembic_runner stamp head
+```