Repository navigation
docs(5.2): 1521 and 5432 are not interchangeable — the listener determines ivorysql.compatible_mode - #379
Open
qwer381 wants to merge 1 commit into
Open
docs(5.2): 1521 and 5432 are not interchangeable — the listener determines ivorysql.compatible_mode#379qwer381 wants to merge 1 commit into
qwer381 wants to merge 1 commit into
Conversation
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
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. |
|
🚀 IvorySQL-Docs Preview Ready
|
qwer381
force-pushed
the
docs/fix-v5.6-5.2-ports
branch
from
November 13, 2026 05:52
7a1a876 to
2b2a3fd
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 #378
What this changes
Two files, pure insertion, no existing line touched:
The new section
=== 双监听端口/=== Dual listening portsgoes in the Oracle part of the pgvectorchapter, 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 iswhere 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
psqlinvocations and their output, so the difference is shown rather than asserted: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 useshow portorshow ivorysql.port, which print the same values on both ports because they describe the listeners;SET ivorysql.compatible_modeworks inside a session but does not survive reconnecting, whereasivorysql.database_modeis a cluster property written intopg_controlbyinitdb;a warning: the two ports must differ;
pg_ctl -o "-p 1521"cannot move the Oracle port (the-ooption only overrides
port), and neither canport = 1521inpostgresql.conf. The four server loglines that result are included, together with the observation that
Address already in usereads likea 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 givesoracleand 5432 gives
pg;the closing sentence: the second listener exists only on Oracle-mode clusters (
DB_ORACLE == database_modein the source); a PostgreSQL-mode cluster listens onportalone.Why
5.2.adocis the page where a reader is first told to connect to port 1521, and the tip there does notsay 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.portappears exactly onceper language, as a row in the GUC table of
7.2.adoc. The two ways this bites are both silent:show port/show ivorysql.portanswer5432/1521on either port, so a reader who checks thatway gets a plausible answer that cannot distinguish the two cases;
SET ivorysql.compatible_mode = 'oracle'from 5432 succeeds, and the next connection ispgagain —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 "anotherpostmaster"), 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.git apply --check --verboseon_base78(v5.6@7c3f4a6, clean tree)offset/fuzzline in the outputreport.md§2.1git apply --check --cached(index, independent of the work tree)report.md§2.2indexlinesb0c1a25..c34e2ca(CN) and1869c68..51a4bf3(EN) match bothHEAD:<page>and the patched file hashesreport.md§2.3report.md§3,logs/01-antora-*.log,logs/01-antora-summary.json5.2.htmlsizereport.md§5.15.2.adocreport.md§4.1file:line:messagereport.md§4.2<table>2 → 5,<tr>2 → 7,<td>4 → 17,<h3>8 → 9,id=13 → 14, section anchors 11 → 12; CN and EN identicalreport.md§5.1,logs/02-html-counts.json+5 <tr>/+13 <td>come from[TIP]+1 / +1 / +2, new[WARNING]+1 / +1 / +2 — so the table itself adds 3 rows in both languagesreport.md§5.2ivorysql.port8 hits in CN and 8 in EN;Address already in use2 / 2;show port1 / 1; the closing "single listener" sentence 1 / 1;DB_ORACLE == database_mode1 / 1; the1522example 2 / 2report.md§6show porttip at5.2.adoc:108(CN) /5.2.adoc:110(EN);pg_ctl -owarning at5.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 atCN-5.2.adoc:142/EN-5.2.adoc:144in the delivery copiesreport.md§7 (warnings),report.md§6 (closing sentence),pr-port/CN-5.2.adoc:142,pr-port/EN-5.2.adoc:144_双监听端口/_dual-listening-ports)report.md§5.3(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.pngTwo notes on reading that table:
=== 数据类型moves thefollowing subsections down by one (
数据类型4.1 → 4.2, and so on). The anchor ids are untouched, soxrefs keep working; only prose that quotes a literal "4.1" would need updating, and none does today.measured on a live 5.6 cluster (
_evidence/port-dual.md§2-§6), and the "a PostgreSQL-mode cluster hasone listener" sentence was verified by initializing a cluster with
initdb -m pgand checkingss:pg_controldatareportsdatabase mode: 0, that postmaster owns exactly oneLISTENsocket(
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 on1521and5432givingoracleandpgrespectively(
_verify-uuid/t8/logs/93-dual-port-mode.txt, PID 12836 listening on both).To re-check the patch after fetching it:
(
ivorysql_docsis checked out with LF line endings —git ls-files --eolreportsi/lf w/lffor bothpages — so the plain
--checkis meaningful here; the--cachedrun in row 2 is just a second,independent angle.)
Checklist
+138 / −0, no existing line modifiedCNandENupdated in the same commit, same structure, semantically equalgit apply --check(and--cached) clean onv5.6@7c3f4a6, no offset, no fuzz5.2.adocproduces zero warningsCloses #378Signed-off-byadded by the human submitter