Repository navigation
Description
Current state
src/backend/utils/misc/ivorysql.conf.sample at tag IvorySQL_5.6 is 15 lines long. The complete file:
1| #------------------------------------------------------------------------------
2| #Oracle COMPATIBLE Mode GUC parameters
3| #
4| #Portions Copyright (c) 2023-2026, IvorySQL Global Development Team
5| #------------------------------------------------------------------------------
6|
7| #ivorysql.listen_addresses = 'localhost' # what IP address(es) of Oracle mode to listen on;
8| # comma-separated list of addresses;
9| # defaults to 'localhost'; use '*' for all
10| # (change requires restart)
11| #ivorysql.port = 1521 # (change requires restart)
12|
13| ivorysql.enable_emptystring_to_NULL = 'on'
14| shared_preload_libraries = 'liboracle_parser, ivorysql_ora' # (change requires restart)
15| #ivorysql.identifier_case_switch = interchange # set the case conversion mode. range [normal,interchange,lowercase]
Four ivorysql.* parameters appear in it — 4 of 15:
| line | form | parameter |
|---|---|---|
| 7 | #name = value — commented |
ivorysql.listen_addresses |
| 11 | #name = value — commented |
ivorysql.port |
| 13 | name = value — active |
ivorysql.enable_emptystring_to_NULL |
| 15 | #name = value — commented |
ivorysql.identifier_case_switch |
So the file offers three commented examples and one setting that is in force from the first start. Line 14 (shared_preload_libraries) is not an ivorysql.* parameter and is not counted on either side of the 4/15.
The other 11 are registered in src/backend/utils/misc/ivy_guc.c (line = the DefineCustom*Variable call):
ivorysql.identifier_case_from_pg_dump 118
ivorysql.enable_case_switch 128
ivorysql.allow_out_parameter_const 154
ivorysql.out_parameter_column_position 165
ivorysql.enable_seq_scale_fixed 176
ivorysql.default_with_rowids 197
ivorysql.enable_internal_warning 208
ivorysql.datetime_ignore_nls_mask 247
ivorysql.rowid_seq_cache 258
ivorysql.database_mode 390
ivorysql.compatible_mode 401
They are also absent from the documentation: git grep -i 'conf\.sample' over the whole v5.6 branch returns zero hits in any file type. Nothing on the site states how much of the parameter set the sample covers, and nothing says where the rest are described.
Why this is a problem
ivorysql.conf.sample is not an incidental file. On an Oracle-mode cluster initdb writes ivorysql.conf into the data directory from it, and postgresql.conf pulls that file in through include_if_exists = 'ivorysql.conf'. It is the first — and for most readers the only — list of ivorysql.* parameters they will see, and it is the file they will copy lines from when they need to change something.
What a reader concludes from it:
- there are four
ivorysql.*parameters, one of which is on by default; - a parameter that is not in this file either does not exist or does not need setting;
ivorysql.compatible_mode,ivorysql.database_modeandivorysql.enable_case_switch— three of the eleven — look like invented names, because the sample never prints them. The first decides which parser a session uses, the second is a cluster property written byinitdb, and the third gates the identifier case conversion that the sample's own last line refers to.
For 7 of the 11 the situation is worse than "not in the sample": those 7 are registered with GUC_NO_SHOW_ALL on top of GUC_NOT_IN_SAMPLE, so they are absent from SHOW ALL and from the pg_settings view as well. A superuser who queries pg_settings for ivorysql.% gets 8 rows, not 15 (15 − 7) — and no page on the site explains the seven missing ones.
Two of the eleven (ivorysql.compatible_mode, ivorysql.database_mode) additionally refuse to be set in a configuration file at all (GUC_DISALLOW_IN_FILE), so for them "put it in the sample" would not even be the right answer. A reader needs to be told the right way to reach each group, which is a documentation job.
Finally, the sample is correct as it stands, and the documentation has to say so. src/test/modules/test_misc/t/003_check_guc.pl asserts that the parameter set in the sample equals the parameter set without GUC_NOT_IN_SAMPLE, in both directions. A contributor who reads this issue as "the sample is missing 11 parameters" and adds them will turn that test red. Without a page that states the rule, the same wrong patch will be sent again.
Expected behaviour
In the configuration documentation, on the page a reader reaches after installation:
- Where the file comes from — state that
initdbwritesivorysql.confin the data directory fromivorysql.conf.samplein the share directory, that only the Oracle port andshared_preload_librariesare replaced with the installation values, and that the file is pulled in byinclude_if_exists = 'ivorysql.conf'inpostgresql.conf(commented out in PostgreSQL mode). - What the sample covers — 4 of the 15
ivorysql.*parameters, which four they are, and the fact that onlyivorysql.enable_emptystring_to_NULLis an active line while the other three are commented examples. - Where the remaining parameters are described — a pointer to the parameter table in
7.2"GUC Framework" on the EN page / "GUC框架" on the CN page (table "New variables(currently)" / "新增变量(目前)"), plus the two ways to enumerate them independently:SELECT name, pg_settings_get_flags(name) FROM pg_settings WHERE name LIKE 'ivorysql.%';at runtime, andivy_guc.c(guc_parameters.datonmaster) in the source tree. - Why the 11 stay out of the sample — they carry
GUC_NOT_IN_SAMPLEand003_check_guc.plasserts they do, so the gap is by design and must not be "fixed" by editing the sample. - How to reach them instead — user-facing ones through
SHOW/SET, developer and diagnostic ones (which are invisible inSHOW ALLandpg_settingsby default) through the query above, and a note that the query returns 8 rows rather than 15 on a stock cluster.
Suggested landing page: CN/modules/ROOT/pages/4.1.adoc and EN/modules/ROOT/pages/4.1.adoc — the installation page, which already covers initdb and the configuration files it writes — as a new == section between "启动数据库" / "Start Database" and "数据库连接" / "Connecting to IvorySQL". Both files are free of in-flight changes; see the conflict check below. A PR for this issue is already prepared on branch docs/fix-v5.6-conf-sample.
Evidence
1. Fifteen registrations, eleven with GUC_NOT_IN_SAMPLE
src/backend/utils/misc/ivy_guc.c @ IvorySQL_5.6 registers 15 ivorysql.* parameters. The four without the flag are exactly the four in the sample:
| line | parameter | flags argument |
|---|---|---|
| 139 | ivorysql.enable_emptystring_to_NULL |
none |
| 235 | ivorysql.port |
none |
| 284 | ivorysql.listen_addresses |
GUC_LIST_INPUT only |
| 412 | ivorysql.identifier_case_switch |
none |
The remaining 11 carry GUC_NOT_IN_SAMPLE, 7 of them together with GUC_NO_SHOW_ALL. 11 + 4 = 15, which matches the registration count.
Flag definition, src/include/utils/guc.h:222:
#define GUC_NOT_IN_SAMPLE 0x000080 /* not in postgresql.conf.sample */The flag is readable from SQL through pg_settings_get_flags() (src/backend/utils/misc/guc_funcs.c:632-633; catalog entry in src/include/catalog/pg_proc.dat:6519-6520), which is what makes a self-service query possible:
SELECT name, pg_settings_get_flags(name) AS flags
FROM pg_settings
WHERE name LIKE 'ivorysql.%'
ORDER BY name;Rows without NOT_IN_SAMPLE are exactly the four that appear in the sample.
2. The 4/15 split is enforced by the test suite
src/test/modules/test_misc/t/003_check_guc.pl (149 lines) collects the GUC lines from both postgresql.conf.sample and ivorysql.conf.sample into one set, then asserts in both directions:
is(scalar(@missing_from_file), 0, "no parameters missing from postgresql.conf.sample");
is(scalar(@missing_from_guc_tables), 0, "no parameters missing from guc_tables.c");
is(scalar(@not_in_sample), 0, "no parameters marked as NOT_IN_SAMPLE in postgresql.conf.sample");The 4 must be present (else the first assertion fails) and the 11 must be absent (else the third fails). This is why the issue is about documentation and not about the sample file being incomplete.
3. Conflict check against the docs PRs open today
gh pr diff <n> --repo IvorySQL/ivorysql_docs --name-only, all four with base = v5.6 and state open:
| PR | files touched |
|---|---|
| #373 | CN/modules/ROOT/pages/7.2.adoc, EN/modules/ROOT/pages/7.2.adoc |
| #375 | CN/modules/ROOT/pages/7.8.adoc, EN/modules/ROOT/pages/7.8.adoc |
| #377 | CN/modules/ROOT/pages/8.1.adoc, EN/modules/ROOT/pages/8.adoc |
| #379 | CN/modules/ROOT/pages/5.2.adoc, EN/modules/ROOT/pages/5.2.adoc |
The union of the changed files of every open PR in the repository (including those based on master, whose files live under CN/.../pages/master/...) contains 4.1.adoc zero times — the only substring match is 6.4.1.adoc, a different page. CN/modules/ROOT/pages/4.1.adoc and EN/modules/ROOT/pages/4.1.adoc are untouched by all of them, so a new section there collides with nothing in review.
4. "4 of 15" also holds on master
ivorysql.conf.sample is the same file on master — a diff between the two branches produces no output — and the split is unchanged: the declarations moved to src/backend/utils/misc/guc_parameters.dat (the four now stand at lines 1494, 1521, 1528 and 1542) but still 11 carry GUC_NOT_IN_SAMPLE and 4 do not. This issue is filed against v5.6 because that is the branch the published site is built from; the coverage statement is true on both.
Environment
docs repository IvorySQL/ivorysql_docs, branch v5.6, commit 7c3f4a67e7d3dc92d3046ad54cac4de196aef4f1
source tag IvorySQL_5.6 -> 74c405c9c355a8167322b3749bbc1b982a0eb0c0 (2026-09-02)
sample file src/backend/utils/misc/ivorysql.conf.sample, 789 B, blob 2a8e768d…,
sha256 f67fb9b0… (byte-identical to the upstream blob, re-hashed locally)
guc registry src/backend/utils/misc/ivy_guc.c, blob 26616c4b…
test src/test/modules/test_misc/t/003_check_guc.pl (149 lines)
server build PostgreSQL 18.6 (IvorySQL 5.6) on x86_64-pc-linux-gnu,
compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
Activity
qwer381 commentedon Nov 11, 2026
/assign
docs(4.1): state ivorysql.conf.sample coverage (4 of 15 GUCs)
qwer381 commentedon Nov 11, 2026
Verification update for this report (re-checked end to end on 2026-11-11, IvorySQL 5.6).
Sample coverage — still 4 of 15.
src/backend/utils/misc/ivorysql.conf.sample(15 lines) contains exactly fourivorysql.*parameters:listen_addresses(line 7, commented),port(line 11, commented),enable_emptystring_to_NULL(line 13, active),identifier_case_switch(line 15, commented).ivy_guc.cregisters 15, and the 11 that carryGUC_NOT_IN_SAMPLEare exactly the 11 that are absent from the file — the four without the flag are exactly the four above.Runtime — the query returns 8 rows today. On a stock 5.6 cluster, connected to the Oracle port (1521):
So 8 = 15 − 7: seven of the eleven flagged parameters also carry
GUC_NO_SHOW_ALL, which is why they are invisible inpg_settingsand inSHOW ALL.One clarification, to keep this issue from being read wider than it is. "4 of 15" is about the sample file, not about documentation coverage. The parameter table in
7.2already names six of the fifteen;listen_addressesis missing there only because thev5.6page spells itivorysql.listen_address, which #373 fixes. What is absent from the site is any description of the sample file itself — where it comes from, how much of the parameter set it covers, and why the rest are deliberately left out so nobody "fixes" the file by adding them.PR #383 is ready against the current branch: base
v5.6, head9f801af, 2 files / +52 −0,mergeable_state=clean,build-and-deploygreen with a Netlify preview, andgit apply --checkexits 0 againstorigin/v5.6(7c3f4a6) in both working-tree and index mode — no rebase needed.If you would rather have this section somewhere else (
6.3.10, next to thesys_guid()note), shorter, or re-based ontomaster, say which and I will redo it.qwer381 commentedon Nov 11, 2026
Live re-check of the numbers in this issue: repository state read through the GitHub API and the runtime figures re-run on a local IvorySQL 5.6 cluster, both on 2026-11-11.
1. Sample coverage - exactly 4 of 15.
src/backend/utils/misc/ivorysql.conf.sampleis 15 lines and names fourivorysql.*parameters:ivorysql.listen_addressesivorysql.portivorysql.enable_emptystring_to_NULL = 'on'ivorysql.identifier_case_switchsrc/backend/utils/misc/ivy_guc.cregisters 15; the 11 that carryGUC_NOT_IN_SAMPLEare exactly the 11 absent from the file, and the four without the flag are exactly the four above.src/test/modules/test_misc/t/003_check_guc.plasserts this in both directions, so "completing" the sample would turn CI red.2. Runtime - 8 rows, not 15. On a stock 5.6 cluster, connected through the Oracle port (1521),
SELECT count(*) FROM pg_settings WHERE name LIKE 'ivorysql.%';returns 8: four parameters without flags plus four carryingNOT_IN_SAMPLE, i.e. 15 - 7, the seven being the ones that also carryGUC_NO_SHOW_ALLand are therefore invisible in bothpg_settingsandSHOW ALL.3. Scope of "4 of 15". It describes the sample file, not documentation coverage. The parameter table in
7.2already names six of the fifteen;listen_addressesappears only after #373, becausev5.6spells itivorysql.listen_address. What no page on the site describes is the sample file itself - where it comes from, how much of the parameter set it covers, and why the other eleven are deliberately left out.4. PR #383 state, read through the API just now. base
v5.6, head9f801af, 2 files / +52 -0 (CN/modules/ROOT/pages/4.1.adoc+26,EN/modules/ROOT/pages/4.1.adoc+26),mergeable_state=clean,build-and-deploysuccess with a live Netlify preview.git apply --checkandgit apply --check --cachedboth exit 0 against the currentorigin/v5.6(7c3f4a6), so no rebase is needed.5. Open question. Would you rather have this section somewhere else (for example
6.3.10, next to thesys_guid()note), in a shorter form, or based onmasterinstead ofv5.6? Name a direction and I will redo it straight away.docs(4.1): state ivorysql.conf.sample coverage (4 of 15 GUCs)