dpb/backend/scripts

breeding 迁移机制

breeding 模块无 alembic 基线（表由 create_all 创建），直接 alembic revision --autogenerate 会试图重建全部表、风险高。故所有结构/数据变更统一走幂等迁移脚本：每支脚本可重复执行， 重复运行不产生副作用，单支失败不影响其余。

统一入口：run_migrations.py

按依赖顺序执行整套迁移，并依据数据库方言（settings.DATABASE_TYPE）自动跳过不支持的脚本：

脚本	作用	PostgreSQL
fix_breeding_columns.py	ORM 与库列补齐（生成器改字段后同步）	✔
schema_align.py	审计列统一新契约（uuid/is_deleted bool/审计 FK）	✔
align_columns.py	业务必填列 NOT NULL 对齐（无 NULL 才收紧）	✔
add_unique_constraints.py	业务唯一约束落库（部分唯一索引，未软删）	✔
migrate_dict_english.py	字典存量中文 label → 英码 value	✔

说明：

• 生产仅使用 PostgreSQL；PostgreSQL 专属语法（部分唯一索引 WHERE is_deleted = false、 gen_random_uuid() 等）在非 postgres 方言下自动跳过并提示。
• 每支脚本均幂等；--check 仅对声明支持的脚本生效，不支持的（schema_align.py）在预览模式下跳过。

本地开发（Windows，conda dpb）

cd backend
$env:ENVIRONMENT = "dev"
uv run python scripts/run_migrations.py --check   # 预览
uv run python scripts/run_migrations.py            # 执行

（无 uv 时可用 conda 环境的 python 替代 uv run python。）

Docker 部署

cd docker
docker compose exec -T backend python /home/scripts/run_migrations.py

或直接 deploy.sh migrate（已接此入口）。容器内挂载 backend 代码到 /home， ENVIRONMENT 由 compose 注入（prod 默认 postgres，runner 自动只跑适用迁移）。

单支脚本用法

每支脚本同样支持单独执行/预览：

uv run python scripts/fix_breeding_columns.py --check      # 仅预览 DDL，不落库
uv run python scripts/fix_breeding_columns.py              # 执行补齐
uv run python scripts/schema_align.py                      # 审计列统一（幂等）
uv run python scripts/add_unique_constraints.py --check    # 唯一约束预览
uv run python scripts/add_unique_constraints.py            # 执行
uv run python scripts/migrate_dict_english.py --check      # 字典迁移预览
uv run python scripts/migrate_dict_english.py              # 执行（自动备份 bre_backup_*）

连接串来源

各脚本读取 app.config.setting.settings.DB_URI / ASYNC_DB_URI（与后端运行时一致），无需手动配置。

输出示例

[run_migrations] 数据库方言: postgres  模式: 执行
[run_migrations] 执行 fix_breeding_columns.py ...
[run_migrations] 执行 schema_align.py ...
[run_migrations] 执行 add_unique_constraints.py ...
[run_migrations] 执行 migrate_dict_english.py ...
[run_migrations] 全部迁移完成