Skip to content

docs(installation): note the uuid-ossp requirement for Oracle mode initdb - #392

Open
qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/installation-uuid-ossp
Open

qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/installation-uuid-ossp

Conversation

@qwer381

@qwer381 qwer381 commented Nov 12, 2026 •

Copy link
Copy Markdown

Closes IvorySQL/IvorySQL#3192

What this changes

Documents, in the installation guide, that Oracle-compatible initialization needs the uuid-ossp extension — and what to do when it is not there.

Two files, 10 added lines each, no deletions:

File Change
CN/modules/ROOT/pages/master/installation_guide.adoc +10 −0
EN/modules/ROOT/pages/master/installation_guide.adoc +10 −0

The note is placed in == Start Database → ** Initializing database, right after the initdb command — the only place in the page where initdb appears, and where the requirement is actually hit.

Why documentation, not a check in initdb

In IvorySQL/IvorySQL#3192 the maintainer preferred option 2:

I perfer to the option 2, as the PR #3193 is too specific.

So instead of adding a pre-flight check to initdb (IvorySQL/IvorySQL#3193, closed), the requirement is stated where users configure and initialize a cluster. The branch behind IvorySQL/IvorySQL#3193 (fix/initdb-uuid-ossp-diagnostic) is kept, including the -L handling fix and the TAP case, should it ever be wanted.

What the note says

  • initdb defaults to Oracle-compatible mode (same as -m oracle), and that mode installs uuid-ossp during initialization; if the extension is unavailable, initdb fails with FATAL: extension "uuid-ossp" is not available and removes the data directory it just created.
  • When building from source, the UUID library must be selected at configuration time (./configure ... --with-uuid=e2fs); without it configure still succeeds but make stops in contrib/uuid-ossp with #error "please use configure's --with-uuid switch to select a UUID library".
  • A one-line check to run before initializing: SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'uuid-ossp';
  • If initialization must run without the extension, initdb ... -m pg is the way (PG mode does not install it).

How this was verified

  • git apply --check, git apply, git apply --check -R against 7d4ad9d: all exit 0.
  • Rendered with @asciidoctor/core 4.2.1: heading/table/listing counts unchanged from the current page (h2=9, table=7, pre=29), 0 warnings, the [NOTE] renders as a single admonitionblock note with no literal [NOTE] left behind.
  • The initdb failure text and the #error text were both taken from runs of PostgreSQL 18.6 (IvorySQL 5.6): an Oracle-mode initdb without the extension, and a build configured without --with-uuid.
  • The check statement was run on a freshly initialized Oracle-mode instance: uuid-ossp | 1.1 | 1.1; on a -m pg instance the same query finds the extension available but not installed.
  • Cross-checked against #350, the only other open PR touching this file (deb package names, lines 140–152): both merge orders apply cleanly.

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)

…itdb

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.
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381
qwer381 force-pushed the docs/installation-uuid-ossp branch from 2c04965 to d50f9e3 Compare November 13, 2026 05:53
@github-actions
github-actions Bot temporarily deployed to pull request November 13, 2026 05:57 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

This branch was previously deployed

1 inactive deployment
pull request — d50f9e33 Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant