Skip to content

docs(7.2): fix the GUC name and add the missing ivorysql.* parameters - #373

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

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

Conversation

@qwer381

@qwer381 qwer381 commented Nov 10, 2026 •

Copy link
Copy Markdown

PR: docs(7.2): fix the listen_addresses name, add enable_case_switch, document the developer-only GUCs

Closes #372

Target branch: v5.6. One commit, parent 7c3f4a67 — the current v5.6 head — and no conflicts against it.

What this changes

One page pair, three corrections — CN/modules/ROOT/pages/7.2.adoc and EN/modules/ROOT/pages/7.2.adoc:

  1. ivorysql.listen_address → ivorysql.listen_addresses. The singular name does not exist on the server; the row now also states the default ('localhost') and that a comma-separated list of addresses is accepted.
  2. Add the missing user-facing row ivorysql.enable_case_switch (default on), cross-referencing 7.3, which already documents the behaviour it controls.
  3. Add a === 开发者选项 / === Developer options subsection listing the 7 parameters registered as GUC_NO_SHOW_ALL | GUC_NOT_IN_SAMPLE, stating plainly that they do not appear in pg_settings and are not written to ivorysql.conf.sample.

Diffstat:

 CN/modules/ROOT/pages/7.2.adoc | 21 +++++++++++++++++++--   (19 insertions, 2 deletions)
 EN/modules/ROOT/pages/7.2.adoc | 21 +++++++++++++++++++--   (19 insertions, 2 deletions)
 2 files changed, 38 insertions(+), 4 deletions(-)

No source code, no build files, no other pages. The === 实现 / === Achieve section is intentionally not touched: on v5.6 the GUC definitions really are the Ivy_ConfigureNamesBool/Int/String/Enum arrays in src/backend/utils/misc/ivy_guc.c, so that text is correct for this branch (it changed only on master).

Why

  • SHOW ivorysql.listen_address; fails on a 5.6 instance with ERROR: unrecognized configuration parameter "ivorysql.listen_address" — the page currently hands users a name that cannot work. In v5.6, Ivy_ConfigureNamesString holds "ivorysql.listen_addresses" with GUC_LIST_INPUT and default "localhost".
  • ivorysql.enable_case_switch is PGC_USERSET with boot value true; leaving it out of the only table that lists settable ivorysql.* parameters makes that table incomplete.
  • The 7 developer-only parameters are visible neither in pg_settings (only 8 of the 15 ivorysql.* entries are returned) nor in ivorysql.conf.sample, so they are undiscoverable today. A separate subsection keeps the main table about everyday configuration while making them findable and clearly fenced off.

Testing

1. Applies to the target branch

gh pr checkout 373                                     # 1 commit, parent 7c3f4a67
git diff --numstat origin/v5.6...HEAD -- CN/modules/ROOT/pages/7.2.adoc EN/modules/ROOT/pages/7.2.adoc
# 19  2  CN/modules/ROOT/pages/7.2.adoc
# 19  2  EN/modules/ROOT/pages/7.2.adoc

2. The page still builds — same generator as .github/workflows/pr-preview.yml (Antora 3, start_path: CN and EN):

npx antora antora-playbook.yml        # exit 0

Rendered 7.2.html, before → after (every warning in that build comes from pre-existing 4.6.2.adoc / 6.3.2.adoc / 7.15.adoc; none from 7.2.adoc):

page bytes <tr> <td> <h3>
CN 7.2.html 25280 → 28675 30 → 39 60 → 86 4 → 5
EN 7.2.html 27940 → 32112 30 → 39 60 → 86 4 → 5

+9 rows = the new/renamed main-table rows plus the developer table (header + 7 rows); +1 heading = the new subsection. CN and EN render identically, as intended.

3. The behaviour claims hold on a running server — IvorySQL 5.6 built from tag IvorySQL_5.6, initdb -m oracle, select version() → PostgreSQL 18.6 (IvorySQL 5.6) ... gcc 13.3.0:

=> show ivorysql.listen_address;
ERROR:  unrecognized configuration parameter "ivorysql.listen_address"
=> show ivorysql.listen_addresses;
 ivorysql.listen_addresses = localhost
=> show ivorysql.enable_case_switch;
 ivorysql.enable_case_switch = on
=> select count(*) from pg_settings where name like 'ivorysql.%';
 8

4. Both languages changed identically

grep -c '^| ivorysql\.' CN/modules/ROOT/pages/7.2.adoc   # 15 (8 documented + 7 developer options)
grep -c '^| ivorysql\.' EN/modules/ROOT/pages/7.2.adoc   # 15
grep -n 'ivorysql\.listen_address[^e]' CN/... EN/...     # no match
grep -n 'ivorysql.enable_case_switch'  CN/... EN/...     # 1 match each

Checklist

  • One PR, one topic (documentation accuracy of 7.2 on v5.6)
  • CN and EN kept in sync
  • No code, no build files, no unrelated pages touched
  • Patch applies cleanly to v5.6, site builds, rendered row/heading deltas as stated
  • Behaviour verified on a running 5.6 instance
  • Closes #372 in the description
  • Signed-off-by (human submitter)

Section 7.2 of the v5.6 documentation lists a parameter that does not
exist (ivorysql.listen_address), omits one that does
(ivorysql.enable_case_switch), and never mentions the seven
developer-only parameters that are registered by IvorySQL but hidden
from pg_settings.

Changes (CN + EN):

  * ivorysql.listen_address -> ivorysql.listen_addresses, with the
    default value ('localhost') and the fact that it accepts a
    comma-separated list.
  * add ivorysql.enable_case_switch (bool, default on) and point to
    section 7.3 for the identifier case conversion details.
  * add a "Developer options" subsection documenting
    allow_out_parameter_const, default_with_rowids,
    enable_internal_warning, enable_seq_scale_fixed,
    identifier_case_from_pg_dump, out_parameter_column_position and
    rowid_seq_cache, noting that they are registered with
    GUC_NO_SHOW_ALL (invisible in pg_settings) and are not written to
    ivorysql.conf.sample.

Verified against a self-built IvorySQL 5.6 instance:
  show ivorysql.listen_address;   -> ERROR: unrecognized configuration parameter
  show ivorysql.listen_addresses; -> localhost
  show ivorysql.enable_case_switch; -> on
  select count(*) from pg_settings where name like 'ivorysql.%'; -> 8
(the seven developer options are all counted 0 there)

Antora build before/after: the 7.2 table goes from 30 rows / 60 cells
to 39 rows / 86 cells, and the page gains one section (4 -> 5).

Closes IvorySQL#372

Signed-off-by: 王诗焱 <3372848903@qq.com>
@github-actions
github-actions Bot temporarily deployed to pull request November 10, 2026 14:02 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 10, 2026

Copy link
Copy Markdown
Author

CLA: the Individual Contributor License Agreement for 王诗焱 (GitHub: qwer381) was signed and emailed to cla@ivorysql.org on 2026-11-10 (delivery confirmed by the mail provider).

If the community needs it re-sent to another address, or needs a scanned wet signature instead of the typed one, say the word and I will send it again.

@qwer381

qwer381 commented Nov 11, 2026

Copy link
Copy Markdown
Author

Friendly ping — this PR plus #375, #377, #379 and #383 are all green (build-and-deploy success, Netlify preview builds fine) and the individual CLA is on file (emailed 2026-11-10). No action needed if they are simply queued for review.

One question that would help me align with your conventions: should these target v5.6, or would you rather have them on master and backported? I picked v5.6 because all five describe behaviour I verified on the 5.6 tree, but re-targeting is a one-line change on my side. Same for anything that does not match the docs conventions (heading level, wording, xrefs) — tell me and I will adjust.

@qwer381
qwer381 force-pushed the docs/fix-v5.6-7.2-guc branch 2 times, most recently from b29ac50 to 1372aab Compare November 13, 2026 05:54
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@github-actions
github-actions Bot temporarily deployed to pull request November 13, 2026 05:56 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 13, 2026

Copy link
Copy Markdown
Author

Correction to my comment of 2026-11-11: "re-targeting is a one-line change on my side" is not accurate, and I would rather fix that here than leave it standing.

v5.6 is this repository's default branch and diverged from master at b038db2ac0 (2025-11-25), so moving the base would not leave this PR at one commit and two files — it would read as 110 commits / 175 files (~+2400 / ~−1015). The head branch also lives in my fork, and my account has no write access to IvorySQL/ivorysql_docs (permissions.push is false), so re-pointing the PR is not something I can do from my side at all.

The PR therefore stays on v5.6; if the same fix should also land on master, that is a separate one-commit PR I can open whenever it is wanted.

This branch was previously deployed

1 inactive deployment
pull request — 1372aab6 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.

docs: 7.2 documents a GUC that does not exist, omits enable_case_switch, and never lists the 7 developer-only GUCs

2 participants