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] 全部迁移完成
|
||
```
|