Wakapi项目MySQL迁移失败问题分析与解决

问题背景

在使用Wakapi 2.13.0版本进行数据库迁移时，系统报错显示无法创建或修改没有主键的表。错误信息明确指出，当MySQL系统变量sql_require_primary_key被设置时，所有表都必须包含主键。这一限制是为了避免在基于行的复制环境中可能出现的性能问题。

问题分析

错误发生在执行名为"20221028-fix_heartbeats_time_user_idx"的迁移脚本时。虽然最初报告指向了heartbeats表，但经过深入检查发现，实际存在问题的表是durations表。

durations表结构显示它确实缺少主键定义，仅有一个基于user_id和time字段的普通索引。这在MySQL默认配置下是可以接受的，但在启用了sql_require_primary_key严格模式的MySQL环境中会导致迁移失败。

技术细节

MySQL从8.0版本开始引入了sql_require_primary_key系统变量，该变量默认为OFF。当设置为ON时，MySQL会强制要求：

1. 所有新创建的表必须包含主键
2. 任何表结构修改操作都不能移除现有主键
3. 任何ALTER TABLE操作都必须保持主键存在

这一限制主要针对使用基于行的复制(RBR)的MySQL集群环境，因为无主键表在这种环境下可能导致严重的性能问题。

解决方案

针对这一问题，开发者可以考虑以下几种解决方案：

1. 修改MySQL配置：如果环境允许，可以临时或永久地将sql_require_primary_key设置为OFF。但需要注意，这可能会影响复制性能。

2. 为durations表添加主键：最规范的解决方案是为表添加适当的主键。考虑到durations表的使用场景，可以将(user_id, time)组合设为主键。

3. 升级Wakapi版本：最新版本(2.13.3)可能已经解决了这一问题，建议用户升级到最新稳定版。

最佳实践建议

对于使用Wakapi的生产环境，特别是部署在云服务提供商MySQL实例上的情况，建议：

1. 在部署前检查MySQL的严格模式设置
2. 考虑使用具有明确主键的表结构设计
3. 保持Wakapi版本更新，以获取最新的兼容性修复
4. 对于云数据库服务，提前了解提供商对MySQL配置的特殊要求

这一案例也提醒开发者，在数据库设计时应考虑不同环境下的兼容性问题，特别是当应用需要部署在各种云服务提供商的托管数据库上时。