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]