Immich项目PostgreSQL迁移脚本中的Schema硬编码问题分析

问题背景

在Immich项目v128.0版本的数据库迁移过程中，当用户使用独立PostgreSQL服务器并配置了专用schema(而非默认的public schema)时，迁移脚本会执行失败。这个问题源于迁移脚本中硬编码了对"public" schema的直接引用，导致在非public schema环境下无法正确执行。

技术细节分析

问题表现

迁移脚本在执行过程中尝试删除索引时，使用了完整的schema限定名称"public.IDX_users_audit_deleted_at_asc_user_id_asc"，而实际上在专用schema环境下，这些索引存在于用户指定的schema中，而非public schema中。这导致了如下错误：

QueryFailedError: index "IDX_users_audit_deleted_at_asc_user_id_asc" does not exist

影响范围

通过代码审查发现，该问题主要出现在以下两个迁移脚本中：

1. 1740595460866-UsersAuditUuidv7PrimaryKey.js文件中：
   • 硬编码引用了"public"."IDX_users_audit_deleted_at_asc_user_id_asc"
   • 硬编码引用了"public"."IDX_users_audit_deleted_at"

解决方案建议

对于直接引用数据库对象(如表、索引等)的情况，应该避免硬编码schema名称，而是使用相对路径或从数据库连接配置中获取当前schema。具体来说：

1. 对于索引删除操作，可以简化为：

   await queryRunner.query(`DROP INDEX "IDX_users_audit_deleted_at_asc_user_id_asc"`);
   

2. 保留必要的search_path设置，因为这是PostgreSQL向量扩展和地理距离计算所必需的：

   await queryRunner.query(`SET search_path TO "$user", public, vectors`);
   

最佳实践

对于数据库迁移脚本的编写，特别是在多schema环境下，建议遵循以下原则：

1. 避免硬编码schema名称：除非绝对必要，否则不应在SQL语句中硬编码schema名称。

2. 使用相对引用：让数据库根据当前search_path自动解析对象位置。

3. 明确区分必要和非必要的schema限定：

   • 对于数据库扩展功能(如pgvector)所需的search_path设置，可以保留
   • 对于普通数据库对象的操作，应使用相对引用

4. 测试覆盖：确保迁移脚本在多种schema配置下都能正常工作，包括：

   • 默认public schema
   • 自定义专用schema
   • 多schema混合环境

总结

Immich项目在数据库迁移脚本中硬编码public schema的问题虽然看似简单，但反映了数据库迁移脚本编写时需要特别注意的环境兼容性问题。通过遵循上述最佳实践，可以确保迁移脚本在各种数据库配置下都能可靠执行，为用户提供更平滑的升级体验。