应配置WorkBuddy迁移机制：一、集成环境与依赖；二、执行结构比对生成迁移文件；三、通过注释定制字段行为；四、导出纯SQL供DBA审核；五、支持从现有数据库反向生成模型与迁移脚本。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在开发过程中自动同步数据库结构变更与代码模型，避免手动编写SQL脚本的繁琐和易错问题，则可能是由于缺乏对WorkBuddy迁移机制的配置与调用。以下是利用WorkBuddy自动生成数据库迁移脚本的具体操作步骤：
一、确认WorkBuddy环境集成与依赖配置
WorkBuddy需作为项目构建流程的一部分被正确引入，其核心能力依赖于底层ORM框架（如SQLAlchemy）与数据库连接元数据的实时读取。只有在项目中完成基础依赖声明和数据库连接初始化后，才能触发结构比对与脚本生成逻辑。
1、在项目根目录的requirements.txt中添加WorkBuddy及配套组件：
workbuddy==2.4.1
sqlalchemy>=1.4.0
pyyaml>=6.0
2、确保database.py或等效模块中已定义并导出engine与metadata对象，且metadata已绑定所有待管理的表模型。
3、运行命令验证连接可用性：
python -c "from database import engine; engine.connect().close(); print('Connection OK')"
二、执行结构差异检测并生成初始迁移文件
WorkBuddy通过比对当前代码中定义的模型结构与目标数据库实际schema，识别新增、删除或修改的字段与约束，并据此生成可执行的迁移脚本。该过程不修改数据库，仅输出待审核的SQL内容。
1、在终端中执行结构扫描命令：
workbuddy revision --autogenerate -m "initial schema from models"
2、检查输出路径（默认为migrations/versions/）是否生成形如abcd1234_init_schema_from_models.py的文件。
3、打开该文件，确认upgrade()函数内包含完整op.create_table()或op.alter_column()调用，且无pass占位符。
三、定制化迁移脚本内容与字段级控制
自动生成的脚本可能无法覆盖特殊业务逻辑（如JSON字段默认值、复合索引命名、ENUM类型映射），需人工介入编辑。WorkBuddy支持在生成前通过注释指令干预字段行为，避免后续手动补丁。
1、在模型字段定义上方添加WorkBuddy识别注释：
# workbuddy: default='NOW()'created_at = Column(DateTime)
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
2、对需跳过自动处理的字段添加忽略标记：
# workbuddy: skiplegacy_hash = Column(String(64))
3、重新运行自动生成命令，确认新迁移文件中对应字段已按注释要求生成SQL片段。
四、生成纯SQL格式迁移文件供DBA审核
部分生产环境禁止直接执行Python迁移函数，要求提供标准SQL语句。WorkBuddy支持将Python迁移脚本编译为可交付的SQL文本，保留事务边界与执行顺序。
1、定位刚生成的Python迁移文件全路径，例如：
migrations/versions/abcd1234_init_schema_from_models.py
2、执行SQL导出命令：
workbuddy upgrade --sql abcd1234_init_schema_from_models
3、终端将直接打印完整SQL内容，复制保存为init_schema_v1.sql，供数据库管理员离线执行。
五、基于已有数据库反向生成模型与迁移起点
当项目已存在线上MySQL数据库，但无对应Python模型时，WorkBuddy可连接该库并反向解析表结构，生成兼容的模型代码与首版迁移脚本，实现“从库到代码”的逆向同步。
1、设置环境变量指定源库连接串：
export WORKBUDDY_SOURCE_URL=mysql+pymysql://user:pass@10.0.1.5:3306/prod_db
2、执行反向工程命令：
workbuddy scaffold --output models/ --tables users,orders,products
3、检查models/__init__.py是否已导入新生成的类，并确认metadata已注册全部表对象。
