Skip to content

docs(5.2): 1521 and 5432 are not interchangeable — the listener determines ivorysql.compatible_mode - #379

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

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

Conversation

@qwer381

@qwer381 qwer381 commented Nov 10, 2026 •

Copy link
Copy Markdown

Closes #378

What this changes

Two files, pure insertion, no existing line touched:

 CN/modules/ROOT/pages/5.2.adoc | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 EN/modules/ROOT/pages/5.2.adoc | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 138 insertions(+)

The new section === 双监听端口 / === Dual listening ports goes in the Oracle part of the pgvector
chapter, immediately after the existing tip that tells readers to test with psql -p 1521
(CN:72-73 / EN:74-75) and before === 数据类型 / === Data Type (CN:75 / EN:77) — that tip is
where the docs first hand a reader the port 1521, and it is the sentence this section explains.

What the section says, in the rendered order:

  • a 3-column table: port (default 5432) → PostgreSQL parser, ivorysql.compatible_mode = pg;
    ivorysql.port (default 1521) → Oracle-compatible parser, = oracle; both defaults are built in;

  • the two psql invocations and their output, so the difference is shown rather than asserted:

     oracle          | 1521            | 5432     -- psql -p 1521
     pg              | 1521            | 5432     -- psql -p 5432
    
  • the mode is decided when the connection is established, from the local port on the server side; the
    client address, the user name and the database name do not enter into it;

  • a tip: read current_setting('ivorysql.compatible_mode'); do not use show port or
    show ivorysql.port, which print the same values on both ports because they describe the listeners;

  • SET ivorysql.compatible_mode works inside a session but does not survive reconnecting, whereas
    ivorysql.database_mode is a cluster property written into pg_control by initdb;

  • a warning: the two ports must differ; pg_ctl -o "-p 1521" cannot move the Oracle port (the -o
    option only overrides port), and neither can port = 1521 in postgresql.conf. The four server log
    lines that result are included, together with the observation that Address already in use reads like
    a foreign process owns the port while the owner is this cluster's own Oracle listener;

  • the way to actually change it: port = 5432 + ivorysql.port = 1522, after which 1522 gives oracle
    and 5432 gives pg;

  • the closing sentence: the second listener exists only on Oracle-mode clusters (DB_ORACLE == database_mode in the source); a PostgreSQL-mode cluster listens on port alone.

Why

5.2.adoc is the page where a reader is first told to connect to port 1521, and the tip there does not
say what that port is. Nothing in the repository explains that the two ports are two listeners of one
postmaster or that the connection port is what selects the parser; ivorysql.port appears exactly once
per language, as a row in the GUC table of 7.2.adoc. The two ways this bites are both silent:

  • show port / show ivorysql.port answer 5432 / 1521 on either port, so a reader who checks that
    way gets a plausible answer that cannot distinguish the two cases;
  • SET ivorysql.compatible_mode = 'oracle' from 5432 succeeds, and the next connection is pg again —
    the value is re-derived from the port on every connect.

And the natural next step after "use 1521" — making 1521 the main port — stops the server from starting
with an error that points at the wrong cause (Address already in use, plus a hint about "another
postmaster"), which is exactly the sort of thing a paragraph in the docs prevents.

Testing

All numbers below come from _verify-port/report.md; raw logs and the counting JSON are linked per row.

# Check Result Evidence
1 git apply --check --verbose on _base78 (v5.6 @ 7c3f4a6, clean tree) exit 0; no offset / fuzz line in the output report.md §2.1
2 git apply --check --cached (index, independent of the work tree) exit 0 report.md §2.2
3 patch ≡ work tree at blob level patch index lines b0c1a25..c34e2ca (CN) and 1869c68..51a4bf3 (EN) match both HEAD:<page> and the patched file hashes report.md §2.3
4 Antora build, CN and EN, base and patched 4 builds, all exit 0 (CN base 3.1 s, EN base 2.3 s, CN patched 3.0 s, EN patched 2.3 s) report.md §3, logs/01-antora-*.log, logs/01-antora-summary.json
5 5.2.html size CN 22281 → 27929 B, EN 22586 → 28520 B report.md §5.1
6 warnings from 5.2.adoc 0 — the file is not mentioned in any of the four build logs report.md §4.1
7 site-wide warning set, base vs patched identical line for line: CN 4 → 4, EN 8 → 8, same file:line:message report.md §4.2
8 rendered counters <table> 2 → 5, <tr> 2 → 7, <td> 4 → 17, <h3> 8 → 9, id= 13 → 14, section anchors 11 → 12; CN and EN identical report.md §5.1, logs/02-html-counts.json
9 where the +5 <tr> / +13 <td> come from data table +1 table / +3 rows / +9 cells, new [TIP] +1 / +1 / +2, new [WARNING] +1 / +1 / +2 — so the table itself adds 3 rows in both languages report.md §5.2
10 key facts present in the rendered HTML ivorysql.port 8 hits in CN and 8 in EN; Address already in use 2 / 2; show port 1 / 1; the closing "single listener" sentence 1 / 1; DB_ORACLE == database_mode 1 / 1; the 1522 example 2 / 2 report.md §6
11 CN / EN parity of the two warnings and the closing sentence show port tip at 5.2.adoc:108 (CN) / 5.2.adoc:110 (EN); pg_ctl -o warning at 5.2.adoc:117 (CN) / 5.2.adoc:119 (EN) — present in both, semantically equal, not word-for-word; the closing sentence renders once per language, and sits at CN-5.2.adoc:142 / EN-5.2.adoc:144 in the delivery copies report.md §7 (warnings), report.md §6 (closing sentence), pr-port/CN-5.2.adoc:142, pr-port/EN-5.2.adoc:144
12 no dead links the 11 pre-existing section anchor ids on the page are unchanged; only one new anchor is added (_双监听端口 / _dual-listening-ports) report.md §5.3
13 visual check on the real build output section sits right after the existing tip, 3×3 table renders complete, both psql outputs (including (1 row)) visible, TIP/WARNING badges intact, no raw |==== or ---- report.md §8, shots/cn-5.2-dual-ports-section.png, shots/en-5.2-dual-ports-section.png

Two notes on reading that table:

  • Visible numbering shifts; anchors do not. Inserting a section before === 数据类型 moves the
    following subsections down by one (数据类型 4.1 → 4.2, and so on). The anchor ids are untouched, so
    xrefs keep working; only prose that quotes a literal "4.1" would need updating, and none does today.
  • The measurements behind the text are not inferred from the source. The two-port behaviour was
    measured on a live 5.6 cluster (_evidence/port-dual.md §2-§6), and the "a PostgreSQL-mode cluster has
    one listener" sentence was verified by initializing a cluster with initdb -m pg and checking ss:
    pg_controldata reports database mode: 0, that postmaster owns exactly one LISTEN socket
    (127.0.0.1:15432), and 1521 belongs to a different process
    (_verify-uuid/t8/logs/92-pgmode-listen.txt). The dual-port half is the same cluster measured on
    1521 and 5432 giving oracle and pg respectively
    (_verify-uuid/t8/logs/93-dual-port-mode.txt, PID 12836 listening on both).

To re-check the patch after fetching it:

git -C ivorysql_docs apply --check --verbose ../patch.diff          # expect exit 0, no offset
git -C ivorysql_docs apply --stat   ../patch.diff                   # expect: 2 files changed, 138 insertions(+)

(ivorysql_docs is checked out with LF line endings — git ls-files --eol reports i/lf w/lf for both
pages — so the plain --check is meaningful here; the --cached run in row 2 is just a second,
independent angle.)

Checklist

  • Documentation only: 2 files, +138 / −0, no existing line modified
  • Both CN and EN updated in the same commit, same structure, semantically equal
  • git apply --check (and --cached) clean on v5.6 @ 7c3f4a6, no offset, no fuzz
  • Antora builds CN and EN with exit 0, and 5.2.adoc produces zero warnings
  • No new site-wide warnings (CN 4 → 4, EN 8 → 8, identical messages)
  • No changed or removed anchor ids on the page
  • Every statement in the section is backed by a measurement, not by reading the source
  • Closes #378
  • Signed-off-by added by the human submitter

5.2.adoc is the page that first tells a reader to connect to port 1521, and
the tip there does not say what that port is. Two silent mistakes follow
from that:

  - show port / show ivorysql.port print 5432 and 1521 on either port, so
    they look like a way to check the compatibility mode;
  - SET ivorysql.compatible_mode = 'oracle' from 5432 succeeds, and the next
    connection is pg again, because the value is re-derived from the port.

And the obvious next step after "use 1521" -- making 1521 the main port --
stops the server from starting, with a message that points at the wrong
cause: "could not bind IPv4 address 127.0.0.1: Address already in use",
hinted as "Is another postmaster already running on port 1521?", while the
process holding the port is this cluster's own Oracle listener. The real
FATAL is "could not create any Oracle TCP/IP sockets".

Add a "Dual listening ports" section after that tip and before the data
type section, in both CN and EN:

  - port (default 5432) routes to the PostgreSQL parser and ivorysql.port
    (default 1521) to the Oracle-compatible parser; one postmaster owns
    both sockets and both defaults are built in;
  - the mode is decided when the connection is established, from the local
    port on the server side, shown with the two psql invocations and their
    output (oracle | 1521 | 5432 versus pg | 1521 | 5432);
  - read current_setting('ivorysql.compatible_mode') to find out the mode of
    the current session; show port / show ivorysql.port cannot tell;
  - SET works within a session but does not survive reconnecting, while
    ivorysql.database_mode is a cluster property written into pg_control;
  - the two ports must differ; neither pg_ctl -o "-p 1521" (which overrides
    port only) nor "port = 1521" in postgresql.conf can move the Oracle
    port, with the four log lines that result;
  - to change it, set ivorysql.port to another value and keep port = 5432;
    afterwards the new port gives oracle and 5432 gives pg;
  - the second listener exists only on Oracle-mode clusters
    (DB_ORACLE == database_mode); a PostgreSQL-mode cluster listens on port
    alone.

Insertion only: 2 files changed, 138 insertions(+), 69 lines per language,
no existing line modified. Verified with 4 Antora builds (CN/EN, base and
patched, all exit 0), zero warnings from 5.2.adoc, unchanged site-wide
warning set (CN 4->4, EN 8->8), identical rendered counters in both
languages (<tr> 2->7, <td> 4->17, <h3> 8->9), and the 11 pre-existing
section anchor ids untouched.

Closes IvorySQL#378
@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.

@github-actions
github-actions Bot temporarily deployed to pull request November 10, 2026 15:28 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 5.2 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/5.2.html 28,936 B 24,639 B +4,297 B
EN /en/ivorysql-doc/v5.6/5.2.html 29,414 B 24,830 B +4,584 B
  • CN preview renders <h3 id="双监听端口">4.1. 双监听端口</h3>; EN preview renders <h3 id="dual-listening-ports">4.1. Dual listening ports</h3>.
  • Placement matches the description: in both languages the <h3> opens immediately after the closing tags of the existing tip that tells readers to test with psql -p 1521 — </td></tr></table></div><div class="sect2"><h3 id=… — so the new section follows that tip and precedes 4.2 数据类型 / 4.2 Data Type.
  • Numbering survives the insertion: the CN sequence moves from 4.1 数据类型 / 4.2 匿名块 / 4.3 存储过程 / 4.4 函数 to 4.1 双监听端口 / 4.2 数据类型 / 4.3 匿名块 / 4.4 存储过程 / 4.5 函数, with the same shift in EN (4.1 Dual listening ports / 4.2 Data Type / 4.3 Anonymous Block / 4.4 PROCEDURE / 4.5 FUNCTION). No gap, no duplicate.
  • The rendered table carries the pairing the title claims: port / 5432 → PostgreSQL parser (ivorysql.compatible_mode = pg), ivorysql.port / 1521 → Oracle-compatible parser (ivorysql.compatible_mode = oracle), with the note that both defaults apply even when postgresql.conf does not set them.
  • Against the live page, the served HTML goes from 0 to 6 occurrences of ivorysql.compatible_mode, 2 to 13 of 1521, and 0 to 8 of 5432 — identically in both languages. Neither heading exists on https://docs.ivorysql.org/{cn,en}/ivorysql-doc/v5.6/5.2.html today, so the deltas are this branch's.

This branch was previously deployed

1 inactive deployment
pull request — 2b2a3fd0 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(5.2): 1521 and 5432 are not interchangeable — the listener determines ivorysql.compatible_mode

2 participants