255 lines
6.0 KiB
Markdown
255 lines
6.0 KiB
Markdown
# 修改 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`，所以修改后必须重启应用才能生效！
|