pgvecto.rs 从0.1.1升级到0.2.0版本的技术指南

升级背景与挑战

pgvecto.rs作为PostgreSQL的向量数据库插件，在0.2.0版本中引入了多项改进。然而，从0.1.x版本升级到0.2.0版本时，用户可能会遇到一些技术挑战，特别是在非Docker环境下的裸机或虚拟机部署场景中。

升级过程中的关键问题

在升级过程中，用户主要遇到了以下几个技术难点：

1. 版本识别问题：从源代码构建时，Cargo.toml文件中默认的版本号为0.0.0，需要手动修改为0.2.0才能正确安装。

2. 依赖版本冲突：pgrx依赖版本需要与系统安装的版本匹配，否则会导致构建失败。

3. 升级路径缺失：直接使用ALTER EXTENSION命令升级时，系统报告没有从0.1.1到0.2.0的升级路径。

4. 扩展删除困难：尝试删除旧版本扩展时，由于依赖关系导致操作失败。

解决方案与最佳实践

1. 准备工作

在开始升级前，建议先备份数据库，特别是包含向量数据的表。对于Immich用户，这包括asset_faces和smart_search表中的数据。

2. 正确安装新版本

从源代码构建时，需要特别注意以下两点：

• 修改Cargo.toml中的版本号为0.2.0
• 确保pgrx依赖版本与系统安装版本一致

构建命令示例：

cargo pgrx install -c /usr/lib/postgresql14/bin/pg_config --sudo --release

3. 升级策略选择

根据实际测试，推荐采用以下两种升级策略之一：

策略一：完整升级路径

1. 确保升级脚本vectors--0.1.11--0.2.0.sql已放置在PostgreSQL的extension目录中
2. 执行以下SQL命令序列：

UPDATE pg_catalog.pg_extension SET extversion = '0.1.11' WHERE extname = 'vectors';
UPDATE pg_catalog.pg_extension SET extrelocatable = true WHERE extname = 'vectors';
CREATE SCHEMA IF NOT EXISTS vectors;
ALTER EXTENSION vectors SET SCHEMA vectors;
UPDATE pg_catalog.pg_extension SET extrelocatable = false WHERE extname = 'vectors';
ALTER EXTENSION vectors UPDATE TO '0.2.0';
SELECT pgvectors_upgrade();

策略二：全新安装（适用于可接受数据丢失的场景）

1. 删除旧版扩展：

DROP EXTENSION vectors CASCADE;

2. 停止PostgreSQL服务
3. 安装新版vectors.so库文件
4. 启动PostgreSQL服务
5. 创建新扩展：

CREATE EXTENSION vectors;

4. 权限处理

升级后，可能需要为数据库用户授予超级用户权限才能创建向量索引：

ALTER ROLE immich WITH superuser;

5. 重建索引与数据

对于Immich用户，升级后需要：

1. 清空相关表数据
2. 重新添加向量列
3. 创建新的向量索引
4. 重新运行面部识别和智能搜索的学习过程

技术建议与注意事项

1. 版本兼容性：确保PostgreSQL版本与pgvecto.rs版本兼容，目前支持PostgreSQL 14。

2. 构建环境：建议使用Rust稳定版(1.76+)进行构建，虽然夜间版也能工作。

3. 文件位置：关键文件包括：

   • vectors.so：PostgreSQL的lib目录
   • vectors.control和升级脚本：PostgreSQL的extension目录

4. 生产环境建议：对于生产环境，建议先在测试环境验证升级过程，特别是评估数据丢失的影响。

未来版本改进方向

根据用户反馈，pgvecto.rs团队计划在后续版本中：

1. 提供包含二进制库和所有升级文件的tar包
2. 完善非Debian系统的安装指南
3. 改进升级脚本的打包和部署机制
4. 增强版本兼容性检查

通过遵循本文指南，用户应该能够顺利完成pgvecto.rs从0.1.x到0.2.0版本的升级过程。对于特定应用场景(如Immich)，可能需要额外的数据处理步骤，建议参考应用的具体文档。