From 2b2a3fd0f222b42a05b6831f44cebe1ae8138c8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E8=AF=97=E7=84=B1?= <3372848903@qq.com>
Date: Tue, 10 Nov 2026 15:23:58 +0000
Subject: [PATCH] docs(5.2): explain the two listening ports of an Oracle-mode
cluster
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 (
2->7, 4->17, 8->9), and the 11 pre-existing
section anchor ids untouched.
Closes #378
---
CN/modules/ROOT/pages/5.2.adoc | 69 ++++++++++++++++++++++++++++++++++
EN/modules/ROOT/pages/5.2.adoc | 69 ++++++++++++++++++++++++++++++++++
2 files changed, 138 insertions(+)
diff --git a/CN/modules/ROOT/pages/5.2.adoc b/CN/modules/ROOT/pages/5.2.adoc
index b0c1a25a..c34e2ca4 100644
--- a/CN/modules/ROOT/pages/5.2.adoc
+++ b/CN/modules/ROOT/pages/5.2.adoc
@@ -72,6 +72,75 @@ CREATE EXTENSION
[TIP]
建议用户使用1521端口进行测试, psql -p 1521
+=== 双监听端口
+
+Oracle 模式集群中,同一个 postmaster 会同时监听两个端口,连哪个端口就由哪套解析器接管:
+
+|====
+| 参数 | 默认端口 | 连该端口时生效的解析器
+| `port` | 5432 | PostgreSQL 解析器(`ivorysql.compatible_mode` = `pg`)
+| `ivorysql.port` | 1521 | Oracle 兼容解析器(`ivorysql.compatible_mode` = `oracle`)
+|====
+
+两个参数都有内置默认值,`postgresql.conf` 里不写也照样生效。用 psql 分别连接两个端口就能看到差别:
+
+[literal]
+----
+$ psql -h 127.0.0.1 -p 1521 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
+ current_setting | current_setting | current_setting
+-----------------+-----------------+-----------------
+ oracle | 1521 | 5432
+(1 row)
+
+$ psql -h 127.0.0.1 -p 5432 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
+ current_setting | current_setting | current_setting
+-----------------+-----------------+-----------------
+ pg | 1521 | 5432
+(1 row)
+----
+
+同一个用户、同一个数据库、同一个集群,只换了连接端口,会话的兼容模式就跟着变。模式在连接建立时确定,判定依据是服务端本地端口,与客户端地址、用户名、数据库名都无关。
+
+[TIP]
+====
+要判断当前会话处在哪种模式,请读 `current_setting('ivorysql.compatible_mode')`。
+
+不要用 `show port` 或 `show ivorysql.port`:这两个值在两个端口上的输出完全一样(5432 和 1521),它们描述的是监听器,不是会话模式。
+====
+
+`ivorysql.compatible_mode` 可以在会话里用 `SET` 临时改掉,但重连即复位,新连接会被端口重新判定一次。`ivorysql.database_mode` 则是集群属性,在 `initdb` 时写进 `pg_control`,与连哪个端口无关。
+
+[WARNING]
+====
+两个监听端口必须不相等。默认的 5432 与 1521 本身正确,不需要额外配置。
+
+不要用 `pg_ctl -o "-p 1521"` 启动服务:`-o` 只覆盖 PostgreSQL 侧的 `port`,改不动 `ivorysql.port`,两个 1521 撞在一起,服务直接起不来——和把 `port` 改成 1521 是同一个冲突。
+
+也不要在 `postgresql.conf` 里把 `port` 改成 1521:
+
+[literal]
+----
+LOG: could not bind IPv4 address "127.0.0.1": Address already in use
+HINT: Is another postmaster already running on port 1521? If not, wait a few seconds and retry.
+WARNING: could not create listen socket for "localhost"
+FATAL: could not create any Oracle TCP/IP sockets
+----
+
+`Address already in use` 很容易被理解成别的进程占了端口,实际占用它的是这个集群自己的 Oracle 监听器,`ss` 里找不到第二个进程。排查时先确认配置里 `port` 与 `ivorysql.port` 是否相等。
+====
+
+确实需要换端口时,只改 `ivorysql.port`,并保持两个值不相等:
+
+[literal]
+----
+port = 5432
+ivorysql.port = 1522
+----
+
+重启后连 1522 得到 `oracle`,连 5432 得到 `pg`。
+
+双监听是 Oracle 模式集群独有的:只有 `initdb --dbmode=oracle` 建出的集群,postmaster 才会额外创建 Oracle 监听套接字(源码里对应 `DB_ORACLE == database_mode` 判断)。PostgreSQL 模式的集群只有 `port` 一个监听端口。
+
=== 数据类型
[literal]
diff --git a/EN/modules/ROOT/pages/5.2.adoc b/EN/modules/ROOT/pages/5.2.adoc
index 1869c685..51a4bf3f 100644
--- a/EN/modules/ROOT/pages/5.2.adoc
+++ b/EN/modules/ROOT/pages/5.2.adoc
@@ -74,6 +74,75 @@ In IvorySQL's Oracle compatibility mode, the pgvector extension can also work co
[TIP]
We suggest users to test using port 1521, using the command: psql -p 1521.
+=== Dual listening ports
+
+In an Oracle-mode cluster a single postmaster listens on two ports at once, and the port a client connects to decides which parser takes over the session:
+
+|====
+| Parameter | Default port | Parser used by connections on that port
+| `port` | 5432 | PostgreSQL parser (`ivorysql.compatible_mode` = `pg`)
+| `ivorysql.port` | 1521 | Oracle-compatible parser (`ivorysql.compatible_mode` = `oracle`)
+|====
+
+Both parameters have built-in defaults, so leaving them out of `postgresql.conf` still works. Connect with psql to each port and the difference shows up:
+
+[literal]
+----
+$ psql -h 127.0.0.1 -p 1521 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
+ current_setting | current_setting | current_setting
+-----------------+-----------------+-----------------
+ oracle | 1521 | 5432
+(1 row)
+
+$ psql -h 127.0.0.1 -p 5432 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
+ current_setting | current_setting | current_setting
+-----------------+-----------------+-----------------
+ pg | 1521 | 5432
+(1 row)
+----
+
+Same user, same database, same cluster: only the connection port changed, and the session is in a different compatibility mode. 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 have no say in it.
+
+[TIP]
+====
+To find out which mode the current session is in, read `current_setting('ivorysql.compatible_mode')`.
+
+Do not use `show port` or `show ivorysql.port` for this. Both print the very same values (5432 and 1521) on either port, because they describe the listeners, not the session.
+====
+
+`ivorysql.compatible_mode` can be changed within a session with `SET`, but that does not survive reconnecting — a new connection is classified by its port again. `ivorysql.database_mode`, by contrast, is a property of the cluster: written into `pg_control` at `initdb` time, unrelated to the port you connect to.
+
+[WARNING]
+====
+The two listening ports must differ. The defaults, 5432 and 1521, are already correct and need no extra configuration.
+
+Do not start the server with `pg_ctl -o "-p 1521"`. The `-o` option overrides `port` only; `ivorysql.port` keeps its value, the two 1521 assignments collide, and the server will not start — the same conflict as setting `port` to 1521.
+
+Nor set `port = 1521` in `postgresql.conf`:
+
+[literal]
+----
+LOG: could not bind IPv4 address "127.0.0.1": Address already in use
+HINT: Is another postmaster already running on port 1521? If not, wait a few seconds and retry.
+WARNING: could not create listen socket for "localhost"
+FATAL: could not create any Oracle TCP/IP sockets
+----
+
+`Address already in use` reads like another process owns the port, but the process holding it is this cluster's own Oracle listener, and `ss` shows no second postmaster. Compare `port` with `ivorysql.port` in the configuration before hunting for a port conflict.
+====
+
+If a different port is really needed, change only `ivorysql.port` and keep the two values apart:
+
+[literal]
+----
+port = 5432
+ivorysql.port = 1522
+----
+
+After a restart, port 1522 gives you `oracle` and port 5432 gives you `pg`.
+
+The second listener exists only on Oracle-mode clusters: the postmaster creates the Oracle listening socket only when the cluster was created with `initdb --dbmode=oracle` (in the source, the `DB_ORACLE == database_mode` check). A PostgreSQL-mode cluster listens on `port` alone.
+
=== Data Type
[literal]
|