Plausible Analytics升级至3.0.0版本时遇到的数据库迁移问题分析

在将自托管的Plausible Analytics从2.1.5版本升级到3.0.0版本过程中，部分用户遇到了数据库迁移问题。这个问题主要表现为应用程序启动时出现数据库列缺失错误，随后又出现列已存在的冲突。

问题现象

升级后启动Plausible容器时，系统报错显示teams表中缺少locked列。错误日志显示应用程序尝试查询一个不存在的locked列，导致启动失败。具体错误信息表明系统在执行团队查询时，期望teams表包含locked字段，但实际数据库结构中该字段尚未创建。

问题根源

通过分析数据库结构发现，teams表的创建语句确实不包含locked列。这属于典型的数据库迁移顺序问题，即应用程序代码已经更新为使用新字段，但相应的数据库迁移脚本尚未执行或执行顺序不正确。

在Plausible 3.0.0版本中，开发团队引入了对团队锁定功能的支持，这需要在teams表中添加locked列。然而，在某些升级场景下，数据库迁移脚本的执行顺序与应用程序启动流程出现了时序问题。

临时解决方案

遇到此问题的用户可以采取以下步骤解决：

1. 手动添加缺失的列：

ALTER TABLE teams ADD COLUMN locked bool DEFAULT false NOT NULL;

2. 如果添加后出现列已存在的错误，则需要删除该列并重新启动应用：

ALTER TABLE teams DROP COLUMN locked;

3. 正常重启Plausible服务，让系统自动完成正确的迁移流程

官方修复

Plausible开发团队已经意识到这个问题，并在3.0.1版本中修复了数据库迁移顺序问题。建议用户直接升级到3.0.1版本，以避免手动干预数据库结构。

经验总结

这个问题为我们在进行应用升级时提供了几点重要启示：

1. 数据库迁移脚本的执行顺序至关重要，特别是在添加新功能时
2. 应用代码与新数据库结构的兼容性需要仔细测试
3. 对于重要系统的升级，建议先在测试环境验证迁移过程
4. 保持关注项目方的发布说明和已知问题列表

对于使用Plausible Analytics的用户，建议在升级前备份数据库，并考虑在低峰期执行升级操作，以最小化潜在影响。