pgroonga

概览

Requires Groonga >= 15.1.7, MessagePack and xxHash.

版本

构建

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

pig build pkg pgroonga         # 构建 RPM / DEB 包

安装

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

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

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

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

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

dnf install -y pgroonga_18       # PG 18
dnf install -y pgroonga_17       # PG 17
dnf install -y pgroonga_16       # PG 16
dnf install -y pgroonga_15       # PG 15
dnf install -y pgroonga_14       # PG 14

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

创建扩展：

CREATE EXTENSION pgroonga;

用法

来源：

• Release 4.1.0

• Control

• Version 4.0.9 SQL

• Version 4.0.9 control

• Official tutorial

• Version 4.0.9 release

• Upgrade guidance

pgroonga 4.1.0 使用 Groonga 索引实现多语言全文检索，安装 pgroonga 访问方法及 SQL 操作符，普通使用不需要共享预加载。

核心流程

安装兼容的 PGroonga 与 Groonga 库后，由管理员创建扩展：

CREATE EXTENSION pgroonga;
CREATE TABLE search_notes (id bigint PRIMARY KEY, body text);
CREATE INDEX search_notes_body_idx ON search_notes USING pgroonga (body);
INSERT INTO search_notes VALUES (1, 'PostgreSQL supports full text search');
SELECT id, body FROM search_notes WHERE body &@ 'PostgreSQL';
SELECT id, body, pgroonga_score(tableoid, ctid) AS score
FROM search_notes WHERE body &@~ 'PostgreSQL OR Groonga'
ORDER BY score DESC;

主要对象

• &@ 匹配关键词；&@~ 接受 Groonga 查询语法。受支持的 LIKE/ILIKE 查询也可使用索引，并在需要时复查结果。
• pgroonga_score(tableoid, ctid) 取得搜索得分；按得分排序时，应确认实际执行了预期索引计划。
• pgroonga_highlight_html() 与 pgroonga_query_extract_keywords() 生成高亮结果；pgroonga_snippet_html() 提供关键词附近的文本。
• 4.0.9 新增 pgroonga_physical_table_names(partitioned_index, prefix)，以文本数组返回 Groonga 命令参数，标识各分区索引背后的物理表。该版本也开始为 PGroonga 扫描累加 pg_stat_user_indexes.idx_scan。

维护与权限

4.0.9 控制文件未声明受信任安装或可迁移模式，不应假定普通用户能安装扩展或将其移到其他模式。索引创建和查询仍需相应的表权限。应使扩展及 Groonga 库与目标 PostgreSQL 构建匹配，并在替换二进制前遵循上游升级说明。

PGroonga 除表数据外还管理派生索引文件，应据此规划磁盘容量和备份恢复流程。适用时使用 REINDEX 修复索引。独立的 pgroonga_database 模块用于恢复损坏的内部 Groonga 数据库，正常搜索并不需要它。在生产环境中，不要为了强制使用索引而全局关闭顺序扫描。

Pigsty 运行库兼容性

当前 Pigsty EL8 和 EL9 软件包与 PostGIS Raster 存在已确认的共存限制，影响 x86_64、aarch64 两种架构及 PostgreSQL 14–18。Groonga 使用 Arrow 22，本轮 GDAL/Raster 依赖栈则在 EL8 使用 Arrow 8、在 EL9 使用 Arrow 9。将两套依赖加载到同一个 PostgreSQL 后端可能导致崩溃；SQL 查询成功并不能证明后端正常退出。

改变加载顺序不是完整修复：EL9 aarch64 的自动会话预加载仍出现后端退出崩溃。在验证兼容依赖组合前，应避免在同一个后端启用两套依赖，必要时隔离使用。本轮测试的 EL10 和 Debian/Ubuntu 组合未复现该故障，但不能据此推广到任意其他依赖版本。这是 Pigsty 软件包依赖栈的边界，不是上游要求普通 PGroonga 搜索必须预加载。

MeCab 分词还需要匹配的 Groonga 分词插件和词典。仅安装 PostgreSQL 扩展并不会提供全部可选分词器；在建立指定分词器的索引前，应确认它可用。

4.1.0 版本

4.1.0 修复其他会话在 CREATE INDEX 提交前执行 VACUUM/ANALYZE 导致索引数据被移除的问题，已经受影响的索引可能需要 REINDEX。直接调用 Groonga 时，搭配 Groonga 16.1.3 或更新版本可在 post_filter 中使用 pgroonga_tuple_is_alive。这次源码发布不改变另行记录的 Pigsty 依赖栈限制。