71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
|
# 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`）
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
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 部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd docker
|
|||
|
|
docker compose exec -T backend python /home/scripts/run_migrations.py
|
|||
|
|
```
|
|||
|
|
或直接 `deploy.sh migrate`（已接此入口）。容器内挂载 backend 代码到 `/home`，
|
|||
|
|
`ENVIRONMENT` 由 compose 注入（prod 默认 postgres，runner 自动只跑适用迁移）。
|
|||
|
|
|
|||
|
|
## 单支脚本用法
|
|||
|
|
|
|||
|
|
每支脚本同样支持单独执行/预览：
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
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] 全部迁移完成
|
|||
|
|
```
|