Skip to content

Commit a21dcdb

Browse files
committed
docs(faq): answer the twelve IvorySQL-specific questions users hit first
The FAQ page answers general questions, but none of the behaviours that are specific to IvorySQL's two serving modes: which port gives which mode, what synchronous replication does to sync_state, why commits hang after pg_promote(), why initdb and make fail when uuid-ossp is missing, and what the container image requires at startup. Add 12 Q&A entries to both the Chinese and the English page. Every number, error message and GUC value quoted here was reproduced on PostgreSQL 18.6 (IvorySQL 5.6) in this environment; nothing is copied from other projects. No existing content is removed. Closes #393 Assisted-by: DSH:deepseek-v4.1 Percentage of AI-generated code: 100%
1 parent 7d4ad9d commit a21dcdb

2 files changed

Lines changed: 664 additions & 0 deletions

File tree

  • CN/modules/ROOT/pages/master/contribution
  • EN/modules/ROOT/pages/master/contribution

‎CN/modules/ROOT/pages/master/contribution/faq.adoc‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,335 @@
5454
== 直接提交到存储库
5555

5656
有时,您会看到核心团队成员直接提交到存储库,而无需执行pull请求工作流。这仅适用于小的更改,我们使用的经验法则是:如果更改涉及任何可能导致测试失败的功能,那么它必须通过pull请求工作流。另一方面,如果更改发生在代码库的非功能部分(例如在注释块中修复打字错误),则核心团队成员可以决定直接提交到存储库。
57+
58+
== 安装与运行常见问题
59+
60+
本节收录社区里反复出现的安装、监听、复制与容器问题。每条回答都给出可以直接执行的检查命令,示例输出来自 IvorySQL 5.6(PostgreSQL 18.6)的实测记录。
61+
62+
=== 应该选 Oracle 兼容模式还是 PostgreSQL 模式?
63+
64+
模式由 `initdb` 的 `-m` 参数决定,并在初始化时写入集群的 control file。初始化完成之后无法再通过修改配置文件切换:`ivorysql.database_mode` 是内部参数,不允许出现在配置文件里,只能由 control file 的值决定。
65+
66+
`initdb --help` 对这一项的说明是 `-m, --dbmode=MODE set database mode, default is oracle`,也就是不写 `-m` 时默认就是 Oracle 兼容模式;要 PG 模式则显式写 `-m pg`。取值非法时 initdb 直接拒绝:
67+
68+
```
69+
$ initdb -D <data_dir> -m nosuchmode
70+
unrecognized database mode.
71+
```
72+
73+
要确认一个已有集群属于哪种模式,用 `pg_controldata` 即可(`database mode` 为 `1` 是 Oracle 兼容模式,为 `0` 是 PostgreSQL 模式):
74+
75+
```
76+
$ pg_controldata -D <data_dir> | grep -i mode
77+
database mode: 1
78+
case conversion mode: 1
79+
```
80+
81+
[TIP]
82+
====
83+
Oracle 兼容模式会在 initdb 的 post-bootstrap 阶段自动执行 `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`。选模式之前请先确认构建产物里带 uuid-ossp,否则初始化会失败(见下文「initdb 报 extension "uuid-ossp" is not available 怎么办」)。
84+
====
85+
86+
=== 1521 和 5432 是两个不同的数据库吗?
87+
88+
不是。一个 postmaster 会同时打开两个监听器:`port`(默认 5432,PostgreSQL 协议)和 `ivorysql.port`(默认 1521,Oracle 兼容协议),两个端口指向同一份数据目录。`ss` 里能看到两行监听属于同一个 pid:
89+
90+
```
91+
$ ss -ltnp | grep -E ':(1521|5432)'
92+
LISTEN 0 200 127.0.0.1:1521 0.0.0.0:* users:(("postgres",pid=10566,fd=7))
93+
LISTEN 0 200 127.0.0.1:5432 0.0.0.0:* users:(("postgres",pid=10566,fd=6))
94+
```
95+
96+
启动日志里也是成对出现:
97+
98+
```
99+
2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
100+
2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432
101+
2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521
102+
2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521
103+
```
104+
105+
官方 Docker 镜像默认就是这种双监听形态,不需要额外配置参数。
106+
107+
=== 为什么两个端口连进去 `ivorysql.compatible_mode` 不一样?
108+
109+
因为兼容模式由「连进来的是哪个监听器」决定,不是由数据库决定。同一个库,从 `port` 连进去是 `pg`,从 `ivorysql.port` 连进去是 `oracle`:
110+
111+
```
112+
---- 端口 5432 ----
113+
conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc
114+
-----------+---------------+-----------------+------------------+----------+--------------
115+
5432 | oracle | pg | localhost | 5432 | 1521
116+
(1 row)
117+
118+
---- 端口 1521 ----
119+
conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc
120+
-----------+---------------+-----------------+------------------+----------+--------------
121+
1521 | oracle | oracle | localhost | 5432 | 1521
122+
(1 row)
123+
```
124+
125+
注意两种连接下 `database_mode` 都是 `oracle`:它是集群级的(来自 control file),而 `compatible_mode` 是会话级的。`pg_settings` 里也能看出这个区别——`ivorysql.compatible_mode` 的 `source` 是 `override`(启动阶段被强制赋值)、`context` 是 `user`:
126+
127+
```
128+
$ psql -p 5432 -c "select name, setting, source, context from pg_settings where name in ('port','ivorysql.port','ivorysql.listen_addresses','ivorysql.database_mode','ivorysql.compatible_mode') order by name"
129+
name | setting | source | context
130+
---------------------------+-----------+----------+------------
131+
ivorysql.compatible_mode | pg | override | user
132+
ivorysql.database_mode | oracle | override | internal
133+
ivorysql.listen_addresses | localhost | default | postmaster
134+
ivorysql.port | 1521 | default | postmaster
135+
port | 5432 | default | postmaster
136+
(5 rows)
137+
```
138+
139+
同一条查询改连 1521,只有 `ivorysql.compatible_mode` 那一行变成 `oracle`,其余四行逐字相同。
140+
141+
[NOTE]
142+
====
143+
`context = user` 意味着可以在会话里 `SET ivorysql.compatible_mode`,但那只影响当前会话,重连一次又会由端口重新决定。不要在应用里靠会话级 `SET` 来「固定模式」。
144+
====
145+
146+
=== 主备两个节点应该怎么配端口?
147+
148+
每个节点都要按「`port` + `ivorysql.port`」成对配置。原因见上一条:客户端连哪个监听器就得到哪种兼容模式。如果备库只改了 `port`、`ivorysql.port` 仍留在默认的 1521,只读应用从 1521 连过来拿到的是 Oracle 兼容模式,而它连主库时走的是 PG 模式,两边行为就会漂移。实测一对主备的设置:
149+
150+
```
151+
port=5532 ivorysql.port=1621 mode=pg in_recovery=false sync_names=FIRST 1 (walreceiver) sync_commit=on
152+
port=5533 ivorysql.port=1622 mode=pg in_recovery=true ro=on
153+
connected_on_1622 mode=oracle in_recovery=true
154+
```
155+
156+
两个监听端口只要不相等就能正常启动,默认的 5432 + 1521 本身已是正确配置,通常不必把这两行写进配置文件。若确实要改,只改 `ivorysql.port`,且不能与 `port` 相同:
157+
158+
```
159+
## postgresql.conf
160+
port = 5432
161+
ivorysql.port = 1522
162+
163+
$ pg_ctl -D <data_dir> -l <log_file> -w start
164+
waiting for server to start.... done
165+
server started
166+
```
167+
168+
把两者配成同一个端口(例如 `port = 1521`,而 `ivorysql.port` 仍是默认的 1521)会让启动直接失败:
169+
170+
```
171+
LOG: listening on IPv4 address "127.0.0.1", port 1521
172+
LOG: could not bind IPv4 address "127.0.0.1": Address already in use
173+
HINT: Is another postmaster already running on port 1521? If not, wait a few seconds and retry.
174+
WARNING: could not create listen socket for "localhost"
175+
FATAL: could not create any Oracle TCP/IP sockets
176+
```
177+
178+
[NOTE]
179+
====
180+
`pg_ctl` 只会在终端上说 `could not start server`,原因要去日志里看。这里先失败的实际是 Oracle 侧监听器(`could not create any Oracle TCP/IP sockets`),而 HINT 提示的「是不是已有 postmaster 在跑」在端口自撞场景下会把人带偏。
181+
====
182+
183+
=== `sync_state` 有时是 `sync`、有时是 `quorum`?
184+
185+
取决于 `synchronous_standby_names` 的写法。命名制(`FIRST n (...)`)下被点名的备库报 `sync`:
186+
187+
```
188+
application_name | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag
189+
------------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+-----------------
190+
walreceiver | streaming | sync | 1 | 0/3000000 | 0/3000000 | 00:00:00.000093 | 00:00:00.000093 | 00:00:00.000093
191+
(1 row)
192+
```
193+
194+
quorum 制(`ANY n (*)`)下同一张表报 `quorum`:
195+
196+
```
197+
pid | usename | application_name | client_addr | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag
198+
-----+----------+------------------+-------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+-----------------
199+
542 | ivorysql | walreceiver | 127.0.0.1 | streaming | quorum | 1 | 0/3000000 | 0/3000000 | 00:00:00.000133 | 00:00:00.000133 | 00:00:00.000133
200+
(1 row)
201+
```
202+
203+
所以看到 `sync_state` 与预期不符时,先看主库的 `synchronous_standby_names` 写的是命名制还是 quorum 制,再看 `pg_stat_replication`。
204+
205+
=== 提升(promote)之后写入一直不返回,怎么排查?
206+
207+
典型现象是:会话处于 `active` 状态,`wait_event_type` 是 `IPC`,`wait_event` 是 `SyncRep`,而且 `statement_timeout` 设了也不生效。先确认提升后的节点是不是还带着 `synchronous_standby_names`、却已经没有任何备库:
208+
209+
```
210+
inherited_sync_names=[FIRST 1 (walreceiver)]
211+
```
212+
213+
由 `pg_basebackup -R` 拉起的备库会继承原主库的 `synchronous_standby_names`。提升之后它自己成了主库,但没有任何备库能确认同步复制,于是任何提交都会永久等待:
214+
215+
```
216+
pid | state | wait_event_type | wait_event | backend_xmin | query
217+
------+--------+-----------------+------------+--------------+--------------------------------------------------------------
218+
1132 | active | IPC | SyncRep | 773 | set statement_timeout='8s'; insert into sync_probe(id,note)
219+
1134 | active | | | 773 | select pid, state, wait_event_type, wait_event, backend_xmin
220+
(2 rows)
221+
```
222+
223+
等过 8 秒(`statement_timeout` 本该触发的时长)再看,仍然卡在同一个等待事件上。处理办法是先确认确实没有备库,再清空同步复制配置:
224+
225+
```
226+
ALTER SYSTEM SET synchronous_standby_names = '';
227+
SELECT pg_reload_conf();
228+
```
229+
230+
清空后同一条 INSERT 立刻返回:
231+
232+
```
233+
sync_names=[]
234+
INSERT 0 1
235+
```
236+
237+
[NOTE]
238+
====
239+
`ALTER SYSTEM` 与 `SELECT pg_reload_conf();` 必须分开执行。写成一行用分号连起来会报 `ERROR: ALTER SYSTEM cannot run inside a transaction block`。
240+
====
241+
242+
=== `initdb` 报 `extension "uuid-ossp" is not available` 怎么办?
243+
244+
Oracle 兼容模式在 initdb 的 post-bootstrap 阶段会执行 `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`。如果这套二进制里没有 uuid-ossp 的扩展文件,初始化就会中断,并把刚建好的数据目录删掉:
245+
246+
```
247+
performing post-bootstrap initialization ... FATAL: extension "uuid-ossp" is not available
248+
HINT: The extension must first be installed on the system where PostgreSQL is running.
249+
STATEMENT: --
250+
-- Plugin uuid-ossp
251+
--
252+
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
253+
child process exited with exit code 1
254+
initdb: removing data directory "<data_dir>"
255+
```
256+
257+
先确认当前安装到底有没有这个扩展(`installed_version` 为空表示可安装但没装;整行都查不到表示扩展文件根本没进 `SHAREDIR`):
258+
259+
```
260+
$ psql -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';"
261+
name | default_version | installed_version
262+
-----------+-----------------+-------------------
263+
uuid-ossp | 1.1 | 1.1
264+
(1 row)
265+
```
266+
267+
在 Oracle 兼容模式的集群里,`template1` 已经带着它,新建的库会自动继承:
268+
269+
```
270+
extname | extversion
271+
--------------+------------
272+
gb18030_2022 | 1.0
273+
ivorysql_ora | 1.0
274+
plisql | 1.0
275+
plpgsql | 1.0
276+
uuid-ossp | 1.1
277+
(5 rows)
278+
```
279+
280+
如果可用扩展列表里查不到 uuid-ossp,`CREATE EXTENSION` 会直接报 `ERROR: 0A000: extension "uuid-ossp" is not available`,附带的 HINT 与上面 initdb 里那条相同。修复方向有两条:一是使用发行版软件包或官方镜像(通常已带该扩展,装完先跑上面第一条 SQL 自检),二是在自行构建时给 `configure` 加上 `--with-uuid`(见下文)。用 `initdb -m pg` 初始化的集群不会自动安装这个扩展(template1 里只有 `gb18030_2022` 与 `plpgsql`),但这不影响之后在需要时再装。
281+
282+
=== 源码构建时漏了 `--with-uuid` 会怎样?
283+
284+
`configure` 不会报错,它只是把 uuid 支持关掉——一份不带 `--with-uuid` 的配置跑完只有这两行结果:
285+
286+
```
287+
configure rc=0
288+
config.log:6635: with_uuid='no'
289+
```
290+
291+
`configure --help` 对这一项的原文是 `--with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)`,可选值是 `bsd`、`e2fs`、`ossp`。不选任何一个时,`make` 在编译 `contrib/uuid-ossp` 时会直接撞上 `#error`:
292+
293+
```
294+
/root/src56/contrib/uuid-ossp/uuid-ossp.c:40:2: error: #error "please use configure's --with-uuid switch to select a UUID library"
295+
```
296+
297+
顶层 `GNUmakefile` 无条件把 `contrib/uuid-ossp` 放进 `all install`:
298+
299+
```
300+
11:$(call recurse,all install,src config contrib/gb18030_2022 contrib/ivorysql_ora contrib/uuid-ossp contrib/ora_btree_gist contrib/ora_btree_gin)
301+
```
302+
303+
所以整条构建在 `make` 阶段就断了,根本走不到 `make install`。要在 Oracle 兼容模式的数据目录里使用 uuid-ossp(或让 `initdb -m oracle` 能完成初始化),构建时必须带上 `--with-uuid`。
304+
305+
[TIP]
306+
====
307+
不要用 `make -C contrib/uuid-ossp` 单独验证这件事:在已有构建产物的源码树里它可能因为「已是最新」而返回 0,看起来像没问题。
308+
====
309+
310+
=== 跑回归测试时用哪种模式?
311+
312+
TAP 测试固定用 PostgreSQL 模式(`-m pg`)的模板集群,与服务器自身的模式无关。`make -C src/bin/initdb check` 会先建模板目录,再在固定端口上跑 `prove`(下面第二行为便于阅读省略了中间的环境变量赋值):
313+
314+
```
315+
initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean '<tmp_install>/initdb-template'
316+
PGPORT='65432' ... prove -I ../../../src/test/perl/ -I . t/*.pl
317+
```
318+
319+
```
320+
t/001_initdb.pl ............. ok
321+
t/002_gb18030.pl ............ ok
322+
t/003_uuid_ossp_missing.pl .. ok
323+
All tests successful.
324+
Files=3, Tests=86, 19 wallclock secs ( 0.04 usr 0.01 sys + 7.25 cusr 9.03 csys = 16.33 CPU)
325+
Result: PASS
326+
```
327+
328+
自己写 TAP 用例时,`initdb` 夹具照着这个形态写(`-m pg` + `--no-sync` + `--no-clean` + 独立 `PGPORT`)最省事,也不会与 Oracle 兼容模式的 post-bootstrap 行为耦合。
329+
330+
=== 容器不设 `IVORYSQL_PASSWORD` 为什么直接退出?
331+
332+
镜像的 entrypoint 在数据目录为空时会先做初始化,而超级用户密码必须显式给出。没给就会在初始化之前退出:
333+
334+
```
335+
Error: Database is uninitialized and superuser password is not specified.
336+
You must specify IVORYSQL_PASSWORD to a non-empty value for the
337+
superuser. For example, "-e IVORYSQL_PASSWORD=password" on "docker run".
338+
339+
You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all
340+
connections without a password. This is *not* recommended.
341+
```
342+
343+
此时容器状态是 `exited exit=1`。按提示用 `-e IVORYSQL_PASSWORD=<password>` 传入即可。提示里提到的 `POSTGRES_HOST_AUTH_METHOD=trust` 虽然也能让它启动,但等于对所有连接免密,不建议使用。
344+
345+
=== 容器默认监听哪些端口?`5866` 是什么?
346+
347+
镜像默认同时监听 5432 与 1521,与裸机安装一致:
348+
349+
```
350+
2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
351+
2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432
352+
2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521
353+
2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521
354+
```
355+
356+
`docker inspect` 里还会看到一个 `5866/tcp`。它不是对外服务端口,而是 entrypoint 在初始化阶段临时使用的端口,并且此时只监听本机:
357+
358+
```
359+
set -- "$@" -c listen_addresses='' -p "${PGPORT:-5866}"
360+
```
361+
362+
初始化结束、正式启动之后,对外仍然是 5432 与 1521。做健康检查时让 `pg_isready` 指向真正的服务端口即可(镜像是 UBI 底座,没有 `ss`、`netstat`、`ps` 可用,所以容器内排查端口要靠这两个监听器自己的日志):
363+
364+
```
365+
--health-cmd "pg_isready -p 1521 -U ivorysql"
366+
```
367+
368+
=== `ivorysql.conf.sample` 里只出现了 4 个 `ivorysql.*` 参数,是不是只有 4 个可配?
369+
370+
不是。IvorySQL 一共注册了 15 个 `ivorysql.*` 参数,样例文件里出现的是 4 个,其中 3 个被注释掉、1 个是生效行:
371+
372+
```
373+
#ivorysql.listen_addresses = 'localhost' # what IP address(es) of Oracle mode to listen on;
374+
#ivorysql.port = 1521 # (change requires restart)
375+
ivorysql.enable_emptystring_to_NULL = 'on'
376+
#ivorysql.identifier_case_switch = interchange # set the case conversion mode. range [normal,interchange,lowercase]
377+
```
378+
379+
其余 11 个在注册时带了 `GUC_NOT_IN_SAMPLE` 标志(含义就是「不进 postgresql.conf.sample」),因此不会出现在样例里。这个「4 / 11」的划分是被 CI 强制住的,不是遗漏:`src/test/modules/test_misc/t/003_check_guc.pl` 里有三条断言,既要求该出现的必须出现(`no parameters missing from postgresql.conf.sample`),也要求带了该标志的参数不能出现(`no parameters marked as NOT_IN_SAMPLE in postgresql.conf.sample`)。因此往样例里补齐那 11 个反而会让测试变红。
380+
381+
想知道某个参数为什么不在样例里,可以直接查运行时标志,凡是结果里带 `NOT_IN_SAMPLE` 的就是不会写进样例的参数:
382+
383+
```
384+
SELECT name, pg_settings_get_flags(name) AS flags
385+
FROM pg_settings
386+
WHERE name LIKE 'ivorysql.%'
387+
ORDER BY name;
388+
```

0 commit comments

Comments
 (0)