# Database 目录说明

## 目录用途

`database/` 目录用于存放数据库相关的初始化脚本和迁移文件。

## 文件说明

### init.sql
**用途**: 数据库初始化脚本

**使用场景**:
- 在数据库首次创建后，需要插入初始数据时使用
- 在 Docker Compose 启动时自动执行
- 在测试环境中初始化测试数据

**执行方式**:
```bash
# 手动执行（如果需要）
psql -U postgres -d admin_service -f database/init.sql

# 或通过 Docker Compose volume 映射自动执行
```

## 与 Prisma 的关系

### Prisma Migrations
- **位置**: `prisma/migrations/`
- **用途**: 创建和管理数据库表结构
- **执行**: `npx prisma migrate deploy`

### database/init.sql
- **位置**: `database/init.sql`
- **用途**: 在表结构创建后，插入初始数据
- **执行**: 在 migrations 之后手动或自动执行

## 执行顺序

正确的数据库初始化顺序：

```
1. Prisma Migrations (创建表结构)
   ↓
2. database/init.sql (插入初始数据)
```

## Docker Compose 集成

如果需要在 Docker Compose 中使用初始化脚本，可以这样配置：

```yaml
services:
  postgres:
    image: postgres:16-alpine
    volumes:
      - ./database/init.sql:/docker-entrypoint-initdb.d/01-init.sql
      - postgres_data:/var/lib/postgresql/data
```

**注意**: PostgreSQL Docker 镜像会自动执行 `/docker-entrypoint-initdb.d/` 目录中的 `.sql` 文件。

## 当前状态

### Admin Service
- ✅ Prisma schema 定义完成
- ✅ Migrations 已创建
- ⚠️  目前不需要初始数据
- ✅ init.sql 文件已创建（保留用于未来需求）

## 使用示例

### 添加初始版本记录

如果需要在数据库初始化时插入默认版本，可以编辑 `init.sql`:

```sql
INSERT INTO "AppVersion" (
  id,
  platform,
  "versionCode",
  "versionName",
  "buildNumber",
  "downloadUrl",
  "fileSize",
  "fileSha256",
  changelog,
  "isEnabled",
  "isForceUpdate",
  "createdBy",
  "createdAt",
  "updatedAt"
)
VALUES (
  'initial-android',
  'android',
  1,
  '1.0.0',
  '1',
  'https://example.com/app-v1.apk',
  10485760,
  'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
  'Initial release',
  true,
  false,
  'system',
  NOW(),
  NOW()
)
ON CONFLICT (id) DO NOTHING;
```

## 参考其他服务

### identity-service
- 使用 `init.sql` 初始化账户序列号生成器
- 示例: `INSERT INTO account_sequence_generator`

### mpc-service
- 使用 `database/migrations/` 存放自定义迁移

## 最佳实践

1. **幂等性**: 所有 SQL 脚本都应该是幂等的（可重复执行）
   - 使用 `ON CONFLICT DO NOTHING`
   - 使用 `IF NOT EXISTS`

2. **注释**: 为所有初始化脚本添加清晰的注释

3. **版本控制**: 将 `database/` 目录纳入 Git 版本控制

4. **测试**: 确保初始化脚本在测试环境中正常工作

## 故障排查

### 初始化脚本未执行

**原因**: PostgreSQL 只在首次创建数据库时执行 initdb 脚本

**解决方案**:
```bash
# 删除 volume 重新创建
docker-compose down -v
docker-compose up
```

### 重复执行错误

**原因**: 脚本不是幂等的

**解决方案**: 使用 `ON CONFLICT` 或 `IF NOT EXISTS`

---

*最后更新: 2025-12-03*