library-picturebook-activity/backend/docs/ENV_CHANGE_GUIDE.md

# 修改 DATABASE_URL 后的操作指南

## 📋 操作决策树

```
修改 DATABASE_URL
    │
    ├─ 只改了连接信息（地址/端口/用户名/密码/数据库名）
    │   └─ schema.prisma 未修改
    │       ├─ 目标数据库已有表结构 → ✅ 只需重启应用
    │       └─ 目标数据库是空的 → ⚠️ 需要运行迁移
    │
    └─ 同时修改了 schema.prisma
        └─ ✅ 必须执行：生成 Client + 运行迁移
```

## 🔄 场景 1：只修改连接信息（最常见）

### 情况 A：目标数据库已有表结构

**示例**：从本地数据库切换到远程数据库，但表结构已存在

```bash
# 1. 修改 .development.env 文件
DATABASE_URL="mysql://user:pass@new-host:3306/db_name?schema=public"

# 2. 重启应用即可（无需执行 Prisma 命令）
npm run start:dev
```

**原因**：

- Prisma Client 在应用启动时读取 `process.env.DATABASE_URL`
- 如果目标数据库已有表结构，直接连接即可
- 不需要重新生成 Client（类型定义没变）
- 不需要运行迁移（表结构没变）

---

### 情况 B：目标数据库是空的（新数据库）

**示例**：切换到全新的数据库，还没有表结构

```bash
# 1. 修改 .development.env 文件
DATABASE_URL="mysql://user:pass@new-host:3306/new_db?schema=public"

# 2. 运行迁移创建表结构
npm run prisma:migrate

# 或使用部署模式（生产环境）
npm run prisma:migrate:deploy

# 3. 重启应用
npm run start:dev
```

**原因**：

- 新数据库没有表结构
- 需要运行迁移来创建表
- 迁移会读取 `process.env.DATABASE_URL` 连接到新数据库

---

## 🔄 场景 2：同时修改了 schema.prisma

**示例**：修改了数据库模型（添加/删除字段、表等）

```bash
# 1. 修改 schema.prisma（添加字段、表等）

# 2. 生成 Prisma Client（必须）
npm run prisma:generate

# 3. 创建并运行迁移（必须）
npm run prisma:migrate
# 会提示输入迁移名称，如：add_user_email_field

# 4. 重启应用
npm run start:dev
```

**原因**：

- schema.prisma 改变 → TypeScript 类型定义改变 → 需要重新生成 Client
- 数据库结构改变 → 需要创建迁移并应用到数据库

---

## 📝 完整操作流程

### 开发环境（推荐流程）

```bash
cd backend

# 1. 修改 .development.env 中的 DATABASE_URL
vim .development.env

# 2. 检查目标数据库是否有表结构
# 方式 A：使用 Prisma Studio 查看
npm run prisma:studio

# 方式 B：直接连接数据库查看
mysql -h host -u user -p database -e "SHOW TABLES;"

# 3. 根据情况选择操作：

# 情况 1：数据库已有表结构 → 只需重启
npm run start:dev

# 情况 2：数据库是空的 → 运行迁移
npm run prisma:migrate
npm run start:dev

# 情况 3：修改了 schema.prisma → 生成 + 迁移
npm run prisma:generate
npm run prisma:migrate
npm run start:dev
```

### 生产环境（部署流程）

```bash
cd backend

# 1. 修改生产环境配置文件或环境变量
# 注意：生产环境通常使用环境变量，而不是文件

# 2. 生成 Prisma Client
npm run prisma:generate

# 3. 运行迁移（生产环境使用 deploy，不会创建新迁移）
NODE_ENV=production npm run prisma:migrate:deploy

# 4. 重启应用
npm run start:prod
```

---

## ✅ 快速检查清单

修改 `DATABASE_URL` 后，按以下顺序检查：

- [ ] **只改了连接信息？**
  - [ ] 目标数据库有表 → ✅ 重启应用
  - [ ] 目标数据库为空 → ⚠️ 运行迁移

- [ ] **修改了 schema.prisma？**
  - [ ] 是 → ✅ 生成 Client + 运行迁移
  - [ ] 否 → 跳过

- [ ] **应用启动后验证**
  - [ ] 检查启动日志中的 DATABASE_URL
  - [ ] 访问 `/api/config-verification/env-info` 验证
  - [ ] 测试数据库操作是否正常

---

## 🔍 验证方法

### 1. 验证 DATABASE_URL 是否生效

```bash
# 启动应用后查看日志
npm run start:dev

# 应该看到：
# DATABASE_URL: 已设置 mysql://...
```

### 2. 验证数据库连接

```bash
# 使用 Prisma Studio 连接
npm run prisma:studio

# 如果能打开并看到表，说明连接成功
```

### 3. 验证表结构

```bash
# 检查迁移状态
npx prisma migrate status

# 应该显示：All migrations have been successfully applied
```

---

## ⚠️ 常见错误

### 错误 1：连接失败

```
Error: Can't reach database server
```

**解决**：

- 检查 DATABASE_URL 格式是否正确
- 检查数据库服务是否运行
- 检查网络连接和防火墙

### 错误 2：表不存在

```
Error: Table 'xxx' doesn't exist
```

**解决**：

- 运行迁移：`npm run prisma:migrate`
- 或使用：`npx prisma db push`（仅开发环境）

### 错误 3：迁移状态不一致

```
Error: The migration failed to apply
```

**解决**：

- 检查迁移历史：`npx prisma migrate status`
- 重置数据库（仅开发环境）：`npx prisma migrate reset`
- 或手动修复迁移文件

---

## 📚 相关命令速查

| 操作        | 命令                            | 说明                      |
| ----------- | ------------------------------- | ------------------------- |
| 生成 Client | `npm run prisma:generate`       | 根据 schema 生成类型      |
| 创建迁移    | `npm run prisma:migrate`        | 开发环境，会创建新迁移    |
| 应用迁移    | `npm run prisma:migrate:deploy` | 生产环境，只应用已有迁移  |
| 查看状态    | `npx prisma migrate status`     | 查看迁移状态              |
| 打开 Studio | `npm run prisma:studio`         | 可视化数据库              |
| 推送结构    | `npx prisma db push`            | 直接同步 schema（仅开发） |

---

## 🎯 总结

**修改 DATABASE_URL 后的最小操作**：

1. **只改连接信息 + 数据库有表** → ✅ **重启应用**
2. **只改连接信息 + 数据库为空** → ⚠️ **运行迁移**
3. **修改了 schema.prisma** → ✅ **生成 Client + 运行迁移**

**记住**：Prisma Client 在应用启动时读取 `process.env.DATABASE_URL`，所以修改后必须重启应用才能生效！