pg_fsql

概览

shared_preload_libraries is optional and only needed for session-start GUC availability.

版本

构建

您可以使用 pig build 命令构建 pg_fsql 扩展的 RPM / DEB 包：

pig build pkg pg_fsql         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_fsql 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install pg_fsql;          # 当前活跃 PG 版本安装

pig ext install -y pg_fsql -v 18  # PG 18
pig ext install -y pg_fsql -v 17  # PG 17
pig ext install -y pg_fsql -v 16  # PG 16
pig ext install -y pg_fsql -v 15  # PG 15
pig ext install -y pg_fsql -v 14  # PG 14

dnf install -y pg_fsql_18       # PG 18
dnf install -y pg_fsql_17       # PG 17
dnf install -y pg_fsql_16       # PG 16
dnf install -y pg_fsql_15       # PG 15
dnf install -y pg_fsql_14       # PG 14

apt install -y postgresql-18-pg-fsql   # PG 18
apt install -y postgresql-17-pg-fsql   # PG 17
apt install -y postgresql-16-pg-fsql   # PG 16
apt install -y postgresql-15-pg-fsql   # PG 15
apt install -y postgresql-14-pg-fsql   # PG 14

创建扩展：

CREATE EXTENSION pg_fsql CASCADE;  -- 依赖: plpgsql

用法

语法：

CREATE EXTENSION pg_fsql;
INSERT INTO fsql.templates (path, cmd, body)
VALUES ('user_count', 'exec',
        'SELECT jsonb_build_object(''total'', count(*)) FROM users WHERE status = {d[status]!r}');
SELECT fsql.run('user_count', '{"status":"active"}');

来源：README

pg_fsql 是 PostgreSQL 的递归 SQL 模板引擎。它将 C 级占位符渲染、PL/pgSQL 模板执行、层级化模板组合以及可选的 SPI 计划缓存结合在一起。上游强调它不需要超级用户权限。

核心对象

扩展会安装两个主要目录表：

fsql.templates (
    path varchar(500) primary key,
    cmd varchar(50),
    body text,
    defaults text,
    cached boolean default false
)

fsql.params (
    key_param varchar(255) primary key,
    type_param varchar(255) not null
)

path 采用点号分隔，用于定义模板层级。

模板命令

README 记录了六种命令类型：

• exec：执行 SQL 并返回 jsonb
• ref：重定向到另一个模板
• if：选择子分支
• exec_tpl：执行 SQL 后将结果重新渲染为模板
• map：将子模板收集为 JSON 对象
• NULL：插入到父模板中的文本片段

占位符

渲染器支持以下占位符：

• {d[key]}
• {d[key]!r}，对应 quote_literal
• {d[key]!j}，对应 JSONB 字面量
• {d[key]!i}，对应 quote_identifier

特殊键 _self 会注入完整的输入 JSON 对象。

公共 API

上游公开函数包括：

• fsql.run(path, data, debug)：执行模板树
• fsql.render(path, data)：预览渲染后的 SQL
• fsql.tree(path)：查看层级结构
• fsql.explain(path, data)：跟踪展开过程
• fsql.validate()：检查模板
• fsql.depends_on(path)：查看依赖关系
• fsql.clear_cache()：释放缓存的 SPI 计划

示例

INSERT INTO fsql.templates (path, cmd, body) VALUES
    ('report', 'exec',
     'SELECT jsonb_build_object(''data'', array_agg(row_to_json(t)))
      FROM (SELECT {d[cols]} FROM {d[src]} {d[where]}) t'),
    ('report.cols',  NULL, 'id, name, email'),
    ('report.src',   NULL, 'customers'),
    ('report.where', NULL, 'WHERE city = {d[city]!r}');

SELECT fsql.run('report', '{"city":"Moscow"}');
SELECT fsql.render('report', '{"city":"Moscow"}');

需求

README 列出的要求包括 PostgreSQL 14+、plpgsql，以及 gcc、make 和 PostgreSQL server development headers 等标准构建依赖。