rwadurian/backend/services/admin-service/database

Database 目录说明

目录用途

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

文件说明

init.sql

用途: 数据库初始化脚本

使用场景:

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

执行方式:

# 手动执行（如果需要）
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 中使用初始化脚本，可以这样配置：

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:

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 脚本

解决方案:

# 删除 volume 重新创建
docker-compose down -v
docker-compose up

重复执行错误

原因: 脚本不是幂等的

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

---

最后更新: 2025-12-03