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

# DATABASE_URL 来源说明

## 📍 定义位置

`DATABASE_URL` 在 `schema.prisma` 中定义：

```prisma
datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")  // ← 从这里读取环境变量
}
```

## 🔄 加载流程

### 1. 配置文件定义

`DATABASE_URL` 定义在环境配置文件中：

**当前配置**：`.development.env` 文件
```env
DATABASE_URL="mysql://root:woshimima@localhost:3306/db_competition_management?schema=public"
```

### 2. NestJS ConfigModule 加载

在 `app.module.ts` 中配置：

```typescript
ConfigModule.forRoot({
  isGlobal: true,
  envFilePath: ['.development.env'],  // ← 从这里加载环境变量
})
```

**加载顺序**：
1. NestJS ConfigModule 读取 `.development.env` 文件
2. 将文件中的 `DATABASE_URL` 加载到 `process.env.DATABASE_URL`
3. 应用启动时，所有模块都可以通过 `ConfigService` 访问

### 3. Prisma 读取

Prisma 在以下时机读取 `DATABASE_URL`：

1. **生成 Prisma Client 时**：
   ```bash
   npx prisma generate
   ```
   - 读取 `process.env.DATABASE_URL`
   - 生成类型定义（不连接数据库）

2. **运行迁移时**：
   ```bash
   npx prisma migrate dev
   npx prisma migrate deploy
   ```
   - 读取 `process.env.DATABASE_URL`
   - 连接到数据库执行迁移

3. **应用运行时**：
   - `PrismaService` 初始化时读取 `process.env.DATABASE_URL`
   - 建立数据库连接

## 📂 配置文件优先级

根据 `app.module.ts` 的配置：

```typescript
envFilePath: ['.development.env']
```

**当前配置**：
- ✅ 优先加载：`.development.env`
- ⚠️ 注意：如果设置了 `ignoreEnvFile: true`，则不会加载文件，只使用系统环境变量

## 🔍 验证 DATABASE_URL 来源

### 方法 1：查看环境变量（应用运行时）

```bash
# 启动应用后，访问配置验证接口
curl http://localhost:3001/api/config-verification/env-info
```

### 方法 2：查看启动日志

应用启动时会在控制台显示：
```
=== 环境配置验证 ===
DATABASE_URL: 已设置 mysql://root:woshimima@localhost:3306/db_competition_management?schema=public
```

### 方法 3：检查配置文件

```bash
cd backend
cat .development.env | grep DATABASE_URL
```

### 方法 4：在代码中验证

```typescript
// 在任何服务中
constructor(private configService: ConfigService) {}

const dbUrl = this.configService.get('DATABASE_URL');
console.log('DATABASE_URL:', dbUrl);
```

## 🔐 环境变量来源优先级

Prisma 读取 `DATABASE_URL` 的优先级：

1. **系统环境变量**（最高优先级）
   ```bash
   export DATABASE_URL="mysql://..."
   ```

2. **.env 文件**（通过 ConfigModule 加载）
   - `.development.env`
   - `.env`

3. **默认值**（如果都没有设置，Prisma 会报错）

## 📝 DATABASE_URL 格式

```
mysql://用户名:密码@主机:端口/数据库名?参数
```

**示例**：
```env
# 本地数据库
DATABASE_URL="mysql://root:password@localhost:3306/db_competition_management?schema=public"

# 远程数据库
DATABASE_URL="mysql://user:pass@192.168.1.100:3306/db_name?schema=public"

# 带 SSL
DATABASE_URL="mysql://user:pass@host:3306/db_name?schema=public&sslmode=require"
```

## ⚠️ 注意事项

1. **密码包含特殊字符**：需要进行 URL 编码
   ```env
   # 密码: p@ssw0rd
   DATABASE_URL="mysql://user:p%40ssw0rd@localhost:3306/db"
   ```

2. **配置文件安全**：
   - `.development.env` 不应提交到 Git
   - 生产环境使用环境变量或密钥管理服务

3. **Prisma 读取时机**：
   - Prisma 直接读取 `process.env.DATABASE_URL`
   - 不依赖 NestJS ConfigModule（但 ConfigModule 会将文件内容加载到 `process.env`）

## 🔧 当前配置总结

- **配置文件**：`.development.env`
- **配置项**：`DATABASE_URL="mysql://root:woshimima@localhost:3306/db_competition_management?schema=public"`
- **加载方式**：NestJS ConfigModule → `process.env` → Prisma
- **验证方式**：启动日志或 `/api/config-verification/env-info` 接口