Skip to content

initdb: Oracle-compatible mode fails with an opaque extension error when contrib/uuid-ossp is missing #3192

Open

Description

@qwer381

Summary

initdb in IvorySQL defaults to Oracle-compatible mode, and Oracle-compatible mode runs
CREATE EXTENSION IF NOT EXISTS "uuid-ossp" while template1 is being built. If the installation does
not contain contrib/uuid-ossp — which is what an ordinary ./configure && make && make install
produces, because configure defaults to --with-uuid=no — initialization aborts after the cluster
has been built, reports an extension-level error that never mentions the missing module, and then
deletes the data directory it just created.

Nothing about the cluster survives the failure, and the last line of output tells the user about the
wrong layer of the problem.

Steps to reproduce

The quickest deterministic reproduction is to take the extension away from an existing 5.6 installation
(this is exactly the state a default build leaves behind):

PREFIX=/opt/ivory56            # any IvorySQL 5.6 installation
CTL="$PREFIX/share/postgresql/extension/uuid-ossp.control"

# 1. Simulate an installation that has no contrib/uuid-ossp
mv "$CTL" "$CTL.hidden"

# 2. Initialize a cluster.  -m oracle is the default; omitting -m does the same thing.
"$PREFIX/bin/initdb" -D /tmp/uuidtest -m oracle
echo "exit=$?"                 # exit=1

# 3. Nothing is left behind
ls -d /tmp/uuidtest            # ls: cannot access '/tmp/uuidtest': No such file or directory

# 4. Restore the installation
mv "$CTL.hidden" "$CTL"

Control group — the same missing file, PG mode instead of Oracle mode:

mv "$CTL" "$CTL.hidden"
"$PREFIX/bin/initdb" -D /tmp/uuidpg -m pg
echo "exit=$?"                 # exit=0, "Success. You can now start the database server using: ..."
mv "$CTL.hidden" "$CTL"

So the dependency is introduced by the Oracle path only; a PostgreSQL-mode cluster is unaffected by
the very same missing files.

The reason the extension is missing in the first place is a build default, not a broken installation:

$ ./configure                  # no --with-uuid
$ grep -n 'uuid' contrib/Makefile
64: ifneq ($(with_uuid),no)
65: SUBDIRS += uuid-ossp
67: ALWAYS_SUBDIRS += uuid-ossp

configure:9026-9027 sets with_uuid=no when the option is not given, and
src/Makefile.global.in:24 / :28 make the ordinary targets recurse into ALWAYS_SUBDIRS only for
clean / distclean. A plain make && make install therefore never builds or installs
contrib/uuid-ossp, while initdb defaults to the mode that requires it:
"standard build + default initdb" fails every time.

Actual output

stdout stops in the middle of a step that looks like it is succeeding:

creating directory /tmp/uuidtest ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... posix
selecting default "max_connections" ... 100
selecting default "shared_buffers" ... 128MB
selecting default time zone ... Asia/Shanghai
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... 

stderr, verbatim:

2026-11-10 22:30:25.181 CST [9302] FATAL:  extension "uuid-ossp" is not available
2026-11-10 22:30:25.181 CST [9302] HINT:  The extension must first be installed on the system where PostgreSQL is running.
2026-11-10 22:30:25.181 CST [9302] STATEMENT:  --
	-- Plugin uuid-ossp
	--
	CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
	
child process exited with exit code 1
initdb: removing data directory "/tmp/uuidtest"

Exit status is 1, and /tmp/uuidtest does not exist afterwards.

Three ways to be incomplete, three different messages

Hiding one file at a time changes the message but not the outcome:

State Message Cluster built? Directory removed?
uuid-ossp.control missing FATAL: extension "uuid-ossp" is not available yes yes
uuid-ossp--1.1.sql missing FATAL: extension "uuid-ossp" has no installation script nor update path for version "1.1" yes yes
uuid-ossp.so missing FATAL: could not access file "uuid-ossp": No such file or directory, with CONTEXT: SQL statement "CREATE FUNCTION uuid_nil() ... AS '$libdir/uuid-ossp', 'uuid_nil' ..." / extension script file "uuid-ossp--1.1.sql", near line 6 yes yes

All three end with child process exited with exit code 1 and
initdb: removing data directory "...".

For the record, because it is easy to report the wrong string:
could not open extension control file "..." is emitted only when the control file exists but cannot
be read
(extension.c:684-697, e.g. wrong permissions). A control file that is simply absent takes
the extension.c:668-674 path and produces extension "uuid-ossp" is not available. The text above is
copied from actual runs, not from reading the source.

Why the message is not actionable

  1. It describes the epilogue, not the cause. initdb: removing data directory "..." is the last line,
    so it reads like the primary error, but it is initdb cleaning up after a failure that happened one
    layer down (cleanup_directories_atexit(), initdb.c:777-823, message at :787). The user's
    takeaway is "initdb deleted my data directory", not "my installation is missing an extension".
  2. It does not name the deliverable. The hint comes from the generic extension machinery
    (extension.c:668-674) and says the extension "must first be installed on the system", without
    saying that it ships in contrib/uuid-ossp, that it is only built when the tree is configured with
    --with-uuid=ossp, or what command installs it.
  3. It does not connect the extension to Oracle mode. The requirement is introduced by
    contrib/ivorysql_ora/preload_ora_misc.sql:22, yet nothing in the output mentions Oracle
    compatibility, so a user has no reason to suspect the database mode — especially since -m pg on
    the same machine works.
  4. It arrives after all the expensive work is already done. By the time the message is printed, bootstrap has completed and
    the whole cluster has been written (--no-sync), and it is then deleted. There is no --no-clean-ish
    switch that keeps the wreckage for inspection.
  5. FATAL instead of ERROR makes it look like a server-level failure. The post-bootstrap backend is
    started as --single ... -c exit_on_error=true (initdb.c:239), and elog.c:375-381 promotes
    ERROR to FATAL whenever ExitOnAnyError is set, so a plain SQL error in an init script kills the
    whole run.

Source anchors (5.6 tree; master has the same layout a few lines away)

Location What it does
src/bin/initdb/initdb.c:214 static char *dbmode = "oracle"; — Oracle mode is the default
src/bin/initdb/initdb.c:216 static int database_mode = DB_ORACLE;
src/bin/initdb/initdb.c:2684 -m, --dbmode=MODE set database mode, default is oracle
src/bin/initdb/initdb.c:3500-3511 -m parsing: pg/0 → DB_PG, oracle/1 → DB_ORACLE
src/bin/initdb/initdb.c:2946-2950 DB_ORACLE selects ivorysql.conf.sample and preload_ora_misc.sql
src/bin/initdb/initdb.c:2978-2982 DB_ORACLE calls check_input() on both — the existing, side-effect-free check pattern
src/bin/initdb/initdb.c:3211 create_data_directory() — everything before this point writes nothing
src/bin/initdb/initdb.c:3311-3316 DB_ORACLE runs setup_run_file(cmdfd, preload_ora_misc)
src/bin/initdb/initdb.c:1820-1835 setup_run_file() just pipes the SQL text into the child backend, unvalidated
src/bin/initdb/initdb.c:239 --single ... -c exit_on_error=true
src/bin/initdb/initdb.c:777-823, :787 cleanup_directories_atexit() → rmtree(pg_data) + removing data directory
contrib/ivorysql_ora/preload_ora_misc.sql:22 CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; — the crash site
src/backend/commands/extension.c:668-674 extension "%s" is not available + the generic hint
src/backend/utils/error/elog.c:375-381 ExitOnAnyError promotes ERROR to FATAL
configure:9026-9027 with_uuid=no when --with-uuid is not given
contrib/Makefile:64-68 uuid-ossp goes to SUBDIRS or to ALWAYS_SUBDIRS
src/Makefile.global.in:24, :28 ordinary targets recurse into ALWAYS_SUBDIRS only for clean/distclean

Full failure sequence:

setup_data_file_paths()          only confirms preload_ora_misc.sql exists
create_data_directory()          PGDATA is born (made_new_pgdata = true)
bootstrap_template1()            bootstrap succeeds
postgres --single -c exit_on_error=true template1
  setup_run_file(preload_ora_misc)
    CREATE EXTENSION IF NOT EXISTS "uuid-ossp"      preload_ora_misc.sql:22
      find_in_paths() finds no uuid-ossp.control    extension.c:4029
        ereport(ERROR "extension ... is not available")
          ExitOnAnyError -> FATAL                   elog.c:378-380
  pclose_check() -> child process exited with exit code 1
exit(1) -> cleanup_directories_atexit() -> rmtree(PGDATA)

Suggested fixes

1. Check the extension before anything is written (preferred). Declare the dependency in the
DB_ORACLE branch of setup_data_file_paths() and check it there, next to the existing
check_input() calls, which already run before create_data_directory():

if (database_mode == DB_ORACLE)
{
    check_input(ora_conf_file);
    check_input(preload_ora_misc);
    check_oracle_extensions();   /* new: uuid-ossp.control, uuid-ossp--1.1.sql, uuid-ossp.so */
}

The check covers three files, because all three are genuinely required (CREATE EXTENSION resolves the
control file and the version script, and the backend loads the shared library as soon as the script
creates its first C function — see the could not access file case above). Reporting goes through
pg_log_error() / pg_log_error_detail() / pg_log_error_hint(), i.e. the same machinery as the
neighbouring check_input(), and names the file that is missing plus the command that installs it:

initdb: error: Oracle-compatible mode requires the "uuid-ossp" extension, but this installation is incomplete:
initdb: detail: missing file "/opt/ivory56/share/postgresql/extension/uuid-ossp.control"
initdb: hint: The "uuid-ossp" extension is provided by contrib/uuid-ossp and is only built when the source tree is configured with --with-uuid=ossp.  Run "make -C contrib/uuid-ossp install", or reconfigure and reinstall, and then try again.  To initialize a cluster without Oracle compatibility, use "-m pg" (or "--dbmode=pg") instead.

This keeps the failure side-effect free (no directory is created, so none is removed) and leaves the
-m pg path untouched.

2. Do not delete the half-built directory (complementary, separate PR). Keeping the wreckage — or at
least saying "rolled back" instead of "removing data directory" — helps every post-bootstrap failure, not
just this one, but it reverses a long-standing upstream behaviour and would need its own discussion.

3. Make uuid-ossp best-effort inside preload_ora_misc.sql (bigger semantic change). Lines 1-17 of
that file (dual, sys.rowid, sys.urowid, two CREATE CASTs) do not use any uuid function, and the
comment above line 22 calls it a "Plugin", so Oracle-mode core objects do not depend on it. Wrapping
the statement in a DO block that warns instead of raising would let Oracle-mode clusters be created
without the extension, but it changes what Oracle mode is supposed to contain, and WHEN OTHERS would
have to be narrowed to specific SQLSTATEs to avoid swallowing real errors.

4. Stop losing contrib/uuid-ossp at build time (root cause). Either make --with-uuid default to a
usable implementation or keep uuid-ossp in the ordinary SUBDIRS; both change upstream PostgreSQL
defaults and are worth discussing separately.

Fix Removes the deletion Fixes the message Size Risk
1. pre-flight check yes yes small (62 lines + 1 test) low
2. keep the directory partly no medium high (changes existing semantics)
3. best-effort extension yes yes medium medium (semantic change)
4. build-side default prevents it — medium high (upstream defaults)

Expected behaviour

  • initdb -m oracle on an installation without contrib/uuid-ossp should fail before creating the
    data directory, name uuid-ossp, name the missing file, and name the fix; nothing should be created
    and therefore nothing removed.
  • initdb -m pg should keep succeeding with the same missing files.
  • A complete installation should behave byte-for-byte as it does today.
  • Regression coverage worth having: -m oracle with a hidden control file → the new error, exit 1,
    PGDATA never created; -m pg with the same hidden file → success.

Impact

Anyone who builds IvorySQL the documented way (./configure && make && make install, no --with-uuid)
and then runs initdb — with or without -m, since Oracle mode is the default — cannot create a
cluster at all, and the only line that looks actionable points at the data directory rather than at the
installation. Packagers that trim contrib hit the same wall. Existing clusters are unaffected; the bug
is limited to initialization.

Environment

  • IvorySQL 5.6 (= PostgreSQL 18.6 (IvorySQL 5.6) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit)
  • Ubuntu 24.04 on WSL2, built from the 5.6 source tree with
    --prefix=/opt/ivory56 --with-libxml --with-openssl --with-icu --without-ldap --without-selinux --without-systemd
  • uuid-ossp present in the installation for the control group, temporarily hidden for the failing runs,
    then restored (hashes re-checked afterwards)

Activity

  1. qwer381 commented on Nov 10, 2026

    @qwer381
    Author

    Related but distinct from #979: that issue asks for uuid-devel / uuid-ossp to be added to the source-installation dependency documentation, so that people stop hitting the missing extension at all. This issue is about what initdb does when it is missing, in the default (Oracle-compatible) mode: the FATAL is raised only after the cluster has been built, cleanup_directories_atexit() then removes the whole data directory, and neither the message nor the hint names contrib/uuid-ossp or the configure default (--with-uuid=no) that silently drops it from an ordinary make && make install. Fixing #979 would reduce how often this is hit; it would not change the diagnostic. The PR that follows only moves the check in front of create_data_directory() and does not install anything.

  2. added a commit that references this issue on Nov 10, 2026
    3e213ca
  3. himmel001 commented on Nov 11, 2026

    @himmel001

    Thanks for contributing to IvorySQL!

  4. bigplaice commented on Nov 11, 2026

    @bigplaice
    Collaborator

    @qwer381
    But in which case the contrib/uuid-ossp will be missing?
    If user builds IvorySQL from source code, configure without --with-uuid will fail.
    While the package provided by community contains uuid extension.

    Thanks,
    Steven

  5. qwer381 commented on Nov 11, 2026

    @qwer381
    Author

    Thanks Steven — I went back to the 5.6 tree and checked both points instead of arguing from memory, and you are right.

    Source builds. ./configure without --with-uuid does not fail (configure.ac:1088 sets with_uuid=no), but the build cannot complete: contrib/uuid-ossp/uuid-ossp.c:40 stops it with

    error: #error "please use configure's --with-uuid switch to select a UUID library"
    

    and GNUmakefile:11 recurses into contrib/uuid-ossp for both all and install, so make dies there and make install never runs. A source install that omits the switch therefore cannot end up with a server lacking the extension — it ends up with no installation at all.

    Packages. Agreed — the 5.6 release ships one rpm and one deb per architecture (~200 MB each), not a split -contrib package, so the extension comes with the server.

    So the honest residue is narrow, and none of it is the standard path: make -C src install (core only), a DESTDIR/prefix mix-up, a downstream distribution that re-packages extensions separately, or an interrupted/partial copy where the control file is present but the version script or the .so is not. In those cases unpatched initdb creates $PGDATA, fails with FATAL: extension "uuid-ossp" is not available, and then removes the directory; the patch only turns that into a pre-flight message naming the files it looked for. It is defence in depth, not coverage of a common mistake.

    Given that, what would you prefer?

    1. Keep initdb: fail early with an actionable error when Oracle mode lacks uuid-ossp #3193 as is — it is a handful of stat() calls, skipped entirely for -m pg, and since 3e213ca it no longer misfires with -L; TAP coverage for the three states is in ece82b8 / 27b76d5.
    2. Close initdb: fail early with an actionable error when Oracle mode lacks uuid-ossp #3193, and let me send a docs PR instead. The docs never state that Oracle-compatible mode needs the uuid-ossp extension at initdb time: 6.3.10 only says sys_guid() reuses the plugin, and the installation page lists uuid-devel / libossp-uuid-dev as build dependencies only. One or two sentences there would cover the gap that actually exists.
    3. Narrow the check to whatever you consider reachable — name the state and I will wire it.

    I am fine with (2) if you think the window is too small to justify a code path in initdb.

  6. bigplaice commented on Nov 12, 2026

    @bigplaice
    Collaborator

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

  7. qwer381 commented on Nov 12, 2026

    @qwer381
    Author

    Handled per option 2 — thanks for the quick call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions