155 lines
3.3 KiB
Markdown
155 lines
3.3 KiB
Markdown
# 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*
|