Repository navigation
Conversation
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
|
🚀 IvorySQL-Docs Preview Ready
|
qwer381
force-pushed
the
docs/fix-v5.6-conf-sample
branch
from
November 11, 2026 13:31
4461f2c to
9f801af
Compare
|
🚀 IvorySQL-Docs Preview Ready
|
qwer381
force-pushed
the
docs/fix-v5.6-conf-sample
branch
from
November 13, 2026 05:53
9f801af to
4d165de
Compare
|
🚀 IvorySQL-Docs Preview Ready
|
Author
|
Deploy-preview verification of
|
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #382
What this changes
Insertion only — no existing line is modified, moved or reflowed:
One new
==level section,== 配置文件与参数说明/== Configuration Files and Parameters, is inserted after theinitdboutput in "启动数据库" / "Start Database" and before "数据库连接" / "Connecting to IvorySQL". The following section keeps its text and simply moves 26 lines down (it wasCN:226/EN:230before the patch).The new section covers, in this order:
ivorysql.confcomes from —initdbwrites it into the data directory fromivorysql.conf.samplein the share directory, replacing only the Oracle port andshared_preload_librarieswith the installation values;postgresql.confpulls it in throughinclude_if_exists = 'ivorysql.conf', and in PostgreSQL mode that line is commented out;ivorysql.*parameters:ivorysql.listen_addresses,ivorysql.portandivorysql.identifier_case_switchas commented examples, andivorysql.enable_emptystring_to_NULLas the only active line. The other 11 are registered insrc/backend/utils/misc/ivy_guc.c;GUC_NOT_IN_SAMPLE(src/include/utils/guc.h), andsrc/test/modules/test_misc/t/003_check_guc.plasserts 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;SHOWand changed withSET(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 carryGUC_NO_SHOW_ALLand therefore do not appear inSHOW ALLor inpg_settingsby default;NOT_IN_SAMPLEare exactly the four in the sample;7.2"GUC Framework" ("新增变量(目前)" in the CN "GUC框架" page) for descriptions and accepted values, and toivy_guc.c(guc_parameters.datonmaster) for the developer parameters that table does not list.Why
ivorysql.conf.sampleis not an incidental file: on an Oracle-mode clusterinitdbturns it intoivorysql.confin the data directory, andpostgresql.confincludes that file. It is the first — and for most readers the only — list ofivorysql.*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 wholev5.6branch returns zero hits. A reader therefore has no way to learn that eleven more parameters exist, that seven of those are also hidden fromSHOW ALLandpg_settings(8 rows forivorysql.%, 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.plasserts 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.6at7c3f4a6.1. The patch applies to the branch it targets —
v5.6at7c3f4a6, clean working tree:Both patched files are clean text:
CN10623 B andEN12365 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 (sha25675EE3308…/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 aspath + line + messagetriples; no warning originates in4.1.adoc).<table><tr><td><h3><h2>id="<pre>data-lang4.1.html4.1.html+1heading,+1anchor id,+1code 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:<strong><code>ivorysql.<strong>(bad nesting)<code>ivorysql.*</code>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.ymlpinsantora@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