Umami项目数据库迁移问题分析与解决方案

问题背景

Umami作为一款开源网站分析工具，在最新版本升级过程中出现了数据库迁移失败的问题。该问题主要影响MySQL和PostgreSQL数据库用户，表现为在执行05_add_visit_id迁移脚本时出现错误。

错误现象

用户在执行数据库迁移时会遇到以下两类典型错误：

1. MySQL/MariaDB环境：报错显示FUNCTION BIN_TO_UUID does not exist，这是由于MySQL 8.0以下版本或MariaDB不支持该函数导致的。

2. PostgreSQL环境：报错显示迁移失败，且后续出现"Something went wrong"错误，这是由于大表数据迁移超时或资源不足导致的。

技术分析

MySQL/MariaDB问题根源

MySQL 8.0引入了UUID支持功能，包括BIN_TO_UUID和UUID_TO_BIN函数。然而：

1. MySQL 8.0以下版本不支持这些函数
2. MariaDB虽然与MySQL兼容，但并未实现这些特定函数

PostgreSQL问题根源

PostgreSQL迁移失败的主要原因包括：

1. 大表数据迁移操作耗时过长，超出默认超时设置
2. 资源不足导致迁移过程中断
3. 迁移失败后未正确处理，导致后续操作受阻

解决方案

针对MySQL/MariaDB的解决方案

对于使用MySQL或MariaDB的用户，可以采用以下替代SQL脚本：

-- 添加visit_id列
ALTER TABLE website_event ADD COLUMN visit_id VARCHAR(36) NULL;

-- 使用兼容方式生成UUID并更新数据
UPDATE website_event we
JOIN (
    SELECT DISTINCT
        s.session_id,
        s.visit_time,
        LOWER(CONCAT(
            HEX(SUBSTR(MD5(RAND()), 1, 4)), '-',
            HEX(SUBSTR(MD5(RAND()), 1, 2)), '-4',
            SUBSTR(HEX(SUBSTR(MD5(RAND()), 1, 2)), 2, 3), '-',
            CONCAT(HEX(FLOOR(ASCII(SUBSTR(MD5(RAND()), 1, 1)) / 64)+8),SUBSTR(HEX(SUBSTR(MD5(RAND()), 1, 2)), 2, 3)), '-',
            HEX(SUBSTR(MD5(RAND()), 1, 6))
        )) AS uuid
    FROM (
        SELECT DISTINCT session_id,
            DATE_FORMAT(created_at, '%Y-%m-%d %H:00:00') visit_time
        FROM website_event
    ) s
) a ON we.session_id = a.session_id AND DATE_FORMAT(we.created_at, '%Y-%m-%d %H:00:00') = a.visit_time
SET we.visit_id = a.uuid
WHERE we.visit_id IS NULL;

-- 修改列属性为非空
ALTER TABLE website_event MODIFY visit_id VARCHAR(36) NOT NULL;

-- 创建索引
CREATE INDEX website_event_visit_id_idx ON website_event(visit_id);
CREATE INDEX website_event_website_id_visit_id_created_at_idx ON website_event(website_id, visit_id, created_at);

针对PostgreSQL的解决方案

对于PostgreSQL用户，特别是数据量较大的情况，建议采用分批处理的方式：

1. 基础迁移脚本：

-- 添加visit_id列
ALTER TABLE "website_event" ADD COLUMN "visit_id" UUID NULL;

-- 更新数据(大数据量时建议分批执行)
UPDATE "website_event" we
SET visit_id = a.uuid
FROM (SELECT DISTINCT
        s.session_id,
        s.visit_time,
        gen_random_uuid() uuid
    FROM (SELECT DISTINCT session_id,
            date_trunc('hour', created_at) visit_time
        FROM "website_event") s) a
WHERE we.session_id = a.session_id 
    and date_trunc('hour', we.created_at) = a.visit_time;

-- 修改列属性
ALTER TABLE "website_event" ALTER COLUMN "visit_id" SET NOT NULL;

-- 创建索引
CREATE INDEX "website_event_visit_id_idx" ON "website_event"("visit_id");
CREATE INDEX "website_event_website_id_visit_id_created_at_idx" ON "website_event"("website_id", "visit_id", "created_at");

2. 大数据量分批处理方案：

对于数据量特别大的表，可以创建一个进度跟踪表，然后使用脚本分批处理：

-- 创建进度跟踪表
CREATE TABLE public.update_progress (
    last_processed_time timestamptz NULL,
    rows_updated int4 NULL
);

然后使用编程语言(Python/Ruby等)编写脚本分批执行更新操作，每批处理一定数量的记录，并保存处理进度。

迁移后处理

无论使用哪种解决方案，执行完迁移脚本后都需要标记迁移为已完成：

UPDATE _prisma_migrations
SET finished_at = NOW(), logs = NULL, applied_steps_count = 1 
WHERE migration_name = '05_add_visit_id';

或者使用Prisma命令行工具：

npx prisma migrate resolve --applied "05_add_visit_id"

最佳实践建议

1. 升级前备份：执行任何数据库迁移前，务必进行完整数据库备份
2. 测试环境验证：先在测试环境验证迁移过程，特别是数据量大的情况
3. 维护窗口：对于生产环境，选择低峰期执行迁移
4. 资源监控：迁移过程中监控数据库资源使用情况
5. 回滚计划：准备好在迁移失败时的回滚方案

总结

Umami的这次数据库迁移问题主要源于数据库版本兼容性和大数据量处理两方面。通过理解问题本质并采用适当的解决方案，用户可以顺利完成升级。对于未来版本，建议项目团队考虑更友好的迁移策略，特别是对于大数据量环境的支持。