Skip to content

docs(4.1): state ivorysql.conf.sample coverage (4 of 15 GUCs) - #383

Open
qwer381 wants to merge 1 commit into
IvorySQL:v5.6from
qwer381:docs/fix-v5.6-conf-sample
Open

qwer381 wants to merge 1 commit into
IvorySQL:v5.6from
qwer381:docs/fix-v5.6-conf-sample

Conversation

@qwer381

@qwer381 qwer381 commented Nov 11, 2026 •

Copy link
Copy Markdown

Closes #382

What this changes

Insertion only — no existing line is modified, moved or reflowed:

 CN/modules/ROOT/pages/4.1.adoc | 26 ++++++++++++++++++++++++++
 EN/modules/ROOT/pages/4.1.adoc | 26 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

One new == level section, == 配置文件与参数说明 / == Configuration Files and Parameters, is inserted after the initdb output in "启动数据库" / "Start Database" and before "数据库连接" / "Connecting to IvorySQL". The following section keeps its text and simply moves 26 lines down (it was CN:226 / EN:230 before the patch).

The new section covers, in this order:

  • where ivorysql.conf comes from — initdb writes it into the data directory from ivorysql.conf.sample in the share directory, replacing only the Oracle port and shared_preload_libraries with the installation values; postgresql.conf pulls it in through include_if_exists = 'ivorysql.conf', and in PostgreSQL mode that line is commented out;
  • what the sample covers — 4 of the 15 ivorysql.* parameters: ivorysql.listen_addresses, ivorysql.port and ivorysql.identifier_case_switch as commented examples, and ivorysql.enable_emptystring_to_NULL as the only active line. The other 11 are registered in src/backend/utils/misc/ivy_guc.c;
  • why the 11 are not in the sample — they carry GUC_NOT_IN_SAMPLE (src/include/utils/guc.h), 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 to the sample would fail the test;
  • how to reach them instead — two groups: user-facing parameters read with SHOW and changed with SET (ivorysql.compatible_mode, ivorysql.database_mode, ivorysql.datetime_ignore_nls_mask, ivorysql.enable_case_switch, …, the first two of which cannot be set in a configuration file at all), and developer / diagnostic parameters that also carry GUC_NO_SHOW_ALL and therefore do not appear in SHOW ALL or in pg_settings by default;
  • the enumeration query, with the note that it returns 8 rows rather than 15 on a stock cluster, and that the rows without NOT_IN_SAMPLE are exactly the four in the sample;
  • a pointer to the "New variables(currently)" table in 7.2 "GUC Framework" ("新增变量(目前)" in the CN "GUC框架" page) for descriptions and accepted values, and to ivy_guc.c (guc_parameters.dat on master) for the developer parameters that table does not list.

Why

ivorysql.conf.sample is not an incidental file: on an Oracle-mode cluster initdb turns it into ivorysql.conf in the data directory, and postgresql.conf includes that file. It is the first — and for most readers the only — list of ivorysql.* parameters they will see, and the file they copy lines from when they need to change something. It shows four of them.

Nothing on the site explains the gap: git grep -i 'conf\.sample' over the whole v5.6 branch returns zero hits. A reader therefore has no way to learn that eleven more parameters exist, that seven of those are also hidden from SHOW ALL and pg_settings (8 rows for ivorysql.%, not 15), or that two of them cannot be put in a configuration file at all. Three of the eleven — ivorysql.compatible_mode, ivorysql.database_mode, ivorysql.enable_case_switch — read like invented names, because the sample never prints them, while the first decides which parser a session uses.

The obvious "fix" — adding the missing parameters to the sample — is wrong, and the page has to say so: 003_check_guc.pl asserts the sample and the flag-less parameter set are equal in both directions, so such a patch turns CI red. Without that sentence the same wrong patch will be sent again.

This is documentation only. The sample file, the flags and the test are correct as they are; what is missing is a page that states the coverage and points at the parameter table.

Testing

Every figure below was measured on this exact patch, on a local checkout of v5.6 at 7c3f4a6.

1. The patch applies to the branch it targets — v5.6 at 7c3f4a6, clean working tree:

git switch -c docs/fix-v5.6-conf-sample upstream/v5.6
git apply --check -p1 patch.diff            # exit 0
git apply --check --cached -p1 patch.diff   # exit 0
git apply -p1 patch.diff
git diff --stat
#  CN/modules/ROOT/pages/4.1.adoc | 26 ++++++++++++++++++++++++++
#  EN/modules/ROOT/pages/4.1.adoc | 26 ++++++++++++++++++++++++++
#  2 files changed, 52 insertions(+)
git diff --numstat
# 26  0  CN/modules/ROOT/pages/4.1.adoc
# 26  0  EN/modules/ROOT/pages/4.1.adoc
git apply --check -R -p1 patch.diff                 # exit 0 on the patched tree

Both patched files are clean text: CN 10623 B and EN 12365 B, CR = 0, no BOM, so the section did not disturb the line endings of the file it was inserted into. They are byte-identical to the standalone copies used for the render checks below (sha256 75EE3308… / CEF20F9D…), so the diff and the rendered text are the same bytes.

2. The site builds in both languages, before and after — Antora 3.2.2 with the repository UI bundle, four builds ({CN, EN} × {base, patched}): all exit 0, zero "level":"error" entries, and the warning multisets identical to the baseline (CN 4 → 4, EN 8 → 8, compared as path + line + message triples; no warning originates in 4.1.adoc).

page bytes <table> <tr> <td> <h3> <h2> id=" <pre> data-lang
CN 4.1.html 34111 → 37820 6 → 6 13 → 13 34 → 34 6 → 6 9 → 10 17 → 18 29 → 30 27 → 28
EN 4.1.html 35396 → 39430 6 → 6 13 → 13 34 → 34 6 → 6 9 → 10 17 → 18 29 → 30 27 → 28

+1 heading, +1 anchor id, +1 code block; no table changed shape. CN and EN are equal in every counter, which is the check that both languages received the same content. Site-wide, after normalising the absolute checkout path out of the generated "edit this page" links, exactly one file differs between base and patched: ivorysql-doc/v5.6/4.1.html (CN: 185 files compared, 184 identical; EN: 179 compared, 178 identical). In-page, the diff is −7 / +51: the seven removed lines are section numbers that shift by one (8 → 9, 9 → 10, 9.1–9.5 → 10.1–10.5), not content.

3. The text renders as intended — the first version of this patch wrote `ivorysql.*` in six places, and Asciidoctor paired the two * across the backticks: the output was <code>ivorysql.<strong></code> and the asterisks disappeared from the rendered paragraph. All six occurrences (3 per language) are now `ivorysql.{asterisk}`, and the assertions on the built HTML are:

build <strong> <code>ivorysql.<strong> (bad nesting) clean <code>ivorysql.*</code>
CN base 1 0 0 (section is new)
CN patched 1 0 3
EN base 1 0 0 (section is new)
EN patched 1 0 3

The single <strong> is the one the page already had before this patch, and no rendered paragraph loses its asterisks. The same detector, run against the superseded version of the patch, reports <strong> 2, bad nesting 1, clean occurrences 1, and two paragraphs with the asterisks missing — which is how these assertions were shown not to be vacuous.

4. Visual check — four screenshots at 1440 × 820 (CN and EN, top and bottom of the new section) show: the section heading "8. 配置文件与参数说明" / "8. Configuration Files and Parameters", its entry in the right-hand Contents between sections 7 and 9, the monospaced ivorysql.* with the asterisk visible and no bold contamination, the SQL block and the bullet lists rendering normally, and the join with the next section intact.

5. Not covered — the preview was built locally with Antora 3.2.2 / Node 24.14.1, while .github/workflows/pr-preview.yml pins antora@3.1.7 / Node 22.15; the page was checked in Chromium only (not print or dark theme); and no HTTP server was started (the files were opened from disk after normalising the path in generated links).

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)

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 IvorySQL#382
@github-actions
github-actions Bot temporarily deployed to pull request November 11, 2026 13:31 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381
qwer381 force-pushed the docs/fix-v5.6-conf-sample branch from 4461f2c to 9f801af Compare November 11, 2026 13:31
@github-actions
github-actions Bot temporarily deployed to pull request November 11, 2026 13:34 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 13, 2026

Copy link
Copy Markdown
Author

Deploy-preview verification of 4.1 on the v5.6 preview (fetched 2026-11-13; both pages HTTP 200, <title> carries (PR Preview)):

page preview live v5.6 delta
CN /cn/ivorysql-doc/v5.6/4.1.html 38,807 B 36,470 B +2,337 B
EN /en/ivorysql-doc/v5.6/4.1.html 40,315 B 37,652 B +2,663 B
  • CN preview renders the new section as <h2 id="配置文件与参数说明">8. 配置文件与参数说明</h2>; EN preview renders <h2 id="configuration-files-and-parameters">8. Configuration Files and Parameters</h2>.
  • Numbering survives the insertion: the <h2> sequence is 1–10 in both languages, and the section that used to be 8 (数据库连接 / Connecting to IvorySQL) renders as 9. No gap, no duplicate, no unnumbered heading anywhere in the sequence.
  • The claim in the body is on the page: the CN section reads ivorysql.conf.sample(IvorySQL 5.6)只涉及 15 个 ivorysql.* 参数中的 4 个, names ivorysql.listen_addresses, ivorysql.port, ivorysql.identifier_case_switch and ivorysql.enable_emptystring_to_NULL, and gives GUC_NOT_IN_SAMPLE plus 003_check_guc.pl as the reason the remaining 11 stay out of the sample.
  • ivorysql.conf.sample occurs 3× in the served CN HTML, against 0× on the live page — the topic was not mentioned there before this patch.
  • Neither heading exists on https://docs.ivorysql.org/{cn,en}/ivorysql-doc/v5.6/4.1.html today, so the byte deltas above come from this branch and not from a stale preview build.

This branch was previously deployed

1 inactive deployment
pull request — 4d165de2 Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants