v3 -> v4 guide: “schema migrations are additive (new tables only)” is not accurate, and the prerequisite it depends on is undocumented

快速结论：Langfuse 官方 v3 升级到 v4 的文档中关于“schema migrations are additive (new tables only)”的描述不准确——v4.10.0 实际上会删除多个表、枚举类型，并且回滚到 v3 的前提（20241024_* 后台迁移必须完成）在文档中未提及。优先排查：升级前确认所有 20241024_* 迁移已经完成，并且不要在 dual 模式下直接回滚服务器。

适用环境：Langfuse v3 升级到 v4.10.0 及后续版本；Issue 中确认涉及 ClickHouse 和 PostgreSQL 双数据库环境，以及 Cloud Run / Kubernetes 滚动更新平台。

最快修复方案：暂无确认的一步修复方案。官方已在文档中澄清升级流程和前置条件（参见 langfuse/langfuse-docs#3589），但 Issue 作者建议在升级前执行检查 SQL 确认后台迁移完成。

注意事项：该问题涉及数据丢失风险，升级前务必验证迁移状态；回滚到 v3 在 dual 模式下已被证实不可行，需要另行规划降级方案。

问题场景

用户参照 Langfuse 官方“v3 升级到 v4”指南进行升级或回滚演练时，发现文档中关于“schema migrations are additive (new tables only)”的描述与实际迁移行为不符。实际场景包括：

在 dual 写入模式下进行回滚演练，v3 Web 容器启动失败。
升级后发现 20241024_* 后台迁移被删除，无法确认是否曾完整执行。
检查迁移文件时发现 v4.10.0 包含大量 DROP TABLE 和 DROP TYPE 语句。

报错原文

v3 -> v4 guide: "schema migrations are additive (new tables only)" is not accurate, and the prerequisite it depends on is undocumented

langfuse-web exits after 8s
error: no migration found for version 46: read down for version 46 .: file does not exist

-- The traces, observations and scores tables were superseded by their
-- ClickHouse counterparts in v3. Their contents were copied over by the
-- 20241024_* background migrations, which must have completed (on the latest
-- v3 release) before upgrading to v4.

原因分析

可能原因有三层：

文档描述不准确：官方指南称 v4 schema 迁移是“增量、只新增表”，但 v4.10.0 实际包含 DROP TABLE（event_log、project_environments、dataset_run_items、traces、observations、scores）和 DROP TYPE（ObservationType、ObservationLevel、ScoreSource）语句，并非“new tables only”。
关键前置条件未写入文档：迁移文件 20260723150000_drop_legacy_tracing_tables 的 SQL 注释中明确要求 20241024_* 后台迁移必须完成才能升级，但升级指南中完全没有提及这一前提。
回滚路径不可用：golang-migrate 在 v3 镜像中只识别到迁移版本 37，而 ClickHouse schema_migrations 记录为 46，导致 v3 Web 容器启动时找不到对应迁移文件而中止；且 v4 迁移会删除 background_migrations 表中的 20241024_* 记录，升级后无法追溯迁移是否曾不完整。

环境排查

确认 Langfuse 版本：v3 最新版、v4.10.0（或更高版本）。
确认数据库环境：ClickHouse 和 PostgreSQL 双数据库部署。
确认后台迁移状态：执行 SELECT name, finished_at FROM background_migrations WHERE name LIKE '20241024%'，检查是否有未完成的迁移。
确认部署平台：Cloud Run、Kubernetes（滚动更新）或 Docker Compose。
确认迁移工具：golang-migrate 版本为 v3 镜像内置的仅支持到版本 37。

解决步骤

升级前检查后台迁移状态——在升级到 v4 之前，先在 v3 环境执行以下 SQL，确认所有 20241024_* 及相关的 dataset_run_items / event_log 迁移都有非空 finished_at：
```
SELECT name, finished_at FROM background_migrations
WHERE name LIKE '20241024%' OR name LIKE '2025%dataset_run_items%'
   OR name LIKE '%event_log_to_blob_storage%';
```
如果存在 finished_at 为空的记录，先等待迁移完成或手动补跑，不要直接升级。
核实文档最新内容——官方已通过 langfuse/langfuse-docs#3589 更新升级指南，请查看最新文档（https://langfuse.com/docs/upgrade/v3-to-v4）确认前置条件如何描述。
如果已经升级且担心数据丢失——检查 ClickHouse 中 traces、observations、scores 表是否包含完整数据；由于 v4 迁移已删除 background_migrations 记录，无法通过该表追溯 20241024_* 迁移状态，需从 ClickHouse 数据本身判断。
如果发生回滚失败（error: no migration found for version 46）——注意该回滚方式已被证实不可行。需要规划替代方案，例如从备份恢复 v3 环境，或保留一个 v3 的旁路环境用于读取旧数据。
升级后验证迁移结果——确认新表结构正常，旧表（若仍存在）不再接收数据写入。