Plausible社区版升级过程中缺失scroll_depth列问题解析

问题背景

在使用Plausible社区版进行版本升级时（从v2.1.5升级到v3.0.1），系统报错提示无法找到scroll_depth列。该错误导致升级过程中断，即使回退到旧版本也无法解决。

错误详情

系统在执行数据库迁移时抛出以下错误：

(Ch.Error) Code: 10. DB::Exception: Wrong column name. Cannot find column `scroll_depth` to drop. (NOT_FOUND_COLUMN_IN_BLOCK)

这表明系统尝试删除一个名为scroll_depth的列，但该列在数据库中并不存在。

根本原因分析

通过检查schema_migrations表和表结构，发现以下关键信息：

1. 迁移记录显示20241216133031号迁移（添加scroll_depth列到imported_pages表）已经执行完成
2. 但实际检查imported_pages表结构时，该列并不存在
3. 这表明迁移标记为已完成，但实际表结构变更未成功应用

解决方案

要解决此问题，需要手动添加缺失的列：

1. 进入ClickHouse命令行界面
2. 执行以下SQL命令：

ALTER TABLE plausible_events_db.imported_pages ADD COLUMN scroll_depth UInt8 DEFAULT 255

技术细节

• scroll_depth列的数据类型为UInt8（无符号8位整数）
• 默认值设置为255（可能表示未记录滚动深度）
• 该列用于记录用户在页面上的滚动深度百分比

预防措施

为避免类似问题，建议：

1. 在执行重要升级前备份数据库
2. 检查迁移脚本的执行情况与实际表结构是否一致
3. 考虑使用事务性迁移确保数据一致性

总结

数据库迁移过程中的不一致状态可能导致升级失败。通过手动修复表结构可以解决此类问题，但更重要的是理解迁移机制并采取预防措施。对于Plausible这类分析系统，确保数据结构的完整性对统计准确性至关重要。