Skip to content

Commit 4d165de

Browse files
committed
docs(4.1): state ivorysql.conf.sample coverage (4 of 15 GUCs)
ivorysql.conf.sample is what initdb turns into ivorysql.conf on an Oracle-mode cluster, and it is the only list of ivorysql.* parameters a reader meets on the installation path. It shows four of them: three commented examples (ivorysql.listen_addresses, ivorysql.port, ivorysql.identifier_case_switch) and one active line (ivorysql.enable_emptystring_to_NULL). The other eleven are registered in src/backend/utils/misc/ivy_guc.c and documented nowhere: "git grep -i 'conf\.sample'" over the whole v5.6 branch returns no hits, so nothing states how much of the parameter set the sample covers or where the rest are described. Seven of the eleven also carry GUC_NO_SHOW_ALL, so they are absent from SHOW ALL and from the pg_settings view as well (8 rows for ivorysql.%, not 15), and two of them cannot be set in a configuration file at all. Add a "Configuration Files and Parameters" section to the installation page (CN and EN), between "Start Database" and "Connecting to IvorySQL": - where ivorysql.conf comes from: written by initdb from the share directory sample, with only the Oracle port and shared_preload_libraries replaced by the installation values, and included from postgresql.conf by include_if_exists = 'ivorysql.conf'; commented out in PostgreSQL mode; - the coverage: 4 of the 15 ivorysql.* parameters, which four, and that only ivorysql.enable_emptystring_to_NULL is an active line; - why the eleven stay out: they are registered with GUC_NOT_IN_SAMPLE, and src/test/modules/test_misc/t/003_check_guc.pl asserts that the parameters in the sample and the parameters without that flag are the same set, so adding them by hand would fail the test; - how to reach them instead: user-facing ones through SHOW / SET, developer and diagnostic ones (GUC_NO_SHOW_ALL) through the enumeration query, which returns 8 rows rather than 15 by default; - a pointer to the parameter table in 7.2 "GUC框架" and to ivy_guc.c (guc_parameters.dat on master) for the rows that table does not list. Insertion only: 2 files changed, 52 insertions(+), 26 lines per language, no existing line modified. Verified with four Antora builds (CN and EN, base and patched, all exit 0), the same warning multiset as the baseline (CN 4 to 4, EN 8 to 8, none from 4.1.adoc), identical rendered counters in both languages (<h2> 9 to 10, id= 17 to 18, <pre> 29 to 30, tables unchanged at 6 / 13 / 34), and a site-wide diff in which only ivorysql-doc/v5.6/4.1.html changes. Closes #382
1 parent 7c3f4a6 commit 4d165de

2 files changed

Lines changed: 52 additions & 0 deletions

File tree

‎CN/modules/ROOT/pages/4.1.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,32 @@ ivorysql 130433 130427 0 02:45 ? 00:00:00 postgres: logical replicatio
223223
ivorysql 130445 130274 0 02:45 pts/1 00:00:00 grep --color=auto postgres
224224
```
225225

226+
== 配置文件与参数说明
227+
228+
Oracle 模式下,`initdb` 会在数据目录中生成 `ivorysql.conf`,内容取自安装目录 share 下的 `ivorysql.conf.sample`(仅 Oracle 端口与 `shared_preload_libraries` 会按实际安装值替换),并由同目录 `postgresql.conf` 中的 `include_if_exists = 'ivorysql.conf'` 引入;PostgreSQL 模式下该引入行被注释,也不会使用该文件。
229+
230+
`ivorysql.conf.sample`(IvorySQL 5.6)只涉及 15 个 `ivorysql.{asterisk}` 参数中的 4 个,这 15 个参数在 `src/backend/utils/misc/ivy_guc.c` 中注册。出现在样例中的 4 个是 `ivorysql.listen_addresses`、`ivorysql.port`、`ivorysql.identifier_case_switch` 与 `ivorysql.enable_emptystring_to_NULL`:前 3 个以注释形式给出示例,只有 `ivorysql.enable_emptystring_to_NULL` 是未注释的生效行。样例中另一个生效赋值是 `shared_preload_libraries`,它不属于 `ivorysql.{asterisk}` 参数。
231+
232+
其余 11 个 `ivorysql.{asterisk}` 参数不出现在样例中并非遗漏:IvorySQL 在注册这些参数时带上了 `GUC_NOT_IN_SAMPLE` 标记(定义见 `src/include/utils/guc.h`),测试用例 `src/test/modules/test_misc/t/003_check_guc.pl` 会断言「样例文件中的参数集合」等于「不带该标记的参数集合」。因此把这 11 个参数手工写进 `ivorysql.conf.sample` 会令该测试失败,它们应在使用时按需设置。
233+
234+
按使用方式,这 11 个参数可分为两类:
235+
236+
* 面向用户的参数:用 `SHOW` 查看、用 `SET` 在当前会话中修改,例如 `ivorysql.compatible_mode`、`ivorysql.database_mode`、`ivorysql.datetime_ignore_nls_mask` 与 `ivorysql.enable_case_switch`。其中 `ivorysql.compatible_mode` 与 `ivorysql.database_mode` 本身不允许在配置文件中设置。
237+
* 开发者/诊断参数:除 `GUC_NOT_IN_SAMPLE` 外还带 `GUC_NO_SHOW_ALL`,默认不出现在 `SHOW ALL` 与 `pg_settings` 视图中,供排查问题或开发调试时按需打开。
238+
239+
因此以超级用户连接后执行以下语句,默认返回 8 条而非 15 条,属于正常现象:
240+
241+
```
242+
SELECT name, pg_settings_get_flags(name) AS flags
243+
FROM pg_settings
244+
WHERE name LIKE 'ivorysql.%'
245+
ORDER BY name;
246+
```
247+
248+
结果中不带 `NOT_IN_SAMPLE` 的正是样例文件里的那 4 个参数;带 `NOT_IN_SAMPLE` 的参数应通过 `SHOW` / `SET` 使用,无需写进配置文件。
249+
250+
上述参数的说明与取值见 7.2「GUC框架」中的「新增变量(目前)」参数表(样例中的 4 个均在该表内);该表未列出的开发者参数,可结合上面的查询与源码 `src/backend/utils/misc/ivy_guc.c` 确认。
251+
226252
== 数据库连接
227253

228254
psql连接数据库:

‎EN/modules/ROOT/pages/4.1.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,32 @@ ivorysql 130433 130427 0 02:45 ? 00:00:00 postgres: logical replicatio
227227
ivorysql 130445 130274 0 02:45 pts/1 00:00:00 grep --color=auto postgres
228228
```
229229

230+
== Configuration Files and Parameters
231+
232+
In Oracle mode, `initdb` creates `ivorysql.conf` in the data directory. Its content comes from `ivorysql.conf.sample` in the share directory of the installation (only the Oracle port and `shared_preload_libraries` are replaced with the actual installation values), and the file is pulled in by `include_if_exists = 'ivorysql.conf'` in `postgresql.conf`. In PostgreSQL mode that include line is commented out and the file is not used.
233+
234+
`ivorysql.conf.sample` (IvorySQL 5.6) covers only 4 of the 15 `ivorysql.{asterisk}` parameters, which are registered in `src/backend/utils/misc/ivy_guc.c`: `ivorysql.listen_addresses`, `ivorysql.port`, `ivorysql.identifier_case_switch` and `ivorysql.enable_emptystring_to_NULL`. The first three are given as commented-out examples, and only `ivorysql.enable_emptystring_to_NULL` is an active, uncommented line. The other active setting in the sample is `shared_preload_libraries`, which is not an `ivorysql.{asterisk}` parameter.
235+
236+
The remaining 11 `ivorysql.{asterisk}` parameters are not missing from the sample by accident: IvorySQL registers them with the `GUC_NOT_IN_SAMPLE` flag (defined in `src/include/utils/guc.h`), and the test `src/test/modules/test_misc/t/003_check_guc.pl` asserts that the set of parameters in the sample file equals the set of parameters without that flag. Adding these 11 parameters to `ivorysql.conf.sample` by hand would therefore make that test fail; set them only when they are actually needed.
237+
238+
From a usage point of view the 11 parameters fall into two groups:
239+
240+
* User-facing parameters: read with `SHOW` and changed for the current session with `SET`, for example `ivorysql.compatible_mode`, `ivorysql.database_mode`, `ivorysql.datetime_ignore_nls_mask` and `ivorysql.enable_case_switch`. Note that `ivorysql.compatible_mode` and `ivorysql.database_mode` cannot be set in a configuration file at all.
241+
* Developer and diagnostic parameters: besides `GUC_NOT_IN_SAMPLE` they also carry `GUC_NO_SHOW_ALL`, so they do not appear in `SHOW ALL` or in the `pg_settings` view by default; they are switched on as needed when diagnosing a problem or during development.
242+
243+
For this reason the following statement, executed in a superuser session, returns 8 rows by default instead of 15, which is expected:
244+
245+
```
246+
SELECT name, pg_settings_get_flags(name) AS flags
247+
FROM pg_settings
248+
WHERE name LIKE 'ivorysql.%'
249+
ORDER BY name;
250+
```
251+
252+
The rows without `NOT_IN_SAMPLE` are exactly the four parameters present in the sample file; parameters that carry `NOT_IN_SAMPLE` are meant to be used with `SHOW` / `SET` and need not be written into the configuration file.
253+
254+
Descriptions and accepted values of these parameters, including the four present in the sample, are listed in the "New variables(currently)" table of 7.2 "GUC Framework"; for developer parameters that are not listed there, use the statement above together with `src/backend/utils/misc/ivy_guc.c`.
255+
230256
== Connecting to IvorySQL
231257

232258
Connect to IovrySQL via psql:

0 commit comments

Comments
 (0)