AIclinicalresearch/docs/09-架构实施/migration-scripts

Schema迁移脚本使用指南

版本： V1.0
创建日期： 2025-11-09
迁移目标： 从public schema迁移到10个隔离Schema

---

📋 脚本清单

#	脚本名称	说明	预计时间	前置依赖
1	001-create-all-10-schemas.sql	创建10个Schema（3详细+7空）	5秒	无
2	002-migrate-platform.sql	迁移platform_schema（1个表：users）	15分钟	001
3	003-migrate-aia.sql	迁移aia_schema（5个表：对话相关）	30分钟	001, 002
4	004-migrate-pkb.sql	迁移pkb_schema（5个表：知识库相关）	30分钟	001, 002
5	005-validate-all.sql	全局验证和数据完整性检查	10分钟	001-004

总计： 约1.5小时

---

🚀 执行步骤

前置准备

1. 备份数据库（强烈建议）

   pg_dump -U postgres -d your_database > backup_$(date +%Y%m%d_%H%M%S).sql
   

2. 确认数据库连接

   # 确保DATABASE_URL环境变量正确
   echo $DATABASE_URL
   # 或查看 .env 文件
   

3. 确认当前表结构

   SELECT tablename FROM pg_tables WHERE schemaname = 'public';
   

---

执行迁移

方法1：使用psql命令（推荐）

# 进入脚本目录
cd AIclinicalresearch/docs/09-架构实施/migration-scripts

# 依次执行脚本
psql $DATABASE_URL -f 001-create-all-10-schemas.sql
psql $DATABASE_URL -f 002-migrate-platform.sql
psql $DATABASE_URL -f 003-migrate-aia.sql
psql $DATABASE_URL -f 004-migrate-pkb.sql
psql $DATABASE_URL -f 005-validate-all.sql

方法2：一次性执行所有脚本

# 创建执行脚本
cat 001-create-all-10-schemas.sql \
    002-migrate-platform.sql \
    003-migrate-aia.sql \
    004-migrate-pkb.sql \
    005-validate-all.sql \
    | psql $DATABASE_URL

方法3：使用数据库客户端（如DBeaver、pgAdmin）

1. 打开数据库客户端
2. 连接到目标数据库
3. 依次打开并执行每个SQL文件

---

✅ 验证清单

执行001后

• 10个Schema全部创建成功
• 每个Schema都有注释说明

-- 验证SQL
SELECT nspname, pg_catalog.obj_description(oid, 'pg_namespace')
FROM pg_namespace
WHERE nspname LIKE '%_schema'
ORDER BY nspname;

执行002后

• platform_schema.users表创建成功
• 数据从public.users完整迁移
• 4个索引创建成功

-- 验证SQL
SELECT COUNT(*) AS public_count FROM public.users;
SELECT COUNT(*) AS platform_count FROM platform_schema.users;

执行003后

• aia_schema的5个表创建成功
• 数据完整迁移
• 外键约束正确建立

-- 验证SQL
SELECT COUNT(*) FROM aia_schema.projects;
SELECT COUNT(*) FROM aia_schema.conversations;

执行004后

• pkb_schema的5个表创建成功
• 包含Phase 2全文阅读字段
• 数据完整迁移

-- 验证SQL
SELECT COUNT(*) FROM pkb_schema.knowledge_bases;
SELECT COUNT(*) FROM pkb_schema.documents;

执行005后

• 所有数据量对比一致
• 跨Schema外键引用有效
• 无数据丢失

---

📊 迁移后数据分布

Platform Schema

platform_schema
└── users (1表)

AIA Schema

aia_schema
├── projects
├── conversations
├── messages
├── general_conversations
└── general_messages (5表)

PKB Schema

pkb_schema
├── knowledge_bases
├── documents
├── batch_tasks
├── batch_results
└── task_templates (5表)

空Schema（7个）

asl_schema      (AI智能文献 - Week 3设计)
common_schema   (通用能力层)
dc_schema       (数据清洗)
rvw_schema      (审稿系统)
admin_schema    (运营管理)
ssa_schema      (智能统计分析)
st_schema       (统计分析工具)

---

⚠️ 注意事项

1. 事务保护

所有迁移脚本都使用了事务（BEGIN/COMMIT）：

• 成功：全部提交
• 失败：自动回滚，无部分迁移

2. 幂等性

所有脚本支持重复执行：

• 使用 IF NOT EXISTS 创建对象
• 使用 ON CONFLICT DO NOTHING 插入数据

3. public schema保留

迁移后不会删除 public schema中的原表：

• 原因：方便回滚和对比验证
• 清理：待所有验证通过后，再决定是否删除

4. 外键约束

支持跨Schema外键：

• 所有业务表引用 platform_schema.users(id)
• PostgreSQL原生支持，无需特殊配置

---

🔧 故障排查

问题1：连接被拒绝

错误： connection refused

解决：

# 检查PostgreSQL服务
sudo systemctl status postgresql

# 启动服务
sudo systemctl start postgresql

问题2：权限不足

错误： permission denied to create schema

解决：

-- 授予权限
GRANT CREATE ON DATABASE your_database TO your_user;

问题3：外键约束失败

错误： violates foreign key constraint

解决：

• 确保先执行 002（platform）再执行 003/004（aia/pkb）
• 检查是否有孤立的user_id

问题4：数据量不一致

错误： 验证脚本报告数据量不一致

解决：

1. 检查是否有迁移过程中新增的数据
2. 使用ID对比检查具体差异：

   -- 找出差异的ID
   SELECT id FROM public.users
   EXCEPT
   SELECT id FROM platform_schema.users;
   

---

📝 回滚方案

快速回滚（推荐）

-- 删除所有新建的Schema（会级联删除所有表和数据）
DROP SCHEMA IF EXISTS platform_schema CASCADE;
DROP SCHEMA IF EXISTS aia_schema CASCADE;
DROP SCHEMA IF EXISTS pkb_schema CASCADE;
DROP SCHEMA IF EXISTS asl_schema CASCADE;
DROP SCHEMA IF EXISTS common_schema CASCADE;
DROP SCHEMA IF EXISTS dc_schema CASCADE;
DROP SCHEMA IF EXISTS rvw_schema CASCADE;
DROP SCHEMA IF EXISTS admin_schema CASCADE;
DROP SCHEMA IF EXISTS ssa_schema CASCADE;
DROP SCHEMA IF EXISTS st_schema CASCADE;

从备份恢复

# 恢复备份
psql $DATABASE_URL < backup_20251109_100000.sql

---

📂 后续步骤

迁移完成后，需要：

1. 更新Prisma配置 → 见任务9

   • 更新 backend/prisma/schema.prisma
   • 添加 multiSchema 预览特性
   • 为3个Schema定义模型

2. 生成Prisma Client

   cd backend
   npx prisma generate
   

3. 更新代码 → 见任务12

   • 所有数据库查询使用新Schema
   • 测试现有功能

4. 运行测试 → 见任务8

   • 测试AI智能问答
   • 测试知识库功能

---

📞 获取帮助

如果遇到问题：

1. 查看日志 - psql会输出详细的执行信息和错误
2. 检查文档 - 参考 09-架构实施/01-Schema隔离架构设计（10个）.md
3. 验证数据 - 运行 005-validate-all.sql

---

创建人： AI助手
最后更新： 2025-11-09
版本： V1.0

核心理念：可重复执行 + 事务保护 + 完整验证 = 安全迁移 ⭐⭐⭐