将XWiki MariaDB表从latin1转utf8mb4遇行过大错误的解决咨询

问题背景 #

将XWiki从v7.0.1升级至v13.10.9时，在测试环境（MariaDB v10.3/10.9）执行字符集转换SQL，activitystream_events等表出现行大小超限错误：

SQL Error [1118] [42000]: (conn=14) Row size too large. The maximum row size for the used table type, not counting BLOBs, is 65535. This includes storage overhead, check the manual. You have to change some columns to TEXT or BLOBs

原表存在多个varchar(2000)列，utf8mb4字符集下每个字符占4字节，导致非BLOB/TEXT列总字节数超过InnoDB 65535的限制。

1. 行大小超限问题的解决方案 #

方案一：将大VARCHAR列转为TEXT类型（推荐） #

TEXT类型的存储不计入InnoDB的行大小限制，是最稳妥的解决方式。先修改表中占用空间大的列类型，再执行字符集转换：

-- 先修改大varchar列为TEXT
ALTER TABLE `xwiki`.`activitystream_events`
MODIFY COLUMN `ase_url` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_title` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_body` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_param1` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_param2` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_param3` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_param4` TEXT DEFAULT NULL,
MODIFY COLUMN `ase_param5` TEXT DEFAULT NULL;

-- 再执行字符集转换
ALTER TABLE `xwiki`.`activitystream_events`
CONVERT TO CHARACTER SET utf8mb4 COLLATE 'utf8mb4_unicode_ci';

其他出现相同错误的表，可参照此方式，将对应大varchar列转为TEXT后再转字符集。

方案二：临时关闭InnoDB严格模式（不推荐） #

通过修改配置关闭innodb_strict_mode可绕过检查，但可能导致数据截断或后续兼容性问题，仅作为临时测试使用：

SET GLOBAL innodb_strict_mode = OFF;

执行完字符集转换后建议重新开启该模式。

方案三：缩减不必要的VARCHAR列长度（谨慎操作） #

若部分大varchar列实际存储数据远小于定义长度，可适当缩减列长度（如确认ase_stream无需255字节可改为100），但需提前验证业务数据，避免数据截断。

2. XWiki数据库升级与字符集转换的通用实践 #

遵循官方逐步升级流程 #

XWiki跨大版本升级（如7.x→13.x）不能直接跳跃，必须按主版本依次升级（7.0.1→7.x最新→8.x→…→13.10.9）。新版本XWiki启动时会自动执行Hibernate迁移脚本，完成表结构的增量更新，直接跨版本升级会导致迁移脚本执行失败，数据库结构不兼容。

优先完成结构升级，再处理字符集 #

先按官方步骤完成XWiki版本升级，让系统自动完成表结构调整（部分大varchar列可能已被官方脚本转为TEXT），之后再统一执行字符集转换操作，避免手动修改与官方迁移冲突。

全量备份前置 #

所有数据库操作前，必须对测试环境和生产环境做全量备份，确保操作失败可快速回滚。

避免随意手动修改表结构 #

除非官方文档明确允许，否则不要手动修改表结构，依赖XWiki自带的迁移机制可保证后续版本升级的兼容性，手动修改可能导致后续迁移脚本执行异常。

内容的提问来源于stack exchange，提问作者James