diff --git a/CN/modules/ROOT/pages/master/contribution/faq.adoc b/CN/modules/ROOT/pages/master/contribution/faq.adoc index b556f11e..ba7af9c2 100644 --- a/CN/modules/ROOT/pages/master/contribution/faq.adoc +++ b/CN/modules/ROOT/pages/master/contribution/faq.adoc @@ -54,3 +54,335 @@ == 直接提交到存储库 有时,您会看到核心团队成员直接提交到存储库,而无需执行pull请求工作流。这仅适用于小的更改,我们使用的经验法则是:如果更改涉及任何可能导致测试失败的功能,那么它必须通过pull请求工作流。另一方面,如果更改发生在代码库的非功能部分(例如在注释块中修复打字错误),则核心团队成员可以决定直接提交到存储库。 + +== 安装与运行常见问题 + +本节收录社区里反复出现的安装、监听、复制与容器问题。每条回答都给出可以直接执行的检查命令,示例输出来自 IvorySQL 5.6(PostgreSQL 18.6)的实测记录。 + +=== 应该选 Oracle 兼容模式还是 PostgreSQL 模式? + +模式由 `initdb` 的 `-m` 参数决定,并在初始化时写入集群的 control file。初始化完成之后无法再通过修改配置文件切换:`ivorysql.database_mode` 是内部参数,不允许出现在配置文件里,只能由 control file 的值决定。 + +`initdb --help` 对这一项的说明是 `-m, --dbmode=MODE set database mode, default is oracle`,也就是不写 `-m` 时默认就是 Oracle 兼容模式;要 PG 模式则显式写 `-m pg`。取值非法时 initdb 直接拒绝: + +``` +$ initdb -D -m nosuchmode +unrecognized database mode. +``` + +要确认一个已有集群属于哪种模式,用 `pg_controldata` 即可(`database mode` 为 `1` 是 Oracle 兼容模式,为 `0` 是 PostgreSQL 模式): + +``` +$ pg_controldata -D | grep -i mode +database mode: 1 +case conversion mode: 1 +``` + +[TIP] +==== +Oracle 兼容模式会在 initdb 的 post-bootstrap 阶段自动执行 `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`。选模式之前请先确认构建产物里带 uuid-ossp,否则初始化会失败(见下文「initdb 报 extension "uuid-ossp" is not available 怎么办」)。 +==== + +=== 1521 和 5432 是两个不同的数据库吗? + +不是。一个 postmaster 会同时打开两个监听器:`port`(默认 5432,PostgreSQL 协议)和 `ivorysql.port`(默认 1521,Oracle 兼容协议),两个端口指向同一份数据目录。`ss` 里能看到两行监听属于同一个 pid: + +``` +$ ss -ltnp | grep -E ':(1521|5432)' +LISTEN 0 200 127.0.0.1:1521 0.0.0.0:* users:(("postgres",pid=10566,fd=7)) +LISTEN 0 200 127.0.0.1:5432 0.0.0.0:* users:(("postgres",pid=10566,fd=6)) +``` + +启动日志里也是成对出现: + +``` +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432 +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521 +``` + +官方 Docker 镜像默认就是这种双监听形态,不需要额外配置参数。 + +=== 为什么两个端口连进去 `ivorysql.compatible_mode` 不一样? + +因为兼容模式由「连进来的是哪个监听器」决定,不是由数据库决定。同一个库,从 `port` 连进去是 `pg`,从 `ivorysql.port` 连进去是 `oracle`: + +``` +---- 端口 5432 ---- + conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc +-----------+---------------+-----------------+------------------+----------+-------------- + 5432 | oracle | pg | localhost | 5432 | 1521 +(1 row) + +---- 端口 1521 ---- + conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc +-----------+---------------+-----------------+------------------+----------+-------------- + 1521 | oracle | oracle | localhost | 5432 | 1521 +(1 row) +``` + +注意两种连接下 `database_mode` 都是 `oracle`:它是集群级的(来自 control file),而 `compatible_mode` 是会话级的。`pg_settings` 里也能看出这个区别——`ivorysql.compatible_mode` 的 `source` 是 `override`(启动阶段被强制赋值)、`context` 是 `user`: + +``` +$ 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" + name | setting | source | context +---------------------------+-----------+----------+------------ + ivorysql.compatible_mode | pg | override | user + ivorysql.database_mode | oracle | override | internal + ivorysql.listen_addresses | localhost | default | postmaster + ivorysql.port | 1521 | default | postmaster + port | 5432 | default | postmaster +(5 rows) +``` + +同一条查询改连 1521,只有 `ivorysql.compatible_mode` 那一行变成 `oracle`,其余四行逐字相同。 + +[NOTE] +==== +`context = user` 意味着可以在会话里 `SET ivorysql.compatible_mode`,但那只影响当前会话,重连一次又会由端口重新决定。不要在应用里靠会话级 `SET` 来「固定模式」。 +==== + +=== 主备两个节点应该怎么配端口? + +每个节点都要按「`port` + `ivorysql.port`」成对配置。原因见上一条:客户端连哪个监听器就得到哪种兼容模式。如果备库只改了 `port`、`ivorysql.port` 仍留在默认的 1521,只读应用从 1521 连过来拿到的是 Oracle 兼容模式,而它连主库时走的是 PG 模式,两边行为就会漂移。实测一对主备的设置: + +``` +port=5532 ivorysql.port=1621 mode=pg in_recovery=false sync_names=FIRST 1 (walreceiver) sync_commit=on +port=5533 ivorysql.port=1622 mode=pg in_recovery=true ro=on +connected_on_1622 mode=oracle in_recovery=true +``` + +两个监听端口只要不相等就能正常启动,默认的 5432 + 1521 本身已是正确配置,通常不必把这两行写进配置文件。若确实要改,只改 `ivorysql.port`,且不能与 `port` 相同: + +``` +## postgresql.conf +port = 5432 +ivorysql.port = 1522 + +$ pg_ctl -D -l -w start +waiting for server to start.... done +server started +``` + +把两者配成同一个端口(例如 `port = 1521`,而 `ivorysql.port` 仍是默认的 1521)会让启动直接失败: + +``` +LOG: listening on IPv4 address "127.0.0.1", port 1521 +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 +``` + +[NOTE] +==== +`pg_ctl` 只会在终端上说 `could not start server`,原因要去日志里看。这里先失败的实际是 Oracle 侧监听器(`could not create any Oracle TCP/IP sockets`),而 HINT 提示的「是不是已有 postmaster 在跑」在端口自撞场景下会把人带偏。 +==== + +=== `sync_state` 有时是 `sync`、有时是 `quorum`? + +取决于 `synchronous_standby_names` 的写法。命名制(`FIRST n (...)`)下被点名的备库报 `sync`: + +``` + application_name | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag +------------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+----------------- + walreceiver | streaming | sync | 1 | 0/3000000 | 0/3000000 | 00:00:00.000093 | 00:00:00.000093 | 00:00:00.000093 +(1 row) +``` + +quorum 制(`ANY n (*)`)下同一张表报 `quorum`: + +``` + pid | usename | application_name | client_addr | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag +-----+----------+------------------+-------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+----------------- + 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 +(1 row) +``` + +所以看到 `sync_state` 与预期不符时,先看主库的 `synchronous_standby_names` 写的是命名制还是 quorum 制,再看 `pg_stat_replication`。 + +=== 提升(promote)之后写入一直不返回,怎么排查? + +典型现象是:会话处于 `active` 状态,`wait_event_type` 是 `IPC`,`wait_event` 是 `SyncRep`,而且 `statement_timeout` 设了也不生效。先确认提升后的节点是不是还带着 `synchronous_standby_names`、却已经没有任何备库: + +``` +inherited_sync_names=[FIRST 1 (walreceiver)] +``` + +由 `pg_basebackup -R` 拉起的备库会继承原主库的 `synchronous_standby_names`。提升之后它自己成了主库,但没有任何备库能确认同步复制,于是任何提交都会永久等待: + +``` + pid | state | wait_event_type | wait_event | backend_xmin | query +------+--------+-----------------+------------+--------------+-------------------------------------------------------------- + 1132 | active | IPC | SyncRep | 773 | set statement_timeout='8s'; insert into sync_probe(id,note) + 1134 | active | | | 773 | select pid, state, wait_event_type, wait_event, backend_xmin +(2 rows) +``` + +等过 8 秒(`statement_timeout` 本该触发的时长)再看,仍然卡在同一个等待事件上。处理办法是先确认确实没有备库,再清空同步复制配置: + +``` +ALTER SYSTEM SET synchronous_standby_names = ''; +SELECT pg_reload_conf(); +``` + +清空后同一条 INSERT 立刻返回: + +``` +sync_names=[] +INSERT 0 1 +``` + +[NOTE] +==== +`ALTER SYSTEM` 与 `SELECT pg_reload_conf();` 必须分开执行。写成一行用分号连起来会报 `ERROR: ALTER SYSTEM cannot run inside a transaction block`。 +==== + +=== `initdb` 报 `extension "uuid-ossp" is not available` 怎么办? + +Oracle 兼容模式在 initdb 的 post-bootstrap 阶段会执行 `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";`。如果这套二进制里没有 uuid-ossp 的扩展文件,初始化就会中断,并把刚建好的数据目录删掉: + +``` +performing post-bootstrap initialization ... FATAL: extension "uuid-ossp" is not available +HINT: The extension must first be installed on the system where PostgreSQL is running. +STATEMENT: -- + -- Plugin uuid-ossp + -- + CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +child process exited with exit code 1 +initdb: removing data directory "" +``` + +先确认当前安装到底有没有这个扩展(`installed_version` 为空表示可安装但没装;整行都查不到表示扩展文件根本没进 `SHAREDIR`): + +``` +$ psql -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';" + name | default_version | installed_version +-----------+-----------------+------------------- + uuid-ossp | 1.1 | 1.1 +(1 row) +``` + +在 Oracle 兼容模式的集群里,`template1` 已经带着它,新建的库会自动继承: + +``` + extname | extversion +--------------+------------ + gb18030_2022 | 1.0 + ivorysql_ora | 1.0 + plisql | 1.0 + plpgsql | 1.0 + uuid-ossp | 1.1 +(5 rows) +``` + +如果可用扩展列表里查不到 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`),但这不影响之后在需要时再装。 + +=== 源码构建时漏了 `--with-uuid` 会怎样? + +`configure` 不会报错,它只是把 uuid 支持关掉——一份不带 `--with-uuid` 的配置跑完只有这两行结果: + +``` + configure rc=0 +config.log:6635: with_uuid='no' +``` + +`configure --help` 对这一项的原文是 `--with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)`,可选值是 `bsd`、`e2fs`、`ossp`。不选任何一个时,`make` 在编译 `contrib/uuid-ossp` 时会直接撞上 `#error`: + +``` +/root/src56/contrib/uuid-ossp/uuid-ossp.c:40:2: error: #error "please use configure's --with-uuid switch to select a UUID library" +``` + +顶层 `GNUmakefile` 无条件把 `contrib/uuid-ossp` 放进 `all install`: + +``` +11:$(call recurse,all install,src config contrib/gb18030_2022 contrib/ivorysql_ora contrib/uuid-ossp contrib/ora_btree_gist contrib/ora_btree_gin) +``` + +所以整条构建在 `make` 阶段就断了,根本走不到 `make install`。要在 Oracle 兼容模式的数据目录里使用 uuid-ossp(或让 `initdb -m oracle` 能完成初始化),构建时必须带上 `--with-uuid`。 + +[TIP] +==== +不要用 `make -C contrib/uuid-ossp` 单独验证这件事:在已有构建产物的源码树里它可能因为「已是最新」而返回 0,看起来像没问题。 +==== + +=== 跑回归测试时用哪种模式? + +TAP 测试固定用 PostgreSQL 模式(`-m pg`)的模板集群,与服务器自身的模式无关。`make -C src/bin/initdb check` 会先建模板目录,再在固定端口上跑 `prove`(下面第二行为便于阅读省略了中间的环境变量赋值): + +``` +initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean '/initdb-template' +PGPORT='65432' ... prove -I ../../../src/test/perl/ -I . t/*.pl +``` + +``` +t/001_initdb.pl ............. ok +t/002_gb18030.pl ............ ok +t/003_uuid_ossp_missing.pl .. ok +All tests successful. +Files=3, Tests=86, 19 wallclock secs ( 0.04 usr 0.01 sys + 7.25 cusr 9.03 csys = 16.33 CPU) +Result: PASS +``` + +自己写 TAP 用例时,`initdb` 夹具照着这个形态写(`-m pg` + `--no-sync` + `--no-clean` + 独立 `PGPORT`)最省事,也不会与 Oracle 兼容模式的 post-bootstrap 行为耦合。 + +=== 容器不设 `IVORYSQL_PASSWORD` 为什么直接退出? + +镜像的 entrypoint 在数据目录为空时会先做初始化,而超级用户密码必须显式给出。没给就会在初始化之前退出: + +``` +Error: Database is uninitialized and superuser password is not specified. + You must specify IVORYSQL_PASSWORD to a non-empty value for the + superuser. For example, "-e IVORYSQL_PASSWORD=password" on "docker run". + + You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all + connections without a password. This is *not* recommended. +``` + +此时容器状态是 `exited exit=1`。按提示用 `-e IVORYSQL_PASSWORD=` 传入即可。提示里提到的 `POSTGRES_HOST_AUTH_METHOD=trust` 虽然也能让它启动,但等于对所有连接免密,不建议使用。 + +=== 容器默认监听哪些端口?`5866` 是什么? + +镜像默认同时监听 5432 与 1521,与裸机安装一致: + +``` +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432 +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521 +``` + +`docker inspect` 里还会看到一个 `5866/tcp`。它不是对外服务端口,而是 entrypoint 在初始化阶段临时使用的端口,并且此时只监听本机: + +``` +set -- "$@" -c listen_addresses='' -p "${PGPORT:-5866}" +``` + +初始化结束、正式启动之后,对外仍然是 5432 与 1521。做健康检查时让 `pg_isready` 指向真正的服务端口即可(镜像是 UBI 底座,没有 `ss`、`netstat`、`ps` 可用,所以容器内排查端口要靠这两个监听器自己的日志): + +``` +--health-cmd "pg_isready -p 1521 -U ivorysql" +``` + +=== `ivorysql.conf.sample` 里只出现了 4 个 `ivorysql.*` 参数,是不是只有 4 个可配? + +不是。IvorySQL 一共注册了 15 个 `ivorysql.*` 参数,样例文件里出现的是 4 个,其中 3 个被注释掉、1 个是生效行: + +``` +#ivorysql.listen_addresses = 'localhost' # what IP address(es) of Oracle mode to listen on; +#ivorysql.port = 1521 # (change requires restart) +ivorysql.enable_emptystring_to_NULL = 'on' +#ivorysql.identifier_case_switch = interchange # set the case conversion mode. range [normal,interchange,lowercase] +``` + +其余 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 个反而会让测试变红。 + +想知道某个参数为什么不在样例里,可以直接查运行时标志,凡是结果里带 `NOT_IN_SAMPLE` 的就是不会写进样例的参数: + +``` +SELECT name, pg_settings_get_flags(name) AS flags +FROM pg_settings +WHERE name LIKE 'ivorysql.%' +ORDER BY name; +``` diff --git a/EN/modules/ROOT/pages/master/contribution/faq.adoc b/EN/modules/ROOT/pages/master/contribution/faq.adoc index 3c476741..27ba9e39 100644 --- a/EN/modules/ROOT/pages/master/contribution/faq.adoc +++ b/EN/modules/ROOT/pages/master/contribution/faq.adoc @@ -56,3 +56,335 @@ At any time during the patch review, you may experience delays based on the avai ## Direct commits to the repository On occasion, you will see core team members committing directly to the repository without going through the pull request workflow. This is reserved for small changes only and the rule of thumb we use is this: if the change touches any functionality that may result in a test failure, then it has to go through a pull request workflow. If, on the other hand, the change is in the non-functional part of the codebase (such as fixing a typo inside of a comment block) core team members can decide to just commit to the repository directly. + +== Installation and Runtime FAQ + +This section collects the installation, listener, replication and container questions that come up repeatedly in the community. Every answer gives a command you can run as-is; the sample outputs were captured on IvorySQL 5.6 (PostgreSQL 18.6). + +=== Should I choose Oracle compatible mode or PostgreSQL mode? + +The mode is selected by `initdb -m` and written into the cluster's control file at initialization time. It cannot be switched afterwards by editing configuration files: `ivorysql.database_mode` is an internal parameter, it is not allowed in the configuration file, and only the control file value decides it. + +`initdb --help` documents the option as `-m, --dbmode=MODE set database mode, default is oracle`, so Oracle compatible mode is the default when `-m` is omitted; use `-m pg` for PostgreSQL mode. An invalid value is rejected outright: + +``` +$ initdb -D -m nosuchmode +unrecognized database mode. +``` + +To check which mode an existing cluster uses, read it back with `pg_controldata` (`database mode` is `1` for Oracle compatible mode and `0` for PostgreSQL mode): + +``` +$ pg_controldata -D | grep -i mode +database mode: 1 +case conversion mode: 1 +``` + +[TIP] +==== +Oracle compatible mode runs `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";` during the initdb post-bootstrap phase. Before choosing the mode, make sure your build ships uuid-ossp, otherwise initialization fails (see "What should I do when initdb reports extension "uuid-ossp" is not available" below). +==== + +=== Are 1521 and 5432 two different databases? + +No. A single postmaster opens two listeners: `port` (5432 by default, PostgreSQL protocol) and `ivorysql.port` (1521 by default, Oracle compatible protocol). Both ports point at the same data directory. In `ss` you can see both listening sockets belong to the same pid: + +``` +$ ss -ltnp | grep -E ':(1521|5432)' +LISTEN 0 200 127.0.0.1:1521 0.0.0.0:* users:(("postgres",pid=10566,fd=7)) +LISTEN 0 200 127.0.0.1:5432 0.0.0.0:* users:(("postgres",pid=10566,fd=6)) +``` + +The startup log shows them as a pair as well: + +``` +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432 +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521 +``` + +The official Docker image ships with exactly this dual-listener setup, no extra parameters required. + +=== Why is `ivorysql.compatible_mode` different on the two ports? + +Because the compatible mode is decided by the listener the client connected to, not by the database. Connecting to `port` gives `pg`; connecting to `ivorysql.port` gives `oracle`, on the same database: + +``` +---- port 5432 ---- + conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc +-----------+---------------+-----------------+------------------+----------+-------------- + 5432 | oracle | pg | localhost | 5432 | 1521 +(1 row) + +---- port 1521 ---- + conn_port | database_mode | compatible_mode | ora_listen_addrs | port_guc | ora_port_guc +-----------+---------------+-----------------+------------------+----------+-------------- + 1521 | oracle | oracle | localhost | 5432 | 1521 +(1 row) +``` + +Note that `database_mode` stays `oracle` on both connections: it is cluster-wide (it comes from the control file), while `compatible_mode` is per session. `pg_settings` shows the same split — `ivorysql.compatible_mode` has `source = override` (forced during startup) and `context = user`: + +``` +$ 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" + name | setting | source | context +---------------------------+-----------+----------+------------ + ivorysql.compatible_mode | pg | override | user + ivorysql.database_mode | oracle | override | internal + ivorysql.listen_addresses | localhost | default | postmaster + ivorysql.port | 1521 | default | postmaster + port | 5432 | default | postmaster +(5 rows) +``` + +Run the same query against 1521 and only the `ivorysql.compatible_mode` row changes to `oracle`; the other four rows are identical. + +[NOTE] +==== +`context = user` means you can `SET ivorysql.compatible_mode` for the current session, but that only affects the current session: after a reconnect the port decides again. Do not pin the mode with a session-level `SET` in your application. +==== + +=== How should the ports be configured on primary and standby nodes? + +Every node needs both `port` and `ivorysql.port`. The reason is above: the listener a client picks decides the compatible mode. If a standby only changes `port` and leaves `ivorysql.port` at the default 1521, a read-only application connecting to 1521 gets Oracle compatible mode while the same application sees PostgreSQL mode on the primary, and behavior drifts between the two. Measured settings of a primary/standby pair: + +``` +port=5532 ivorysql.port=1621 mode=pg in_recovery=false sync_names=FIRST 1 (walreceiver) sync_commit=on +port=5533 ivorysql.port=1622 mode=pg in_recovery=true ro=on +connected_on_1622 mode=oracle in_recovery=true +``` + +As long as the two listener ports differ, startup succeeds; the default 5432 + 1521 is already a correct configuration and you normally do not need either line in the configuration file. If you do change it, change only `ivorysql.port`, and it must not equal `port`: + +``` +## postgresql.conf +port = 5432 +ivorysql.port = 1522 + +$ pg_ctl -D -l -w start +waiting for server to start.... done +server started +``` + +Setting both to the same port (for example `port = 1521` while `ivorysql.port` is still the default 1521) makes startup fail: + +``` +LOG: listening on IPv4 address "127.0.0.1", port 1521 +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 +``` + +[NOTE] +==== +`pg_ctl` only prints `could not start server`; the reason is in the log. Here the listener that fails first is the Oracle one (`could not create any Oracle TCP/IP sockets`), and the HINT about "another postmaster already running" sends you in the wrong direction for this self-collision case. +==== + +=== Why is `sync_state` sometimes `sync` and sometimes `quorum`? + +It depends on how `synchronous_standby_names` is written. With the named method (`FIRST n (...)`) the named standby reports `sync`: + +``` + application_name | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag +------------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+----------------- + walreceiver | streaming | sync | 1 | 0/3000000 | 0/3000000 | 00:00:00.000093 | 00:00:00.000093 | 00:00:00.000093 +(1 row) +``` + +With the quorum method (`ANY n (*)`) the same view reports `quorum`: + +``` + pid | usename | application_name | client_addr | state | sync_state | sync_priority | sent_lsn | replay_lsn | write_lag | flush_lag | replay_lag +-----+----------+------------------+-------------+-----------+------------+---------------+-----------+------------+-----------------+-----------------+----------------- + 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 +(1 row) +``` + +So when `sync_state` is not what you expect, first check whether the primary's `synchronous_standby_names` uses the named or the quorum method, then look at `pg_stat_replication`. + +=== Writes hang after a promote. How do I troubleshoot that? + +The classic symptom: the session is `active`, `wait_event_type` is `IPC`, `wait_event` is `SyncRep`, and `statement_timeout` does not help. First check whether the promoted node still carries `synchronous_standby_names` while having no standby at all: + +``` +inherited_sync_names=[FIRST 1 (walreceiver)] +``` + +A standby created with `pg_basebackup -R` inherits the primary's `synchronous_standby_names`. After promotion that node is the primary, but there is no standby to acknowledge synchronous replication, so every commit waits forever: + +``` + pid | state | wait_event_type | wait_event | backend_xmin | query +------+--------+-----------------+------------+--------------+-------------------------------------------------------------- + 1132 | active | IPC | SyncRep | 773 | set statement_timeout='8s'; insert into sync_probe(id,note) + 1134 | active | | | 773 | select pid, state, wait_event_type, wait_event, backend_xmin +(2 rows) +``` + +Looking again after 8 seconds (the timeout should have fired) shows the same wait event. The fix is to confirm there really is no standby, then clear the synchronous replication setting: + +``` +ALTER SYSTEM SET synchronous_standby_names = ''; +SELECT pg_reload_conf(); +``` + +Once cleared, the same INSERT returns immediately: + +``` +sync_names=[] +INSERT 0 1 +``` + +[NOTE] +==== +`ALTER SYSTEM` and `SELECT pg_reload_conf();` must run as separate statements. Sending both on one line separated by a semicolon fails with `ERROR: ALTER SYSTEM cannot run inside a transaction block`. +==== + +=== What should I do when `initdb` reports `extension "uuid-ossp" is not available`? + +Oracle compatible mode runs `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";` during the initdb post-bootstrap phase. If the binaries do not ship the uuid-ossp extension files, initialization aborts and removes the data directory it just created: + +``` +performing post-bootstrap initialization ... FATAL: extension "uuid-ossp" is not available +HINT: The extension must first be installed on the system where PostgreSQL is running. +STATEMENT: -- + -- Plugin uuid-ossp + -- + CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +child process exited with exit code 1 +initdb: removing data directory "" +``` + +First check whether the installation actually has the extension (`installed_version` empty means available but not installed; no row at all means the extension files never reached `SHAREDIR`): + +``` +$ psql -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';" + name | default_version | installed_version +-----------+-----------------+------------------- + uuid-ossp | 1.1 | 1.1 +(1 row) +``` + +In an Oracle compatible cluster `template1` already carries it, and new databases inherit it: + +``` + extname | extversion +--------------+------------ + gb18030_2022 | 1.0 + ivorysql_ora | 1.0 + plisql | 1.0 + plpgsql | 1.0 + uuid-ossp | 1.1 +(5 rows) +``` + +If uuid-ossp does not appear in the available-extensions list, `CREATE EXTENSION` fails with `ERROR: 0A000: extension "uuid-ossp" is not available` and the same HINT as above. There are two ways out: use a distribution package or the official image (usually already built with the extension — run the first query above to confirm), or add `--with-uuid` when building from source (see below). A cluster initialized with `initdb -m pg` does not install this extension automatically (template1 only has `gb18030_2022` and `plpgsql`), which does not prevent installing it later when needed. + +=== What happens if a source build is missing `--with-uuid`? + +`configure` does not fail; it just turns the uuid support off. A configure run without `--with-uuid` produces exactly this: + +``` + configure rc=0 +config.log:6635: with_uuid='no' +``` + +`configure --help` documents the option as `--with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)`; the accepted values are `bsd`, `e2fs` and `ossp`. With none selected, `make` dies while compiling `contrib/uuid-ossp`: + +``` +/root/src56/contrib/uuid-ossp/uuid-ossp.c:40:2: error: #error "please use configure's --with-uuid switch to select a UUID library" +``` + +The top-level `GNUmakefile` unconditionally includes `contrib/uuid-ossp` in `all install`: + +``` +11:$(call recurse,all install,src config contrib/gb18030_2022 contrib/ivorysql_ora contrib/uuid-ossp contrib/ora_btree_gist contrib/ora_btree_gin) +``` + +So the whole build stops at the `make` stage and never reaches `make install`. To use uuid-ossp in an Oracle compatible data directory (or to let `initdb -m oracle` finish), the build must include `--with-uuid`. + +[TIP] +==== +Do not try to verify this with `make -C contrib/uuid-ossp` alone: in a source tree that already has build artifacts it may report everything up to date and return 0, which looks like success. +==== + +=== Which mode do the regression tests run in? + +The TAP tests always use a PostgreSQL mode (`-m pg`) template cluster, regardless of the server's own mode. `make -C src/bin/initdb check` first builds the template directory, then runs `prove` on a fixed port (the second line below omits the intermediate environment assignments for readability): + +``` +initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean '/initdb-template' +PGPORT='65432' ... prove -I ../../../src/test/perl/ -I . t/*.pl +``` + +``` +t/001_initdb.pl ............. ok +t/002_gb18030.pl ............ ok +t/003_uuid_ossp_missing.pl .. ok +All tests successful. +Files=3, Tests=86, 19 wallclock secs ( 0.04 usr 0.01 sys + 7.25 cusr 9.03 csys = 16.33 CPU) +Result: PASS +``` + +When writing your own TAP test, follow the same shape for the `initdb` fixture (`-m pg` + `--no-sync` + `--no-clean` + a dedicated `PGPORT`); it is the least surprising setup and does not couple your test to the Oracle compatible post-bootstrap behavior. + +=== Why does the container exit immediately when `IVORYSQL_PASSWORD` is not set? + +When the data directory is empty the image's entrypoint initializes it first, and a superuser password must be supplied explicitly. Without it the container exits before initialization: + +``` +Error: Database is uninitialized and superuser password is not specified. + You must specify IVORYSQL_PASSWORD to a non-empty value for the + superuser. For example, "-e IVORYSQL_PASSWORD=password" on "docker run". + + You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all + connections without a password. This is *not* recommended. +``` + +The container state is then `exited exit=1`. Pass the password as the message suggests, with `-e IVORYSQL_PASSWORD=`. The suggested `POSTGRES_HOST_AUTH_METHOD=trust` does make it start, but it allows every connection without a password and is not recommended. + +=== Which ports does the container listen on, and what is `5866`? + +The image listens on both 5432 and 1521 by default, just like a native installation: + +``` +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432 +2026-11-11 16:15:19.039 UTC [1] LOG: listening on IPv6 address "::", port 5432 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 1521 +2026-11-11 16:15:19.042 UTC [1] LOG: listening on IPv6 address "::", port 1521 +``` + +`docker inspect` also reports a `5866/tcp`. That is not a service port: the entrypoint uses it temporarily during initialization, and at that point it only listens locally: + +``` +set -- "$@" -c listen_addresses='' -p "${PGPORT:-5866}" +``` + +Once initialization finishes and the server starts for real, the exposed ports are still 5432 and 1521. For a health check, point `pg_isready` at the real service port (the image is UBI based and has no `ss`, `netstat` or `ps`, so inside the container you rely on the listener log lines above): + +``` +--health-cmd "pg_isready -p 1521 -U ivorysql" +``` + +=== `ivorysql.conf.sample` only mentions 4 `ivorysql.*` parameters. Does that mean only 4 are configurable? + +No. IvorySQL registers 15 `ivorysql.*` parameters. Four of them appear in the sample file — three commented out, one an active setting: + +``` +#ivorysql.listen_addresses = 'localhost' # what IP address(es) of Oracle mode to listen on; +#ivorysql.port = 1521 # (change requires restart) +ivorysql.enable_emptystring_to_NULL = 'on' +#ivorysql.identifier_case_switch = interchange # set the case conversion mode. range [normal,interchange,lowercase] +``` + +The other 11 are registered with the `GUC_NOT_IN_SAMPLE` flag (which means "do not include in postgresql.conf.sample"), so they do not show up there. This 4/11 split is enforced by CI, not an oversight: `src/test/modules/test_misc/t/003_check_guc.pl` has three assertions — the parameters that should be there must be there (`no parameters missing from postgresql.conf.sample`), and parameters carrying the flag must not be (`no parameters marked as NOT_IN_SAMPLE in postgresql.conf.sample`). Adding those 11 to the sample would therefore turn the tests red. + +To find out why a given parameter is absent from the sample, query the runtime flag directly; anything reported with `NOT_IN_SAMPLE` is a parameter that is never written to the sample: + +``` +SELECT name, pg_settings_get_flags(name) AS flags +FROM pg_settings +WHERE name LIKE 'ivorysql.%' +ORDER BY name; +```