From 14f350f21b1cab2bc67a84e08712faf632c1379d Mon Sep 17 00:00:00 2001
From: Yue Wang <1939455790@qq.com>
Date: Fri, 31 Jul 2026 10:57:10 +0800
Subject: [PATCH] docs: document PGroonga encoding requirement

---
 .../master/ecosystem_components/pgroonga.adoc   | 17 +++++++++++++++++
 .../master/ecosystem_components/pgroonga.adoc   | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
index 14727fe8..93f8a879 100644
--- a/CN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
+++ b/CN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
@@ -90,5 +90,22 @@ postgres=# select version();
 (1 row)
 ```
 
+== 编码兼容性
+
+PGroonga 依赖 https://groonga.org/docs/reference/api/util_8h.html#c.grn_encoding[Groonga 支持的字符编码]，其中不包含 GB18030。因此，在 GB18030 编码的数据库中创建 PGroonga 索引时，索引可能没有生成词元，并导致查询无法返回匹配结果。
+
+使用 PGroonga 的业务应创建 UTF-8 编码的数据库：
+
+[source,sql]
+----
+CREATE DATABASE search_db
+  WITH ENCODING 'UTF8'
+       LC_COLLATE 'C'
+       LC_CTYPE 'C'
+       TEMPLATE template0;
+----
+
+修改 Groonga 的运行时编码或重建索引不会改变数据库编码。已有数据需要迁移或重新导入 UTF-8 数据库，再创建 PGroonga 索引。
+
 == 使用
 关于PGroonga的使用，请参阅 https://pgroonga.github.io/tutorial[PGroonga官方文档]
diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
index 987f3242..6531f111 100644
--- a/EN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
+++ b/EN/modules/ROOT/pages/master/ecosystem_components/pgroonga.adoc
@@ -87,5 +87,22 @@ postgres=# select version();
 (1 row)
 ```
 
+== Encoding Compatibility
+
+PGroonga relies on https://groonga.org/docs/reference/api/util_8h.html#c.grn_encoding[Groonga's supported encodings], which do not include GB18030. A PGroonga index created in a GB18030-encoded database may therefore contain no tokens and return no matches.
+
+Create a UTF-8 database for workloads that use PGroonga:
+
+[source,sql]
+----
+CREATE DATABASE search_db
+  WITH ENCODING 'UTF8'
+       LC_COLLATE 'C'
+       LC_CTYPE 'C'
+       TEMPLATE template0;
+----
+
+Changing Groonga's runtime encoding or rebuilding the index does not change the database encoding. Existing data must be migrated or reloaded into a UTF-8 database before creating the PGroonga index.
+
 == Usage
 For PGroonga usage, please refer to the https://pgroonga.github.io/tutorial[PGroonga Official Documentation]