Debian上PostgreSQL插件如何使用

Debian 上使用 PostgreSQL 插件的完整流程

一 环境准备与版本确认

• 更新索引并安装基础包：sudo apt update && sudo apt install postgresql postgresql-contrib。contrib 包提供不少常用扩展的脚本与工具。
• 确认本机 PostgreSQL 主版本：sudo -i -u postgres psql -c “SELECT version();”，输出类似 PostgreSQL 15.x，后续安装扩展时需匹配该主版本号。
• 进入数据库会话：sudo -i -u postgres psql。以上步骤完成后即可在目标数据库内创建扩展。

二 安装与启用扩展的常用方式

• 方式 A 通过 APT 安装并 CREATE EXTENSION
  1. 安装对应版本的扩展包（将版本号替换为你的实际版本，如 13、15）：
     sudo apt install postgresql-15-pg_stat_monitor
     sudo apt install postgresql-15-pgtrgm
  2. 在需要的数据库中启用：
     CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;
     CREATE EXTENSION IF NOT EXISTS pg_trgm;
  3. 验证：SELECT * FROM pg_extension;
     说明：部分扩展（如 timescaledb）可能需要额外配置或依赖，安装后按扩展文档执行 CREATE EXTENSION 或带 CASCADE 的选项。
• 方式 B 编译安装（适用于官方仓库未收录的扩展）
  1. 安装编译依赖与对应版本的 server-dev 包（示例为 9.6，请按实际版本调整）：
     sudo apt-get install -y build-essential postgresql-server-dev-9.6 …
  2. 获取源码、编译并安装（以 Decoderbufs 为例）：
     git clone https://github.com/debezium/postgres-decoderbufs.git
     cd postgres-decoderbufs && make && sudo make install
  3. 修改配置并重启（见下一节）。
• 方式 C 使用第三方扩展管理工具（可选）
  如 Pig 可简化多版本环境下的扩展安装与维护：pig ext list/info/install/remove/update/status。适合需要快速部署多扩展或镜像加速的场景。

三 配置与权限要点

• 共享预加载库 shared_preload_libraries
  某些扩展需在 postgresql.conf 中预加载（如逻辑解码插件），示例：
  shared_preload_libraries = ‘decoderbufs’
  修改后需重启数据库：sudo systemctl restart postgresql。
• 逻辑复制相关参数（使用 Decoderbufs 等逻辑解码时）
  wal_level = logical
  max_wal_senders = 8
  wal_keep_segments = 4
  max_replication_slots = 4
  并在 pg_hba.conf 为复制用户放行：
  local replication trust
  host replication 127.0.0.1/32 trust
  host replication ::1/128 trust
• 无需预加载的示例
  如调试扩展 pldebugger 在 PostgreSQL 15 上通常不需要配置 shared_preload_libraries，安装包后直接 CREATE EXTENSION 即可：
  sudo apt install postgresql-15-pldebugger
  CREATE EXTENSION pldbgapi;
• 其它扩展
  个别扩展可能要求修改 postgresql.conf 的专用参数，按扩展文档调整并在需要时重启。

四 常用扩展快速上手

• pg_trgm：用于模糊匹配与全文搜索
  安装：sudo apt install postgresql-15-pgtrgm
  启用：CREATE EXTENSION IF NOT EXISTS pg_trgm;
  用法示例：
  SELECT word_similarity(‘hello’, ‘helo’);
  CREATE INDEX ON t USING gin(col gin_trgm_ops);
• pg_stat_monitor：查询性能监控
  安装：sudo apt install postgresql-15-pgstatmonitor
  启用：CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;
  验证：SELECT * FROM pg_extension;
• Decoderbufs：逻辑解码输出 Protobuf，供 CDC 使用
  安装：编译安装（见第二节方式 B）
  配置：设置 shared_preload_libraries、wal_level=logical 等并重启
  验证与使用：
  SELECT * FROM pg_create_logical_replication_slot(‘decoderbufs_demo’, ‘decoderbufs’);
  INSERT INTO t(id) VALUES (1);
  SELECT data FROM pg_logical_slot_peek_changes(‘decoderbufs_demo’, NULL, NULL, ‘debug-mode’, ‘1’);
• pldebugger：在 15 上调试存储过程/函数
  安装：sudo apt install postgresql-15-pldebugger
  启用：CREATE EXTENSION pldbgapi;
  客户端（如 DBeaver）需安装调试插件并启用调试视图后，可对函数设置断点、单步执行。

五 常见问题与排查

• 扩展包未找到或版本不匹配
  确认 APT 源已启用且版本号一致（如 postgresql-15-xxx），必要时 apt update 或检查是否安装了 postgresql-contrib。
• 创建扩展时报“未找到扩展控制文件”
  多为扩展包未安装或安装到了其它 PostgreSQL 版本目录，核对版本并重新安装对应版本的扩展包。
• 逻辑解码不可用
  检查 shared_preload_libraries、wal_level、max_replication_slots 等参数与 pg_hba.conf 复制权限，修改后需重启。
• 修改配置未生效
  涉及 shared_preload_libraries、wal_level 等参数需重启；其它参数按扩展文档要求重载或重启。
• 客户端调试不可用
  确认数据库端已 CREATE EXTENSION pldbgapi，且客户端（如 DBeaver）已安装调试插件并启用调试工具栏。