playground/cmd/message-migrator/README.md

Message Migrator 数据迁移工具

这个工具用于将指定项目的消息数据从源数据库迁移到目标数据库。

功能特性

• ✅ 按项目ID迁移数据
• ✅ 支持可选的UID替换
• ✅ 自动处理表之间的ID关联映射
• ✅ 使用事务保证数据一致性
• ✅ 按正确的依赖顺序迁移：m_stream_messages → m_stream_contents → m_context_messages → m_task_messages

涉及的表

1. m_stream_messages - 流式消息记录表（主表）
2. m_stream_contents - 流式消息内容详情及分段表
3. m_context_messages - Agent上下文消息记录表
4. m_task_messages - 任务聚合消息记录表

安装依赖

go get github.com/go-sql-driver/mysql

配置

在使用前，请修改 main.go 中的数据库连接配置：

const (
    // 源数据库 DSN 格式: user:password@tcp(host:port)/database?parseTime=true
    SOURCE_DSN = "user:password@tcp(localhost:3306)/goalfymax_prod?parseTime=true"
    // 目标数据库 DSN
    TARGET_DSN = "user:password@tcp(localhost:3306)/goalfymax_archive?parseTime=true"
)

使用方法

基本用法（保持原始UID）

go run main.go -project <project_id>

示例：

go run main.go -project 123

替换UID

go run main.go -project <project_id> -uid <new_uid>

示例：

go run main.go -project 123 -uid 456

自定义数据库连接

go run main.go -project 123 \
  -source "root:pass@tcp(source-host:3306)/goalfymax_prod?parseTime=true" \
  -target "root:pass@tcp(target-host:3306)/goalfymax_archive?parseTime=true"

编译后使用

# 编译
go build -o message-migrator

# 运行
./message-migrator -project 123
./message-migrator -project 123 -uid 456

参数说明

参数	必需	说明	示例
-project	是	要迁移的项目ID	-project 123
-uid	否	新的用户ID（不指定则使用原始UID）	-uid 456
-source	否	源数据库DSN（不指定则使用代码中的默认值）	-source "user:pass@tcp(host:3306)/db"
-target	否	目标数据库DSN（不指定则使用代码中的默认值）	-target "user:pass@tcp(host:3306)/db"

迁移流程

1. 连接数据库：连接到源数据库和目标数据库
2. 开启事务：在两个数据库上分别开启事务
3. 迁移主表：迁移 m_stream_messages，记录旧ID到新ID的映射
4. 迁移关联表：
   • 迁移 m_stream_contents，使用映射更新 main_message_id
   • 迁移 m_context_messages，使用映射更新 main_message_id
   • 迁移 m_task_messages，使用映射更新 main_message_id
5. 提交事务：所有数据迁移成功后提交事务

注意事项

⚠️ 重要提示：

1. 备份数据：在执行迁移前，请务必备份源数据库和目标数据库
2. 目标表存在：工具不会创建表，请确保目标数据库中已存在所有需要的表结构
3. 事务一致性：迁移过程使用事务，如果中途失败会自动回滚
4. ID映射：工具会自动处理 main_message_id 的映射关系，确保关联正确
5. UID替换：如果指定了 -uid 参数，所有表中的 uid 字段都会被替换为新值
6. 重复执行：请注意，重复执行相同的迁移命令可能会导致数据重复

日志输出

工具会输出详细的迁移日志：

2025/11/07 10:00:00 Starting migration for project_id=123
2025/11/07 10:00:00 Will replace UID with: 456
2025/11/07 10:00:01 Step 1: Migrating m_stream_messages...
2025/11/07 10:00:02   Migrated 150 stream messages
2025/11/07 10:00:02 Step 2: Migrating m_stream_contents...
2025/11/07 10:00:03   Migrated 300 stream contents
2025/11/07 10:00:03 Step 3: Migrating m_context_messages...
2025/11/07 10:00:04   Migrated 200 context messages
2025/11/07 10:00:04 Step 4: Migrating m_task_messages...
2025/11/07 10:00:05   Migrated 180 task messages
2025/11/07 10:00:05 Migration completed successfully!

错误处理

如果迁移过程中遇到错误：

• 事务会自动回滚，不会产生部分数据
• 错误信息会显示在日志中
• 检查数据库连接、权限和表结构是否正确

性能建议

对于大量数据的迁移：

1. 在非高峰期执行
2. 确保数据库有足够的临时空间
3. 可以考虑先迁移到测试环境验证
4. 监控数据库性能指标