huang
041856dc8c
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m13s
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 数据库迁移说明
|
||
|
||
## 当前结构
|
||
|
||
```
|
||
migrations/
|
||
├── 000114_squash_baseline.up.sql ← ⚠️ 待创建（见下方说明）
|
||
├── 000114_squash_baseline.down.sql ← ⚠️ 待创建
|
||
├── 000115_init_data.up.sql ← 初始化数据（轮询配置 + purchase_role 回填）
|
||
├── 000115_init_data.down.sql
|
||
├── 000116_remove_legacy_commission_fields.up.sql ← 删除废弃分佣字段
|
||
├── 000116_remove_legacy_commission_fields.down.sql
|
||
└── archive/ ← 已归档的历史迁移（000000~000113）
|
||
```
|
||
|
||
## ⚠️ 发布前必做：生成 000114 squash 基线
|
||
|
||
**背景**：历史迁移（000000-000113）已归档，但尚未生成汇总基线文件。
|
||
现有测试环境的表是在 migrate 工具之外创建的，不受影响。
|
||
但全新环境（本地搭建、CI、生产首次部署）必须有 000114 才能通过 `migrate up` 建表。
|
||
|
||
**执行时机**：正式发布前，确认 schema 已稳定后执行一次。
|
||
|
||
**步骤**：
|
||
|
||
1. 安装 PostgreSQL 客户端（若未安装）：
|
||
```bash
|
||
brew install libpq
|
||
export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
|
||
```
|
||
|
||
2. 生成 schema 基线（仅 DDL，不含数据）：
|
||
```bash
|
||
PGPASSWORD=<密码> pg_dump \
|
||
--schema-only --no-owner --no-acl \
|
||
-h <host> -U <user> -d <dbname> \
|
||
> migrations/000114_squash_baseline.up.sql
|
||
```
|
||
|
||
3. 在生成的 `000114_squash_baseline.up.sql` 头部加上注释（参考其他迁移文件格式）。
|
||
|
||
4. 创建 `000114_squash_baseline.down.sql`（删除所有表）：
|
||
```sql
|
||
-- 回滚：删除所有业务表（谨慎执行）
|
||
DROP TABLE IF EXISTS tb_wechat_config CASCADE;
|
||
DROP TABLE IF EXISTS tb_tag CASCADE;
|
||
-- ... 其他表（按依赖倒序）
|
||
```
|
||
|
||
5. 找 AI 协助完成 down.sql 和验证步骤（在全新数据库执行 `migrate up` 验证链路）。
|
||
|
||
6. 更新 `scripts/reset_db.sh` 中的注释，确认脚本可用。
|
||
|
||
## 迁移链路（目标状态）
|
||
|
||
```
|
||
全新数据库
|
||
└─ migrate up
|
||
├─ 000114: 建表（squash 基线）
|
||
├─ 000115: 写初始化数据
|
||
└─ 000116: 删除废弃字段
|
||
```
|
||
|
||
## 现有测试环境说明
|
||
|
||
测试环境的表通过历史方式创建，`schema_migrations` 中仅记录版本 116。
|
||
对正在运行的服务**没有影响**。
|
||
若需在测试库补齐迁移记录，可手动运行 `migrate up`（000115 全部幂等，安全）。
|