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

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

2025-05-08 19:54:35作者:翟萌耘Ralph

问题背景

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_UUIDUUID_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");
  1. 大数据量分批处理方案

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

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

登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
23
6
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
225
2.27 K
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
9
1
flutter_flutterflutter_flutter
暂无简介
Dart
526
116
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
988
585
Cangjie-ExamplesCangjie-Examples
本仓将收集和展示高质量的仓颉示例代码,欢迎大家投稿,让全世界看到您的妙趣设计,也让更多人通过您的编码理解和喜爱仓颉语言。
Cangjie
351
1.42 K
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer(第 2 版)》、《程序员面试金典(第 6 版)》题解
Java
61
17
GLM-4.6GLM-4.6
GLM-4.6在GLM-4.5基础上全面升级:200K超长上下文窗口支持复杂任务,代码性能大幅提升,前端页面生成更优。推理能力增强且支持工具调用,智能体表现更出色,写作风格更贴合人类偏好。八项公开基准测试显示其全面超越GLM-4.5,比肩DeepSeek-V3.1-Terminus等国内外领先模型。【此简介由AI生成】
Jinja
47
0
giteagitea
喝着茶写代码!最易用的自托管一站式代码托管平台,包含Git托管,代码审查,团队协作,软件包和CI/CD。
Go
17
0
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
JavaScript
212
288