PG18之插件使用大全（简单用例）

一，pg_buffercache

1.1 编译安装模块

bash 复制代码

# 编译 contrib/pg_buffercache
su - root
cd contrib/pg_buffercache
make
sudo make install

#验证
su - postgres
ls $(pg_config --sharedir)/extension/pg_buffercache*
# 应看到 .control 和 .sql 文件

1.2 数据库加载模块

bash 复制代码

-- 连接到目标数据库
\c your_database

-- PG 18 支持更细粒度权限，普通用户也可创建（如果有权限）
CREATE EXTENSION IF NOT EXISTS pg_buffercache;

-- 查看版本（应为 1.4及以上）
SELECT extversion FROM pg_extension WHERE extname = 'pg_buffercache';

1.3 表结构解释

bash 复制代码

-- 查看 pg_buffercache 视图结构
\d pg_buffercache

-- 输出（PG 15-18 通用）：
-- View "pg_catalog.pg_buffercache"
--        Column         |   Type   | 说明
-- ----------------------+----------+-------------------------------------------
--  bufferid             | integer  | 缓冲区编号（0 ~ shared_buffers-1）
--  relfilenode          | oid      | 表/索引的文件节点号（物理文件标识）
--  reltablespace        | oid      | 表空间 OID
--  reldatabase          | oid      | 数据库 OID
--  relforknumber        | smallint | 文件分支号（0=主数据,1=FSM,2=VM,3=INIT）
--  relblocknumber       | bigint   | 在文件中的块号（8KB 为单位）
--  isdirty              | boolean  | 是否为脏页（内存与磁盘不一致）
--  usagecount           | smallint | Clock Sweep 使用计数（0-5）
--  pinning_backends     | integer  | 当前引用该缓冲区的后端进程数（refcount）

--以下是pg18的
postgres=# \d pg_buffercache
                  View "public.pg_buffercache"
+------------------+----------+-----------+----------+---------+
|      Column      |   Type   | Collation | Nullable | Default |
+------------------+----------+-----------+----------+---------+
| bufferid         | integer  |           |          |         |
| relfilenode      | oid      |           |          |         |
| reltablespace    | oid      |           |          |         |
| reldatabase      | oid      |           |          |         |
| relforknumber    | smallint |           |          |         |
| relblocknumber   | bigint   |           |          |         |
| isdirty          | boolean  |           |          |         |
| usagecount       | smallint |           |          |         |
| pinning_backends | integer  |           |          |         |
+------------------+----------+-----------+----------+---------+

1.4 相关sql查询

sql 复制代码

--统计基础查询
SELECT 
    -- 【缓冲区标识】
    bufferid,                    -- 缓冲区唯一编号（数组下标）
    
    -- 【物理位置】
    relfilenode,                 -- 文件节点（对应 pg_class.relfilenode）
    reltablespace,               -- 表空间（默认 1663 为 pg_default）
    reldatabase,                 -- 数据库 OID（0 为共享表）
    relforknumber,               -- 分支：0=main, 1=fsm, 2=vm, 3=init
    relblocknumber,              -- 文件内块偏移（*8KB=字节位置）
    
    -- 【状态标志】
    isdirty,                     -- 脏页标记（true=需刷盘, false=干净）
    usagecount,                  -- 热度计数（Clock Sweep用, 0-5）
    pinning_backends             -- 引用计数（>0表示正被使用，不可淘汰）
    
FROM pg_buffercache
WHERE relfilenode IS NOT NULL   -- 过滤未使用的缓冲区
LIMIT 10;


--脏页分析查询
SELECT 
    -- 【表信息】
    coalesce(c.relname, 'unknown') as table_name,
    case c.relkind
        when 'r' then '表'
        when 'i' then '索引'
        when 'S' then '序列'
        when 't' then 'TOAST'
        else c.relkind::text
    end as object_type,
    
    -- 【脏页统计】
    count(*) as total_pages,                    -- 该对象总缓存页数
    count(*) FILTER (WHERE b.isdirty) as dirty_pages,  -- 脏页数
    round(100.0 * count(*) FILTER (WHERE b.isdirty) / count(*), 2) as dirty_pct,  -- 脏页比例
    
    -- 【热度分析】
    avg(b.usagecount) as avg_heat,              -- 平均热度
    max(b.usagecount) as max_heat,                -- 最高热度
    sum(b.pinning_backends) as total_pins,        -- 总引用数
    
    -- 【大小计算】
    pg_size_pretty(count(*) * 8192) as cache_size,           -- 缓存总大小
    pg_size_pretty(count(*) FILTER (WHERE b.isdirty) * 8192) as dirty_size  -- 脏数据大小
    
FROM pg_buffercache b
LEFT JOIN pg_class c ON b.relfilenode = c.relfilenode
WHERE b.relfilenode IS NOT NULL
GROUP BY c.relname, c.relkind
HAVING count(*) FILTER (WHERE b.isdirty) > 0      -- 只显示有脏页的对象
ORDER BY dirty_pages DESC;


--Clock Sweep 分析（空闲页识别）
SELECT 
    case
        when b.relfilenode IS NULL then '完全空闲（未初始化）'
        when b.pinning_backends > 0 then '使用中（被锁定）'
        when b.isdirty and b.usagecount = 0 then '待刷脏（可淘汰）'
        when b.isdirty then '脏页（需刷盘）'
        when b.usagecount = 0 then '干净空闲（立即可用）'
        else '干净使用中'
    end as buffer_status,
    
    count(*) as buffer_count,
    pg_size_pretty(count(*) * 8192) as total_size,
    min(b.bufferid) as min_bufid,
    max(b.bufferid) as max_bufid,
    avg(b.usagecount) as avg_usage,
    sum(b.pinning_backends) as total_refs
    
FROM pg_buffercache b
GROUP BY 1
ORDER BY 
    -- 关键：用 bool_or() 或 min()/max() 聚合原始条件
    min(case
        when b.relfilenode IS NULL then 1
        when b.pinning_backends > 0 then 5
        when b.isdirty and b.usagecount = 0 then 3
        when b.isdirty then 4
        when b.usagecount = 0 then 2
        else 6
    end);


--关联表名查询
SELECT 
    b.bufferid,                  -- 缓冲区ID
    
    -- 【对象信息】
    n.nspname as schema_name,    -- 模式名（如 public）
    c.relname as table_name,     -- 表/索引名
    c.relkind as object_type,    -- 对象类型：r=表,i=索引,S=序列,t=TOAST
    
    -- 【物理位置】
    b.relfilenode,               -- 文件节点
    b.relforknumber,             -- 分支号
    b.relblocknumber,            -- 块号
    
    -- 【状态】
    b.isdirty,                   -- 是否脏页
    b.usagecount,                -- 使用计数（热度）
    b.pinning_backends,          -- 引用数（并发访问数）
    
    -- 【计算字段】
    pg_size_pretty(8192::bigint) as page_size,           -- 显式转 bigint
    pg_size_pretty((b.usagecount * 8192)::bigint) as heat_score  -- 整体转 bigint
    
FROM pg_buffercache b
LEFT JOIN pg_class c ON b.relfilenode = c.relfilenode
LEFT JOIN pg_namespace n ON c.relnamespace = n.oid
WHERE b.relfilenode IS NOT NULL
  AND c.relname IS NOT NULL
ORDER BY b.usagecount DESC, b.isdirty DESC
LIMIT 20;

F.1. amcheck ------ 验证表与索引一致性

作用：检查 B-tree 索引的逻辑一致性，可用于发现损坏。
启用：CREATE EXTENSION amcheck;
示例：

sql

复制代码

-- 检查索引的所有页
SELECT bt_index_check('index_name');
-- 深入检查（可能锁定）
SELECT bt_index_parent_check('index_name');

F.2. auth_delay ------ 认证失败时延迟

作用：认证失败后增加延迟，防止暴力破解。
启用：预加载库，配置参数。
配置（postgresql.conf）：

ini

复制代码

shared_preload_libraries = 'auth_delay'
auth_delay.milliseconds = 500   # 延迟毫秒数

F.3. auto_explain ------ 记录慢查询执行计划

作用：自动将执行时间超过阈值的查询计划记录到日志。
启用：预加载库。
配置：

ini

复制代码

shared_preload_libraries = 'auto_explain'
auto_explain.log_min_duration = '2s'
auto_explain.log_analyze = on

F.4. basebackup_to_shell ------ 示例 pg_basebackup shell 模块

作用：允许 pg_basebackup 将备份通过 shell 命令处理（如压缩、加密）。
启用：预加载库。
用法：在 pg_basebackup 命令中使用 --target=shell。

F.5. basic_archive ------ 示例 WAL 归档模块

作用：提供一个简单的 WAL 归档模块模板。
启用：预加载库，配置 archive_command 等。
示例：需自定义实现。

F.6. bloom ------ 布鲁姆过滤器索引

作用：支持等值查询的组合过滤，适合多列等值查询。
启用：CREATE EXTENSION bloom;
示例：

sql

复制代码

CREATE TABLE t (c1 int, c2 text, c3 int);
CREATE INDEX t_bloom ON t USING bloom (c1, c2, c3) WITH (length=80);
SELECT * FROM t WHERE c1 = 10 AND c2 = 'xxx';

F.7. btree_gin ------ GIN 索引支持 B-tree 操作符

作用：允许在 GIN 索引上使用 B-tree 操作符（=, <, > 等）。
启用：CREATE EXTENSION btree_gin;
示例：

sql

复制代码

CREATE TABLE t (a int, b text);
CREATE INDEX t_gin ON t USING gin (a, b);
SELECT * FROM t WHERE a = 1 AND b LIKE '%abc%';

F.8. btree_gist ------ GiST 索引支持 B-tree 操作符

作用：允许在 GiST 索引上使用 B-tree 操作符，用于排他约束等。
启用：CREATE EXTENSION btree_gist;
示例：

sql

复制代码

CREATE TABLE t (room int, during tsrange);
CREATE INDEX t_gist ON t USING gist (room, during);
-- 防止同一房间同一时间段冲突
ALTER TABLE t ADD EXCLUDE USING gist (room WITH =, during WITH &&);

F.9. citext ------ 大小写不敏感的文本类型

作用：提供 citext 类型，比较时忽略大小写。
启用：CREATE EXTENSION citext;
示例：

sql

复制代码

CREATE TABLE users (name citext);
INSERT INTO users VALUES ('Alice');
SELECT * FROM users WHERE name = 'ALICE';  -- 返回 Alice

F.10. cube ------ 多维立方体数据类型

作用：存储多维点或区间，支持距离运算。
启用：CREATE EXTENSION cube;
示例：

sql

复制代码

CREATE TABLE points (p cube);
INSERT INTO points VALUES ('(1,2)'), ('(3,4)');
SELECT cube_distance(p, '(1,2)') FROM points;

F.11. dblink ------ 远程数据库连接

作用：在数据库内执行远程 SQL。
启用：CREATE EXTENSION dblink;
示例：

sql

复制代码

-- 建立持久连接
SELECT dblink_connect('myconn', 'dbname=otherdb');
-- 查询远程表
SELECT * FROM dblink('myconn', 'SELECT id, name FROM users') AS t(id int, name text);

F.12. dict_int ------ 全文搜索整数词典

作用：将整数作为可搜索词处理（忽略非整数）。
启用：CREATE EXTENSION dict_int;
用法：在文本搜索配置中使用：

sql

复制代码

CREATE TEXT SEARCH DICTIONARY intdict (TEMPLATE = intdict);

F.13. dict_xsyn ------ 同义词词典

作用：将一组同义词映射为同一词。
启用：CREATE EXTENSION dict_xsyn;
配置：需提供同义词文件。

F.14. earthdistance ------ 地球距离计算

作用：计算球面上两点距离（基于 cube 或点）。
启用：CREATE EXTENSION earthdistance;
示例：

sql

复制代码

SELECT ll_to_earth(40.7, -74.0) <@> ll_to_earth(34.05, -118.25) AS distance;

F.15. file_fdw ------ 访问服务器文件系统

作用：将外部文件（如 CSV）当作表查询。
启用：CREATE EXTENSION file_fdw;
示例：

sql

复制代码

CREATE SERVER file_server FOREIGN DATA WRAPPER file_fdw;
CREATE FOREIGN TABLE csv_import (id int, name text) SERVER file_server
OPTIONS (filename '/path/to/file.csv', format 'csv');

F.16. fuzzystrmatch ------ 模糊匹配算法

作用：提供 Soundex、Levenshtein、Metaphone 等函数。
启用：CREATE EXTENSION fuzzystrmatch;
示例：

sql

复制代码

SELECT levenshtein('kitten', 'sitting');  -- 3
SELECT soundex('hello'), soundex('halo');  -- 相同

F.17. hstore ------ 键值对存储

作用：存储一组键值对。
启用：CREATE EXTENSION hstore;
示例：

sql

复制代码

CREATE TABLE t (id int, kv hstore);
INSERT INTO t VALUES (1, '"a"=>"1", "b"=>"2"');
SELECT kv -> 'a' FROM t;

F.18. intagg ------ 整数聚合器

作用：将整数列聚合为数组或字符串。
启用：CREATE EXTENSION intagg;
示例：

sql

复制代码

SELECT group_concat(id) FROM (VALUES (1),(2),(3)) AS t(id);  -- 返回 {1,2,3}

F.19. intarray ------ 整数数组增强

作用：提供整数数组的快速操作和索引。
启用：CREATE EXTENSION intarray;
示例：

sql

复制代码

SELECT ARRAY[1,2,3] && ARRAY[2,4];  -- true
CREATE INDEX idx ON t USING gin (arr gin__int_ops);

F.20. isn ------ 国际标准编号类型

作用：支持 ISBN、ISSN、UPC 等编号类型，带校验。
启用：CREATE EXTENSION isn;
示例：

sql

复制代码

CREATE TABLE books (isbn ISBN13);
INSERT INTO books VALUES ('978-0-393-04002-9');

F.21. lo ------ 大对象管理

作用：提供触发器自动管理大对象引用。
启用：CREATE EXTENSION lo;
示例：创建触发器，删除行时自动删除关联的大对象。

F.22. ltree ------ 树形路径类型

作用：存储标签路径，支持层次查询。
启用：CREATE EXTENSION ltree;
示例：

sql

复制代码

CREATE TABLE tree (path ltree);
INSERT INTO tree VALUES ('Top.Child.GrandChild');
SELECT * FROM tree WHERE path @> 'Top.Child';

F.23. pageinspect ------ 底层页面检查

作用：查看数据页、索引页的原始内容。
启用：CREATE EXTENSION pageinspect;
示例：

sql

复制代码

SELECT * FROM bt_page_items('my_index', 1);
SELECT * FROM heap_page_items(get_raw_page('my_table', 0));

F.24. passwordcheck ------ 密码强度校验

作用：在 CREATE ROLE 或 ALTER ROLE 时检查密码强度。
启用：预加载库。
配置：shared_preload_libraries = 'passwordcheck'，无需额外 SQL。

F.25. pg_buffercache ------ 共享缓冲区状态

作用：查看哪些表/索引页在内存中。
启用：CREATE EXTENSION pg_buffercache;
示例：

sql

复制代码

SELECT c.relname, count(*) AS buffers
FROM pg_buffercache b JOIN pg_class c ON b.relfilenode = pg_relation_filenode(c.oid)
GROUP BY c.relname;

F.26. pgcrypto ------ 加密函数

作用：提供哈希、加密、PGP 等功能。
启用：CREATE EXTENSION pgcrypto;
示例：

sql

复制代码

SELECT crypt('mypassword', gen_salt('bf'));   -- 生成 bcrypt 哈希
SELECT digest('message', 'sha256');

F.27. pg_freespacemap ------ 空闲空间映射

作用：查看每个页面的空闲空间。
启用：CREATE EXTENSION pg_freespacemap;
示例：

sql

复制代码

SELECT * FROM pg_freespace('my_table');

F.28. pg_logicalinspect ------ 逻辑解码组件检查

作用：查看逻辑解码状态。
启用：CREATE EXTENSION pg_logicalinspect;
示例：

sql

复制代码

SELECT * FROM pg_logical_slot_get_changes('slot_name', NULL, NULL);

F.29. pg_overexplain ------ 更详细的 EXPLAIN

作用：输出 EXPLAIN 中隐藏的细节（如范围表）。
启用：CREATE EXTENSION pg_overexplain;
示例：

sql

复制代码

EXPLAIN (DEBUG) SELECT * FROM t;   -- 输出额外信息

F.30. pg_prewarm ------ 预加载表到缓存

作用：将指定表或索引加载到共享缓冲区。
启用：CREATE EXTENSION pg_prewarm;
示例：

sql

复制代码

SELECT pg_prewarm('my_table', 'main', 'buffer');

F.31. pgrowlocks ------ 行级锁信息

作用：显示表上当前的行锁情况。
启用：CREATE EXTENSION pgrowlocks;
示例：

sql

复制代码

SELECT * FROM pgrowlocks('my_table');

F.32. pg_stat_statements ------ SQL 统计

作用：记录 SQL 的执行统计。
启用：预加载 + CREATE EXTENSION。
示例：

sql

复制代码

SELECT query, calls, total_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC;

F.33. pgstattuple ------ 元组级统计

作用：获取表和索引的物理统计信息（死元组比例等）。
启用：CREATE EXTENSION pgstattuple;
示例：

sql

复制代码

SELECT * FROM pgstattuple('my_table');
SELECT * FROM pgstatindex('my_index');

F.34. pg_surgery ------ 低级数据手术

作用：强制删除或修复损坏的元组（紧急修复）。
启用：CREATE EXTENSION pg_surgery;
示例：

sql

复制代码

SELECT heap_force_kill('my_table', ARRAY['(0,1)']);   -- 杀死指定元组

F.35. pg_trgm ------ 三元组相似度

作用：文本相似度计算及 LIKE/ILIKE 索引加速。
启用：CREATE EXTENSION pg_trgm;
示例：

sql

复制代码

SELECT similarity('word', 'wodr');   -- 相似度
CREATE INDEX trgm_idx ON t USING gin (col gin_trgm_ops);
SELECT * FROM t WHERE col LIKE '%abc%';   -- 使用索引

F.36. pg_visibility ------ 可见性映射检查

作用：查看表的可见性映射和页面可见性。
启用：CREATE EXTENSION pg_visibility;
示例：

sql

复制代码

SELECT * FROM pg_visibility_map('my_table');
SELECT * FROM pg_visibility('my_table', 0);

F.37. pg_walinspect ------ WAL 检查

作用：检查 WAL 日志内容（v15+）。
启用：CREATE EXTENSION pg_walinspect;
示例：

sql

复制代码

SELECT * FROM pg_get_wal_records_info('0/3000000', '0/4000000');

F.38. postgres_fdw ------ 远程 PostgreSQL 外部数据包装器

作用：访问远程 PostgreSQL 服务器。
启用：CREATE EXTENSION postgres_fdw;
示例：

sql

复制代码

CREATE SERVER remote FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '...', dbname '...');
CREATE USER MAPPING FOR current_user SERVER remote OPTIONS (user '...', password '...');
CREATE FOREIGN TABLE remote_t (id int) SERVER remote OPTIONS (table_name 'local_t');

F.39. seg ------ 线段/区间类型

作用：存储浮点数区间，支持包含、重叠等操作。
启用：CREATE EXTENSION seg;
示例：

sql

复制代码

CREATE TABLE t (range seg);
INSERT INTO t VALUES ('1.0 .. 2.5');
SELECT * FROM t WHERE range @> 2.0;

F.40. sepgsql ------ SELinux 强制访问控制

作用：基于 SELinux 的 MAC 安全模块。
启用：预加载库 + 操作系统配置。
示例：需 SELinux 策略支持，不提供简单 SQL 示例。

F.41. spi ------ 服务器编程接口示例

作用：包含 refint（引用完整性）、autoinc（自增）、insert_username、moddatetime 等触发器函数。
启用：对每个子模块 CREATE EXTENSION（如 CREATE EXTENSION refint;）。
示例（refint）：

sql

复制代码

CREATE TABLE child (id int, parent_id int);
CREATE TRIGGER fk_check BEFORE INSERT OR UPDATE ON child
FOR EACH ROW EXECUTE FUNCTION check_foreign_key(1, 'parent', 'id');

F.42. sslinfo ------ SSL 连接信息

作用：获取当前 SSL 连接信息。
启用：CREATE EXTENSION sslinfo;
示例：

sql

复制代码

SELECT ssl_cipher(), ssl_client_cert();

F.43. tablefunc ------ 交叉表等表函数

作用：提供 crosstab、normal_rand 等函数。
启用：CREATE EXTENSION tablefunc;
示例：

sql

复制代码

SELECT * FROM crosstab(
  'SELECT rowid, category, value FROM data ORDER BY 1,2',
  'SELECT DISTINCT category FROM data ORDER BY 1'
) AS ct(rowid text, cat1 text, cat2 text);

F.44. tcn ------ 触发变更通知

作用：表变化时发送 NOTIFY 消息。
启用：CREATE EXTENSION tcn;
示例：

sql

复制代码

CREATE TABLE t (id int);
CREATE TRIGGER tcn_trig AFTER INSERT OR UPDATE OR DELETE ON t
FOR EACH ROW EXECUTE FUNCTION triggered_change_notification();
-- 之后执行 DML 会发出 NOTIFY

F.45. test_decoding ------ 逻辑解码输出插件示例

作用：测试逻辑解码的 SQL 输出。
启用：无需扩展，直接使用逻辑复制槽。
示例：

sql

复制代码

SELECT pg_create_logical_replication_slot('test_slot', 'test_decoding');
SELECT pg_logical_slot_get_changes('test_slot', NULL, NULL);

F.46. tsm_system_rows ------ 按行数采样

作用：TABLESAMPLE 方法，返回固定行数。
启用：CREATE EXTENSION tsm_system_rows;
示例：

sql

复制代码

SELECT * FROM my_table TABLESAMPLE SYSTEM_ROWS(100);

F.47. tsm_system_time ------ 按时间采样

作用：TABLESAMPLE 方法，限制采样时间（毫秒）。
启用：CREATE EXTENSION tsm_system_time;
示例：

sql

复制代码

SELECT * FROM my_table TABLESAMPLE SYSTEM_TIME(1000);

F.48. unaccent ------ 移除重音符号的字典

作用：用于文本搜索，去除重音。
启用：CREATE EXTENSION unaccent;
示例：

sql

复制代码

SELECT unaccent('élève');  -- 'eleve'
CREATE TEXT SEARCH DICTIONARY mydict (TEMPLATE = unaccent);

F.49. uuid-ossp ------ UUID 生成器

作用：生成 UUID（v1, v3, v4, v5）。
启用：CREATE EXTENSION "uuid-ossp";
示例：

sql

复制代码

SELECT uuid_generate_v4();
SELECT uuid_generate_v5(uuid_ns_url(), 'https://example.com');

F.50. xml2 ------ XPath 和 XSLT 支持

作用：提供 XPath 查询和 XSLT 转换函数（部分功能已被核心 XML 函数取代）。
启用：CREATE EXTENSION xml2;
示例：

sql

复制代码

SELECT xpath('/book/title', '<book><title>My Book</title></book>');

以上每个模块均可通过上述示例快速体验其功能。对于需要预加载的模块，请记得修改 postgresql.conf 并重启数据库。对于 SQL 扩展，直接执行 CREATE EXTENSION 即可。