pg_fsql
支持 JSONB 驱动执行的递归 SQL 模板引擎
概览
| 扩展包名 | 版本 | 分类 | 许可证 | 语言 |
|---|---|---|---|---|
pg_fsql | 1.1.0 | UTIL | PostgreSQL | C |
| ID | 扩展名 | Bin | Lib | Load | Create | Trust | Reloc | 模式 |
|---|---|---|---|---|---|---|---|---|
| 4110 | pg_fsql | 否 | 是 | 否 | 是 | 否 | 否 | fsql |
| 相关扩展 | plpgsql plpgsql pg_readme schedoc |
|---|
Release tag 1.1.0 still ships extension SQL version 1.0; shared_preload_libraries is optional and only needed for session-start GUC availability.
版本
| 类型 | 仓库 | 版本 | PG 大版本 | 包名 | 依赖 |
|---|---|---|---|---|---|
| EXT | PIGSTY | 1.1.0 | 1817161514 | pg_fsql | plpgsql |
| RPM | PIGSTY | 1.1.0 | 1817161514 | pg_fsql_$v | - |
| DEB | PIGSTY | 1.1.0 | 1817161514 | postgresql-$v-pg-fsql | - |
构建
您可以使用 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 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
用法
来源：README, control file
pg_fsql 是 PostgreSQL 的递归 SQL 模板引擎。它把基于 C 的占位符渲染、PL/pgSQL 模板执行、层级化模板组合，以及可选的 SPI plan cache 结合在一起。上游项目强调它不需要 superuser 权限。
快速开始
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"}');
SELECT fsql.render('user_count', '{"status":"active"}');
目录表
扩展会安装两个主要目录表：
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 并返回jsonbref，重定向到另一个模板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)，预览渲染后的 SQLfsql.tree(path)，查看层级结构fsql.explain(path, data)，跟踪展开过程fsql.validate()，检查模板fsql.depends_on(path)，查看依赖关系fsql.clear_cache()，释放缓存的 SPI plans
层级模板示例
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。control file 当前仍声明 SQL extension version 1.0，尽管包任务跟踪的 release 为 1.1.0。仓库没有额外的官方 release notes，因此用户侧行为仍应以当前 README 为准。