Skip to content

Commit 2b2a3fd

Browse files
committed
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 (<tr> 2->7, <td> 4->17, <h3> 8->9), and the 11 pre-existing section anchor ids untouched. Closes #378
1 parent 7c3f4a6 commit 2b2a3fd

2 files changed

Lines changed: 138 additions & 0 deletions

File tree

‎CN/modules/ROOT/pages/5.2.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,75 @@ CREATE EXTENSION
7272
[TIP]
7373
建议用户使用1521端口进行测试, psql -p 1521
7474

75+
=== 双监听端口
76+
77+
Oracle 模式集群中,同一个 postmaster 会同时监听两个端口,连哪个端口就由哪套解析器接管:
78+
79+
|====
80+
| 参数 | 默认端口 | 连该端口时生效的解析器
81+
| `port` | 5432 | PostgreSQL 解析器(`ivorysql.compatible_mode` = `pg`)
82+
| `ivorysql.port` | 1521 | Oracle 兼容解析器(`ivorysql.compatible_mode` = `oracle`)
83+
|====
84+
85+
两个参数都有内置默认值,`postgresql.conf` 里不写也照样生效。用 psql 分别连接两个端口就能看到差别:
86+
87+
[literal]
88+
----
89+
$ psql -h 127.0.0.1 -p 1521 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
90+
current_setting | current_setting | current_setting
91+
-----------------+-----------------+-----------------
92+
oracle | 1521 | 5432
93+
(1 row)
94+
95+
$ psql -h 127.0.0.1 -p 5432 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
96+
current_setting | current_setting | current_setting
97+
-----------------+-----------------+-----------------
98+
pg | 1521 | 5432
99+
(1 row)
100+
----
101+
102+
同一个用户、同一个数据库、同一个集群,只换了连接端口,会话的兼容模式就跟着变。模式在连接建立时确定,判定依据是服务端本地端口,与客户端地址、用户名、数据库名都无关。
103+
104+
[TIP]
105+
====
106+
要判断当前会话处在哪种模式,请读 `current_setting('ivorysql.compatible_mode')`。
107+
108+
不要用 `show port` 或 `show ivorysql.port`:这两个值在两个端口上的输出完全一样(5432 和 1521),它们描述的是监听器,不是会话模式。
109+
====
110+
111+
`ivorysql.compatible_mode` 可以在会话里用 `SET` 临时改掉,但重连即复位,新连接会被端口重新判定一次。`ivorysql.database_mode` 则是集群属性,在 `initdb` 时写进 `pg_control`,与连哪个端口无关。
112+
113+
[WARNING]
114+
====
115+
两个监听端口必须不相等。默认的 5432 与 1521 本身正确,不需要额外配置。
116+
117+
不要用 `pg_ctl -o "-p 1521"` 启动服务:`-o` 只覆盖 PostgreSQL 侧的 `port`,改不动 `ivorysql.port`,两个 1521 撞在一起,服务直接起不来——和把 `port` 改成 1521 是同一个冲突。
118+
119+
也不要在 `postgresql.conf` 里把 `port` 改成 1521:
120+
121+
[literal]
122+
----
123+
LOG: could not bind IPv4 address "127.0.0.1": Address already in use
124+
HINT: Is another postmaster already running on port 1521? If not, wait a few seconds and retry.
125+
WARNING: could not create listen socket for "localhost"
126+
FATAL: could not create any Oracle TCP/IP sockets
127+
----
128+
129+
`Address already in use` 很容易被理解成别的进程占了端口,实际占用它的是这个集群自己的 Oracle 监听器,`ss` 里找不到第二个进程。排查时先确认配置里 `port` 与 `ivorysql.port` 是否相等。
130+
====
131+
132+
确实需要换端口时,只改 `ivorysql.port`,并保持两个值不相等:
133+
134+
[literal]
135+
----
136+
port = 5432
137+
ivorysql.port = 1522
138+
----
139+
140+
重启后连 1522 得到 `oracle`,连 5432 得到 `pg`。
141+
142+
双监听是 Oracle 模式集群独有的:只有 `initdb --dbmode=oracle` 建出的集群,postmaster 才会额外创建 Oracle 监听套接字(源码里对应 `DB_ORACLE == database_mode` 判断)。PostgreSQL 模式的集群只有 `port` 一个监听端口。
143+
75144
=== 数据类型
76145

77146
[literal]

‎EN/modules/ROOT/pages/5.2.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,75 @@ In IvorySQL's Oracle compatibility mode, the pgvector extension can also work co
7474
[TIP]
7575
We suggest users to test using port 1521, using the command: psql -p 1521.
7676

77+
=== Dual listening ports
78+
79+
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:
80+
81+
|====
82+
| Parameter | Default port | Parser used by connections on that port
83+
| `port` | 5432 | PostgreSQL parser (`ivorysql.compatible_mode` = `pg`)
84+
| `ivorysql.port` | 1521 | Oracle-compatible parser (`ivorysql.compatible_mode` = `oracle`)
85+
|====
86+
87+
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:
88+
89+
[literal]
90+
----
91+
$ psql -h 127.0.0.1 -p 1521 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
92+
current_setting | current_setting | current_setting
93+
-----------------+-----------------+-----------------
94+
oracle | 1521 | 5432
95+
(1 row)
96+
97+
$ psql -h 127.0.0.1 -p 5432 -d postgres -c "select current_setting('ivorysql.compatible_mode'), current_setting('ivorysql.port'), current_setting('port')"
98+
current_setting | current_setting | current_setting
99+
-----------------+-----------------+-----------------
100+
pg | 1521 | 5432
101+
(1 row)
102+
----
103+
104+
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.
105+
106+
[TIP]
107+
====
108+
To find out which mode the current session is in, read `current_setting('ivorysql.compatible_mode')`.
109+
110+
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.
111+
====
112+
113+
`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.
114+
115+
[WARNING]
116+
====
117+
The two listening ports must differ. The defaults, 5432 and 1521, are already correct and need no extra configuration.
118+
119+
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.
120+
121+
Nor set `port = 1521` in `postgresql.conf`:
122+
123+
[literal]
124+
----
125+
LOG: could not bind IPv4 address "127.0.0.1": Address already in use
126+
HINT: Is another postmaster already running on port 1521? If not, wait a few seconds and retry.
127+
WARNING: could not create listen socket for "localhost"
128+
FATAL: could not create any Oracle TCP/IP sockets
129+
----
130+
131+
`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.
132+
====
133+
134+
If a different port is really needed, change only `ivorysql.port` and keep the two values apart:
135+
136+
[literal]
137+
----
138+
port = 5432
139+
ivorysql.port = 1522
140+
----
141+
142+
After a restart, port 1522 gives you `oracle` and port 5432 gives you `pg`.
143+
144+
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.
145+
77146
=== Data Type
78147

79148
[literal]

0 commit comments

Comments
 (0)