Skip to content

Commit 2c04965

Browse files
committed
docs(installation): note the uuid-ossp requirement for Oracle mode initdb
Oracle-compatible initialization installs the uuid-ossp extension, so a cluster cannot be initialized when the extension is missing. The failure surfaces halfway through initdb, after the data directory has been created, and initdb then removes that directory again -- which is easy to misread as a disk or permission problem. Document the prerequisite where the initdb command is given, together with the one-line check that tells whether the current installation has it, the configure option a source build needs, and the -m pg escape hatch. Per the maintainer's preference in #3192, this is handled as documentation rather than as an additional check inside initdb. Assisted-by: DSH:deepseek-v4.1 Percentage of AI-generated code: 100%
1 parent 7d4ad9d commit 2c04965

2 files changed

Lines changed: 20 additions & 0 deletions

File tree

‎CN/modules/ROOT/pages/master/installation_guide.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,16 @@ $ initdb -D /usr/ivory-5/data
184184
....
185185
其中-D参数用来指定数据库的数据目录。更多参数使用方法,请使用initdb --help命令获取。
186186
....
187+
[NOTE]
188+
====
189+
`initdb` 默认按 Oracle 兼容模式初始化(等价于 `-m oracle`),该模式会在初始化阶段安装 `uuid-ossp` 扩展。若系统上找不到该扩展,`initdb` 会因 `FATAL: extension "uuid-ossp" is not available` 失败,并删除刚创建的数据目录。
190+
191+
- 用社区发布的 rpm 或 deb 包安装时通常无需额外操作;如不确定,先用下面的语句自检。
192+
- 从源码构建时,必须在配置阶段显式指定 UUID 库,例如 `./configure --prefix=/usr/local/ivorysql/ivorysql-5 --with-uuid=e2fs`。漏掉该参数时 `configure` 不会报错,但 `make` 会在 `contrib/uuid-ossp` 处因 `#error "please use configure's --with-uuid switch to select a UUID library"` 中断。
193+
- 自检语句:`SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';`,正常结果应包含 `uuid-ossp | 1.1 | 1.1`。
194+
- 如确实需要在不带该扩展的情况下初始化,可显式使用 PG 模式:`initdb -D /usr/ivory-5/data -m pg`(PG 模式不安装该扩展)。
195+
====
196+
187197

188198
** 启动数据库服务
189199

‎EN/modules/ROOT/pages/master/installation_guide.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,16 @@ $ initdb -D /usr/ivory-5/data
186186
187187
For more options, refer to initdb --help.
188188
....
189+
[NOTE]
190+
====
191+
By default `initdb` initializes the cluster in Oracle-compatible mode (the same as `-m oracle`), and that mode installs the `uuid-ossp` extension during initialization. If the extension is not available on the system, `initdb` fails with `FATAL: extension "uuid-ossp" is not available` and removes the data directory it has just created.
192+
193+
- Installing from the community rpm or deb package usually requires no extra step; if you are unsure, run the check below first.
194+
- When IvorySQL is built from source, the UUID library must be selected at configuration time, for example `./configure --prefix=/usr/local/ivorysql/ivorysql-5 --with-uuid=e2fs`. Without that option `configure` still succeeds, but `make` stops in `contrib/uuid-ossp` with `#error "please use configure's --with-uuid switch to select a UUID library"`.
195+
- Check: `SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';` should report `uuid-ossp | 1.1 | 1.1`.
196+
- If initialization really has to run without the extension, request PG mode explicitly: `initdb -D /usr/ivory-5/data -m pg`, which does not install it.
197+
====
198+
189199

190200
** Starting IvorySQL service
191201

0 commit comments

Comments
 (0)