CentOS 上 PostgreSQL 扩展插件使用教程

一 准备与环境确认

• 确认版本与路径：在数据库内执行 SELECT version(); 查看 PostgreSQL 主版本；在操作系统执行 which pg_config 与 pg_config --pgxs 确认开发工具链可用（编译插件需要）。
• 常见目录：数据目录通常为 /var/lib/pgsql/<版本>/data，配置文件为 postgresql.conf 与 pg_hba.conf。
• 权限与安全：操作前切换到 postgres 系统用户；远程访问需在 pg_hba.conf 放行网段并使用强认证；涉及重启需评估业务窗口。
• 插件生效范围：多数扩展以“数据库级”生效，需在目标库内执行创建；少数组件需服务器级预加载。
  以上准备与路径示例、以及“插件以数据库级生效”的说明，可参考典型安装与云数据库文档。

二 安装方式与步骤

• 方式一 RPM 包安装（推荐，适用于常见官方扩展）

  1. 安装对应版本的 PostgreSQL 官方 YUM 源（以 EL-7 为例）：
     yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
  2. 安装扩展对应的包（示例：PostGIS）并自动解决依赖：
     yum list | grep postgis
     yum install -y postgis
  3. 登录数据库，在需要的库内创建扩展：
     psql -U postgres -c “CREATE EXTENSION postgis;”
  4. 验证：
     psql -c “\dx”
     说明：RPM 安装会把扩展文件放入 PostgreSQL 目录，但要在数据库内通过 CREATE EXTENSION 才能真正加载到目标库。

• 方式二 源码编译安装（适用于官方仓库未收录或较新插件）

  1. 安装编译依赖（以 PostgreSQL 15 为例）：
     yum install -y postgresql15-devel

     如遇 llvm-toolset 依赖问题，可先安装 centos-release-scl-rh 再装 devel 包

  2. 准备插件源码并编译安装（示例：pgvector v0.5.1）：
     git clone --branch v0.5.1 https://github.com/pgvector/pgvector.git
     cd pgvector && make && make install
  3. 登录数据库，在目标库内创建扩展：
     psql -c “CREATE EXTENSION vector;”
  4. 验证：
     psql -c “SELECT * FROM pg_extension WHERE extname = ‘vector’;”
     说明：编译时常用 USE_PGXS=1 让 Makefile 自动通过 pg_config 找到头文件与库路径；部分插件可能还需服务器级预加载（见下一节）。

三 常用插件快速上手

• PostGIS（空间数据）

  • 安装：yum install -y postgis
  • 启用：CREATE EXTENSION postgis;（可按需 CREATE EXTENSION postgis_topology;）
  • 验证：\dx 能看到 postgis 条目。

• pgvector（向量相似检索）

  • 编译安装（见上节），在目标库：CREATE EXTENSION vector;
  • 测试：
    CREATE TABLE t (id bigserial PRIMARY KEY, vec vector(3));
    INSERT INTO t(vec) VALUES (‘[1,2,3]’), (‘[4,5,6]’);
    SELECT * FROM t ORDER BY vec <-> ‘[3,1,2]’ LIMIT 5; – L2 距离最近邻

• Citus（分布式表）

  • 安装扩展包（示例仓库为 citus72_10 对应 PG 10），并在 postgresql.conf 中预加载：
    echo “shared_preload_libraries = ‘citus’” | tee -a /var/lib/pgsql/10/data/postgresql.conf
    重启数据库后，在 coordinator 节点目标库：CREATE EXTENSION citus;
    添加 worker：SELECT master_add_node(‘192.168.99.101’, 5432);
    验证：SELECT * FROM master_get_active_worker_nodes();
  • 说明：Citus 属于“服务器级预加载 + 数据库内创建扩展”的典型组合。

四 管理与卸载

• 查看已安装扩展：
  • psql 元命令：\dx
  • SQL：SELECT * FROM pg_extension;
• 创建与删除：
  • 创建：CREATE EXTENSION ;（可指定 schema：CREATE EXTENSION SCHEMA ;）
  • 删除：DROP EXTENSION ;
  • 存在依赖时：DROP EXTENSION CASCADE;（会一并删除依赖对象）
• 云数据库 RDS 场景：部分云厂商提供封装函数（如 control_extension）用于创建/删除扩展，且插件为数据库级生效，需在目标库执行；请以对应云产品文档为准。

五 常见问题与排查

• 创建时报 “extension already exists”：先 DROP EXTENSION 或使用 CREATE EXTENSION IF NOT EXISTS。
• 删除时报依赖错误：使用 CASCADE 级联删除，或先清理依赖对象。
• 找不到扩展（CREATE EXTENSION 失败）：确认插件包已安装到操作系统、库文件路径正确，且当前数据库用户有权限；必要时检查插件是否需服务器级预加载（shared_preload_libraries）。
• 编译失败：确认已安装对应版本的 -devel 包，pg_config 在 PATH，必要时设置 PATH=/usr/pgsql-<版本>/bin:$PATH；某些平台需安装 SCL 源解决工具链依赖。
• 扩展不生效或找不到函数：确认在正确的数据库内创建了扩展，且搜索路径 search_path 包含扩展所在 schema。