groonga/pgroonga

Pgroonga Docker 镜像使用介绍

简介

Pgroonga 是 PostgreSQL 的一款高性能全文搜索扩展，支持中文、日文等多语言分词，查询速度快且功能丰富。这个 Docker 镜像封装了 PostgreSQL 和 Pgroonga，帮你省去手动编译安装的麻烦，快速搭建带全文搜索能力的数据库环境。

前提条件

使用前需确保已安装 Docker。可通过以下命令检查 Docker 是否安装：

bash
docker --version  # 输出 Docker 版本信息即表示安装成功

使用步骤

1. 拉取镜像

默认拉取最新版本（包含最新 PostgreSQL 和 Pgroonga）：

bash
docker pull groonga/pgroonga

如需指定版本（如 PostgreSQL 16 + Pgroonga 3.2.0），可带标签拉取：

bash
docker pull groonga/pgroonga:16-3.2.0  # 格式：{PostgreSQL版本}-{Pgroonga版本}

2. 运行容器

启动容器时，需配置端口映射（访问数据库）、数据持久化（避免容器删除后数据丢失）和必要的环境变量（如数据库密码）。

基础命令示例（适合测试，数据不持久化）：

bash
docker run -d \
  --name my-pgroonga \
  -p 5432:5432 \  # 本地端口:容器内端口（PostgreSQL默认端口5432）
  -e POSTGRES_PASSWORD=mysecretpassword \  # 设置数据库密码（必填）
  groonga/pgroonga

生产环境建议（数据持久化，指定用户和数据库名）：

bash
docker run -d \
  --name my-pgroonga \
  -p 5432:5432 \
  -v /path/on/host:/var/lib/postgresql/data \  # 本地目录挂载到容器数据目录（持久化数据）
  -e POSTGRES_USER=myuser \  # 自定义数据库用户（默认postgres）
  -e POSTGRES_DB=mydb \  # 自定义数据库名（默认与用户名相同）
  -e POSTGRES_PASSWORD=StrongPassword123! \  # 强密码（生产环境必须）
  groonga/pgroonga:16-3.2.0  # 指定稳定版本

3. 连接数据库

容器启动后，用 psql 工具连接（需先安装 PostgreSQL 客户端，或用容器内的 psql）：

方法1：本地客户端连接

bash
psql -h localhost -p 5432 -U myuser -d mydb

输入密码后即可进入 PostgreSQL 命令行。

方法2：进入容器内连接

bash
docker exec -it my-pgroonga psql -U myuser -d mydb

配置选项

环境变量

启动容器时可通过 -e 设置以下常用环境变量：

• POSTGRES_USER：数据库用户名（默认 postgres）
• POSTGRES_PASSWORD：用户密码（必填，无默认值）
• POSTGRES_DB：默认数据库名（默认与 POSTGRES_USER 相同）
• PGROONGA_VERSION：指定 Pgroonga 版本（镜像标签已包含时无需设置）
• POSTGRES_INITDB_ARGS：初始化数据库时的额外参数（如 --encoding=UTF8）

挂载配置文件

如需自定义 PostgreSQL 配置（如修改 shared_buffers），可挂载本地 postgresql.conf 到容器：

bash
docker run -d \
  --name my-pgroonga \
  -v /path/on/host/postgresql.conf:/var/lib/postgresql/data/postgresql.conf \  # 挂载配置文件
  -e POSTGRES_PASSWORD=mysecretpassword \
  groonga/pgroonga

示例：测试全文搜索

以下是一个简单的全文搜索测试流程，在 PostgreSQL 命令行中执行：

1. 创建测试表并启用 Pgroonga：

sql
CREATE TABLE articles (
  id SERIAL PRIMARY KEY,
  title text,
  content text
);

-- 添加 Pgroonga 索引（支持全文搜索）
CREATE INDEX pgroonga_articles_index ON articles USING pgroonga (title, content);

2. 插入测试数据：

sql
INSERT INTO articles (title, content) VALUES 
  ('PostgreSQL 全文搜索', 'Pgroonga 让 PostgreSQL 支持高效中文分词'),
  ('Docker 部署技巧', '用 Docker 快速搭建 Pgroonga 环境，省去编译步骤');

3. 执行全文搜索（搜索包含“中文”的内容）：

sql
SELECT * FROM articles WHERE pgroonga_match_text(content, '中文');

结果会返回第一条数据，验证全文搜索功能正常。

注意事项

1. 数据持久化：务必通过 -v 挂载数据卷，否则容器删除后数据会丢失。
2. 版本选择：生产环境建议指定镜像标签（如 16-3.2.0），避免自动更新到不兼容版本。
3. 安全配置：不要使用弱密码，生产环境建议限制端口访问（如只允许内网 IP 连接 5432 端口）。
4. 日志查看：通过 docker logs my-pgroonga 查看容器运行日志，排查启动或连接问题。

通过以上步骤，你可以快速上手 Pgroonga Docker 镜像，搭建支持全文搜索的 PostgreSQL 环境。更多细节可参考 GitHub 仓库。