王伟志 7800b7786d feat: init

2025-11-23 14:04:20 +08:00

6.0 KiB

Raw Blame History

修改 DATABASE_URL 后的操作指南

📋 操作决策树

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

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

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

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

# 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：目标数据库是空的（新数据库）

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

# 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

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

# 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
数据库结构改变 → 需要创建迁移并应用到数据库

📝 完整操作流程

开发环境（推荐流程）

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

生产环境（部署流程）

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 是否生效

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

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

2. 验证数据库连接

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

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

3. 验证表结构

# 检查迁移状态
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 后的最小操作：

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

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

6.0 KiB Raw Blame History Unescape Escape