OpenProject 数据库编码变更实战：解决 OpenProject 15 迁移中的 ICU 排序规则（collation）错误

OpenProject 数据库编码变更实战解决 OpenProject 15 迁移中的 ICU 排序规则collation错误【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject本文是一份面向 OpenProject 系统管理员的数据库编码变更操作指南核心目标是解决从旧版本升级到 OpenProject 15 时迁移脚本尝试创建 ICU 排序规则collation而当前数据库编码不支持所导致的迁移失败问题。读完本文后你将掌握一套完整的「备份 → 新建 Unicode 编码数据库 → 恢复 → 切换连接配置」的标准化迁移流程并能结合仓库源码理解该错误产生的根本原因与校验方式。一、问题背景为什么迁移会要求创建 ICU 排序规则OpenProject 15 的数据库迁移流程中会通过 PostgreSQL 的 ICUInternational Components for Unicode能力创建一个名为versions_name的排序规则用于对versions表版本/里程碑的name字段进行自然排序即按数字大小而不是按字符字典序排序。在仓库中该排序规则的创建逻辑位于 db/migrate/extensions/version_name_collation.rb其核心 SQL 为CREATE COLLATION IF NOT EXISTS versions_name (provider icu, locale und-u-kn-true)provider icu表示由 ICU 提供排序能力这要求数据库服务器所运行的 PostgreSQL 版本与编译环境支持 ICUlocale und-u-kn-true中的kn扩展开启了数字感知numeric ordering排序这正是为了让Version 2排在Version 10之前。而versions表的name列在定义时就绑定了这个排序规则见 db/migrate/tables/versions.rbt.string :name, default: , null: false, collation: versions_name该排序规则的创建被注册在聚合迁移 db/migrate/1000016_aggregated_migrations.rb 中与BtreeGist、PgTrgm、Unaccent等扩展一起在迁移时执行。为什么会失败当数据库本身的编码encoding不兼容 ICU 排序规则的创建要求时例如某些非 Unicode 编码的数据库CREATE COLLATION语句会报错。迁移框架 db/migrate/extensions/base.rb 会捕获该错误并输出如下提示后中止迁移ERROR: Failed to create an ICU collation with current database encoding. You need to change the database encoding before proceeding.由于 PostgreSQL 不允许在同一个数据库中直接修改编码唯一的正确做法就是新建一个使用 Unicode 编码的数据库将数据整体迁移过去再让 OpenProject 指向新数据库。本文后续步骤正是围绕这条路径展开。二、前置条件在执行以下操作前请确认满足两点数据库权限拥有 OpenProject 所连接数据库服务器上创建数据库所需的凭据与权限服务器 Shell 访问能够登录 OpenProject 所在服务器执行命令。此外本文所有步骤均假设你使用的是 OpenProject 自带的openproject管理命令适用于基于 Linux 的软件包安装方式。若你使用的是 Docker 部署命令入口会有所不同本文步骤中的openproject命令形式可能不适用。三、步骤 1创建数据库备份dump在执行任何变更前务必先为现有数据库创建一份完整备份。使用内置命令openproject run backup执行成功后注意记录输出中Generating database backup之后显示的备份文件路径其格式通常为/var/db/openproject/backup/postgresql-dump-DATE_TIME_DIGITS.pgdump该路径将用于后续的恢复操作。此备份命令对应的底层实现可在 lib/tasks/backup.rake 中查看它基于pg_dump生成数据库逻辑备份。关于备份策略的更完整介绍可参考 Backing up your OpenProject installation。四、步骤 2创建使用 Unicode 编码的新数据库4.1 获取当前数据库连接 URL先通过 openproject 命令读取当前配置中的DATABASE_URLopenproject config:get DATABASE_URL输出应形如postgres://USERNAME:PASSWORDHOST:PORT/DATABASE请记下该 URL后续步骤会反复用到其中各组成部分。4.2 方式一使用 psql 创建新数据库在决定新数据库名称后本文示例使用openproject-unicode执行psql DATABASE_URL -c CREATE DATABASE NEW_DATABASE_NAME ENCODING UNICODE例如psql postgres://openproject:hard-passwordsome-host:5432/openproject \ -c CREATE DATABASE openproject-unicode ENCODING UNICODE关于CREATE DATABASE的更多可选参数如LC_COLLATE、LC_CTYPE、TEMPLATE等可查阅你所使用 PostgreSQL 版本的官方sql-createdatabase文档。4.3 方式二使用 createdb 命令如果你的环境中更方便使用命令行工具createdb可以以数据库超级用户身份执行su postgres -c createdb -E UNICODE -O dbusernamer openproject_backup其中-E UNICODE等价于--encodingUNICODE指定新数据库编码为 Unicode即 UTF-8-O dbusernamer等价于--owner指定新数据库的所有者通常应设置为 OpenProject 连接数据库所用的用户名openproject_backup为示例新数据库名可自行替换。createdb的完整参数说明同样可参考对应 PostgreSQL 版本的官方app-createdb文档。官方建议为获得最大兼容性请始终使用 UnicodeUTF-8编码来创建新数据库。这是 OpenProject 迁移脚本能够正常创建 ICU 排序规则的前提。五、步骤 3将备份恢复到新数据库首先基于第 4.1 步获取的旧连接 URL 推导出新数据库的连接 URL只需将其中最后的数据库名替换为新建的数据库名即可。例如旧 URL 为postgres://openproject:hard-passwordsome-host:5432/openproject新数据库名为openproject-unicode则新 URL 为postgres://openproject:hard-passwordsome-host:5432/openproject-unicode随后使用pg_restore将第 1 步生成的 dump 文件恢复到新数据库pg_restore -d NEW_DATABASE_URL PATH_TO_THE_DATABASE_DUMP例如pg_restore -d postgres://openproject:hard-passwordsome-host:5432/openproject-unicode \ /var/db/openproject/backup/postgresql-dump-20240101000000.pgdumppg_restore会读取自定义格式的 dump 并重建全部表结构、数据与索引。恢复过程的更完整说明可参考 Restoring an OpenProject backup。六、步骤 4让 OpenProject 使用新数据库将新数据库的连接 URL 写入 OpenProject 配置openproject config:set DATABASE_URLNEW_DATABASE_URL例如openproject config:set DATABASE_URLpostgres://openproject:hard-passwordsome-host:5432/openproject-unicode设置完成后需要重启 OpenProject 服务使配置生效具体重启方式取决于你的部署形态可参考 控制 OpenProject 服务 相关文档。之后即可重新执行升级/迁移命令此时迁移脚本中的CREATE COLLATION IF NOT EXISTS versions_name (provider icu, locale und-u-kn-true)应在 Unicode 编码的数据库上正常执行。关于DATABASE_URL配置项的更多细节如自定义数据库服务器的连接参数、SSL 选项等可参考 Configuring a custom database server。七、验证与注意事项完成切换后建议做如下验证确认新数据库编码连接新数据库执行\l或查询pg_database确认其Encoding列为 UnicodeUTF8确认排序规则存在执行SELECT collname FROM pg_collation WHERE collname versions_name;应能看到该 ICU 排序规则确认数据完整抽查工作包、版本、项目等核心表中的记录数量与迁移前一致确认应用可用重新运行迁移命令直至成功并登录 OpenProject 验证版本Release列表的排序行为符合预期数字感知排序。需要特别留意的是备份是安全底线第 1 步的 dump 是唯一可用于回滚的介质在确认新数据库完全正常之前不要删除新旧数据库并存切换配置后旧数据库并不会被自动清理可先保留一段时间以便回滚确认稳定后再手动清理编码不可原地修改PostgreSQL 不支持在已有数据库上直接更改编码因此新建 迁移是唯一稳妥路径这也是本文整套流程存在的意义权限最小化psql/createdb/pg_restore均需要相应数据库权限建议全程使用具有建库权限的专用账户而非随意提升权限。八、相关文档索引备份 OpenProject 安装openproject run backup的完整说明恢复 OpenProject 备份pg_restore恢复流程的细节配置自定义数据库服务器DATABASE_URL配置项详解迁移相关错误信息来源db/migrate/extensions/version_name_collation.rb、db/migrate/extensions/base.rb、db/migrate/tables/versions.rb【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考