Plausible社区版数据库升级中的列缺失问题解析

问题背景

在使用Plausible社区版从v2.1.5升级到v3.0.1版本时，系统报错提示缺少scroll_depth列。这是一个典型的数据库迁移过程中出现的列缺失问题，涉及到ClickHouse数据库表结构的变更。

错误现象

升级过程中，系统抛出以下错误信息：

** (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表，可以看到所有迁移记录都已标记为完成，包括应该添加scroll_depth列的迁移(20241216133031)。然而，实际检查imported_pages表结构时，确实没有发现scroll_depth列的存在。

技术分析

这种情况通常发生在以下场景：

1. 迁移脚本执行成功，但实际表结构变更未完成
2. 数据库事务未正确提交
3. 迁移标记被错误记录

在ClickHouse这类分布式数据库中，由于其特殊的存储引擎和复制机制，偶尔会出现元数据与实际表结构不一致的情况。

解决方案

针对这个问题，可以采取以下步骤解决：

1. 通过ClickHouse CLI连接到数据库
2. 手动执行ALTER TABLE语句添加缺失的列：

ALTER TABLE plausible_events_db.imported_pages ADD COLUMN scroll_depth UInt8 DEFAULT 255

预防措施

为避免类似问题，建议：

1. 在执行重要升级前备份数据库
2. 在开发环境先测试升级流程
3. 监控迁移过程中的错误日志
4. 考虑使用数据库迁移工具的验证功能

总结

数据库迁移是系统升级中的关键环节，特别是在使用ClickHouse这类特殊数据库时，需要特别注意表结构变更的验证。通过理解错误信息、检查实际表结构和迁移记录，可以有效定位和解决这类问题。