Skip to content

ivorysql.conf.sample documents 4 of the 15 ivorysql.* parameters, and the other 11 are documented nowhere #382

Open

Description

@qwer381

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_mode and ivorysql.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 by initdb, 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:

  1. Where the file comes from — state that initdb writes ivorysql.conf in the data directory from ivorysql.conf.sample in the share directory, that only the Oracle port and shared_preload_libraries are replaced with the installation values, and that the file is pulled in by include_if_exists = 'ivorysql.conf' in postgresql.conf (commented out in PostgreSQL mode).
  2. What the sample covers — 4 of the 15 ivorysql.* parameters, which four they are, and the fact that only ivorysql.enable_emptystring_to_NULL is an active line while the other three are commented examples.
  3. 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, and ivy_guc.c (guc_parameters.dat on master) in the source tree.
  4. Why the 11 stay out of the sample — they carry GUC_NOT_IN_SAMPLE and 003_check_guc.pl asserts they do, so the gap is by design and must not be "fixed" by editing the sample.
  5. How to reach them instead — user-facing ones through SHOW / SET, developer and diagnostic ones (which are invisible in SHOW ALL and pg_settings by 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

  1. qwer381 commented on Nov 11, 2026

    @qwer381
    Author

    /assign

  2. added a commit that references this issue on Nov 11, 2026
    9f801af
  3. qwer381 commented on Nov 11, 2026

    @qwer381
    Author

    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 four ivorysql.* 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.c registers 15, and the 11 that carry GUC_NOT_IN_SAMPLE are 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):

    SELECT count(*) FROM pg_settings WHERE name LIKE 'ivorysql.%';
    -- 8
    
    SELECT name, pg_settings_get_flags(name) FROM pg_settings
     WHERE name LIKE 'ivorysql.%' ORDER BY name;
    -- compatible_mode, database_mode, datetime_ignore_nls_mask, enable_case_switch   -> {NOT_IN_SAMPLE}
    -- enable_emptystring_to_NULL, identifier_case_switch, listen_addresses, port    -> {}
    -- (8 rows)
    

    So 8 = 15 − 7: seven of the eleven flagged parameters also carry GUC_NO_SHOW_ALL, which is why they are invisible in pg_settings and in SHOW 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.2 already names six of the fifteen; listen_addresses is missing there only because the v5.6 page spells it ivorysql.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, head 9f801af, 2 files / +52 −0, mergeable_state=clean, build-and-deploy green with a Netlify preview, and git apply --check exits 0 against origin/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 the sys_guid() note), shorter, or re-based onto master, say which and I will redo it.

  4. qwer381 commented on Nov 11, 2026

    @qwer381
    Author

    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.sample is 15 lines and names four ivorysql.* parameters:

    line form parameter
    7 commented ivorysql.listen_addresses
    11 commented ivorysql.port
    13 active ivorysql.enable_emptystring_to_NULL = 'on'
    15 commented ivorysql.identifier_case_switch

    src/backend/utils/misc/ivy_guc.c registers 15; the 11 that carry GUC_NOT_IN_SAMPLE are 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.pl asserts 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 carrying NOT_IN_SAMPLE, i.e. 15 - 7, the seven being the ones that also carry GUC_NO_SHOW_ALL and are therefore invisible in both pg_settings and SHOW ALL.

    3. Scope of "4 of 15". It describes the sample file, not documentation coverage. The parameter table in 7.2 already names six of the fifteen; listen_addresses appears only after #373, because v5.6 spells it ivorysql.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, head 9f801af, 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-deploy success with a live Netlify preview. git apply --check and git apply --check --cached both exit 0 against the current origin/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 the sys_guid() note), in a shorter form, or based on master instead of v5.6? Name a direction and I will redo it straight away.

  5. added a commit that references this issue on Nov 13, 2026
    4d165de
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions