Local Development and Testing Workflow
This page walks through the full path from source code to a submitted patch: prepare the tools, configure and build, initialize clusters in both modes, run the three tiers of tests locally, and submit the patch following the community conventions.
Every command and every terminal output on this page comes from an actual run. Steps that were not measured in this batch are called out explicitly; no output on this page is invented.
1. Scope
-
Contributors who change C code, SQL regression tests, or TAP tests.
-
Contributors who need to reproduce problems such as "Oracle-compatible mode fails during initialization".
Readers who only revise documentation do not need a build; see the Contribution Guide instead.
2. Prerequisites
2.1. Build dependencies
The package list for each distribution and its installation commands are in the Installation Guide; this page does not repeat them.
3. Building from Source
3.2. Configure
./configure --prefix=<INSTALL_DIR> --with-uuid=e2fs --enable-tap-tests
-
<INSTALL_DIR>is your choice, for example the/usr/local/ivorysql/ivorysql-5prefix used in the Installation Guide. -
--with-uuidselects the UUID library used bycontrib/uuid-ossp; the only accepted values arebsd,e2fs, andossp. -
--enable-tap-testsis the switch for TAP tests. Without it,make -C src/bin/initdb checkdoes not actually run the cases.
The relevant lines from configure --help:
--enable-debug build with debugging symbols (-g)
--enable-tap-tests enable TAP tests (requires Perl and IPC::Run)
--enable-cassert enable assertion checks (for debugging)
--with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)
--with-ossp-uuid obsolete spelling of --with-uuid=ossp
--with-ossp-uuid is the obsolete spelling of --with-uuid=ossp; do not use it in new scripts.
3.2.1. What happens if --with-uuid is omitted
configure does not fail: when the option is absent, the script simply sets the value to no.
1127:PGAC_ARG_REQ(with, uuid, [LIB], [build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)])
1128:if test x"$with_uuid" = x"" ; then
1129- with_uuid=no
1130-fi
1144: AC_MSG_ERROR([--with-uuid must specify one of bsd, e2fs, or ossp])
The price is paid during make: the translation unit contrib/uuid-ossp/uuid-ossp.c hits an #error.
38-#include <uuid/uuid.h>
39-#else
40:#error "please use configure's --with-uuid switch to select a UUID library"
41-#endif
Both the all and install goals in the top-level GNUmakefile:11 recurse into contrib/uuid-ossp unconditionally, so make stops at that #error and make install is never reached.
3.3. Build and install
make -j$(nproc)
make install
The top-level make install installs contrib as well, so the uuid-ossp control file, SQL script, and shared library all land in the installation tree.
Be careful with a core-only install: make -C src install installs only what is under src/ and never touches contrib/. The resulting installation tree has a working server, but share/postgresql/extension/ contains no uuid-ossp, so Oracle-compatible initdb is guaranteed to fail. See "Common Failures and Fixes" at the end of this page for how to install it afterwards.
4. Initializing Clusters in Both Modes
4.1. The two modes
initdb selects the database mode with -m. The accepted values are oracle and pg, and the default is oracle.
# Oracle-compatible mode (default)
initdb -D <PGDATA_ORACLE> -m oracle
# Native PostgreSQL mode
initdb -D <PGDATA_PG> -m pg
The difference shows up in the input files read during the bootstrap stage: Oracle mode additionally needs files such as postgres_oracle.bki and preload_ora_misc.sql, while pg mode uses only the native set.
4.2. How uuid-ossp relates to the two modes
Oracle mode loads the uuid-ossp extension near the end of initialization, so the installation tree must provide all three pieces: extension/uuid-ossp.control, extension/uuid-ossp—1.1.sql, and the uuid-ossp shared library under the pkglib directory. pg mode does not load it.
Measured results after deleting one file at a time from the same installation tree:
| Case | Action | Exit code |
|---|---|---|
A |
All three present, |
0 |
B |
Delete |
1 |
C |
Delete |
0 |
D |
Delete |
1 |
E |
Delete |
1 |
In short: Oracle mode hard-depends on the three pieces, pg mode does not.
The current master initdb only notices the missing extension after the bootstrap stage, at which point the data directory has already been created and is then rolled back and removed, and the message does not say which file is missing. Upstream has a change that moves the check ahead of any disk write; once merged, the failure happens before the data directory is created.
4.3. What -L actually does
initdb -L <dir> makes initdb read its own input files from <dir>; it is equivalent to overriding the internal share_path.
It does not change how extensions are resolved: CREATE EXTENSION is resolved by the post-bootstrap backend process against the compiled-in SHAREDIR. Do not use -L to "point at a temporary extension directory" in order to work around a missing extension; that only forks the input location from the real extension directory and misleads diagnosis.
5. Three Tiers of Local Testing
All three tiers must be run by a regular (non-root) user. Time cost and coverage increase from tier to tier; day-to-day work usually needs only the first one.
5.1. Tier 1: TAP tests
make -C src/bin/initdb check
This is the fastest tier; it runs only the Perl cases under src/bin/initdb/t/. Measured output (the tree used in this batch had three cases under t/; the number varies between versions):
# +++ tap check in src/bin/initdb +++
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
The fixture behind this tier is worth knowing: make first creates a template under tmp_install with
initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean <tmp_install>/initdb-template
and then runs prove on a fixed port:
PGPORT=65432 prove -I ../../../src/test/perl/ -I . t/*.pl
So the shared TAP template always uses -m pg and has nothing to do with Oracle mode; a case that wants Oracle mode has to initialize its own instance from a temporary installation tree.
5.2. Tier 2: core regression
make check
This tier runs the core pg_regress suite. It was not measured in this batch, so this page does not paste its output.
5.3. Tier 3: Oracle-compatible regression
make oracle-check-world
This tier runs the full Oracle-compatibility regression set and is considerably larger than the first two; leave it for the final round before submitting. It was also not measured in this batch, so no output is pasted here.
5.4. Notes on running the tests
-
Start with tier 1: it is the fastest and surfaces problems with the TAP infrastructure itself (
perl,IPC::Run,prove). -
Judge by
All tests successful.andResult: PASS; whenDubiousorFailedappears, open the corresponding log and work through it. -
Each tier leaves its instances and data directories under its own
tmp_check/, which can be deleted wholesale — no manual cleanup needed.
6. Submitting a Patch
6.1. Commit message style
Commit subjects in this repository follow area: imperative summary: a lowercase area name, a colon, an imperative sentence, and no trailing period. Existing commits are the reference:
initdb: fail early with an actionable error when Oracle mode lacks uuid-ossp
initdb: add TAP coverage for the Oracle mode uuid-ossp check
initdb: list every --with-uuid value in the hint and check the TAP exit status
The body should state why the change is needed, what it does, and how it was verified; the verification part should paste the commands and results that were actually run.
6.2. AI assistance disclosure
When AI tools helped write code or documentation, add both statements to the commit message:
Assisted-by: AGENT_NAME:MODEL_VERSION
Percentage of AI-generated code: xx%
AGENT_NAME is the name of the AI tool or framework and MODEL_VERSION is the specific model version, for example:
Assisted-by: Claude:4.6
Assisted-by: GitHub:Copilot
Assisted-by: OpenAI:gpt-4
One more rule: AI tools must not add Signed-off-by tags. Only a human can legally certify the Developer Certificate of Origin (DCO), so the submitter reviews all AI-generated content, adds the signature, and takes full responsibility for the contribution.
6.3. Generating and sending the patch
# Export the whole branch relative to master
git format-patch origin/master
# Export only the last commit
git format-patch -1 HEAD
The resulting .patch files can be sent as mail attachments to the mailing list, or you can push the branch to your own fork and open a Pull Request.
6.4. Sign the CLA
Code and documentation contributions require a signed Contributor License Agreement. The signing process and the two download links are in the "Sign the CLA" section of the Contribution Guide. A Pull Request from a contributor without a signed CLA cannot enter the review stage.
7. Common Failures and Fixes
| Symptom | Cause | Action |
|---|---|---|
|
|
Re-run |
|
TAP test dependencies are not installed |
Debian/Ubuntu: |
Oracle mode |
The installation tree lacks the three pieces, typically after a core-only |
|
|
It was run as root |
Re-run it as a regular user |
8. Summary
-
Pass
--with-uuidto select the UUID library and--enable-tap-teststo enable TAP. -
Only the top-level
make installinstalls contrib. -
-m oracleneeds the threeuuid-ossppieces;-m pgdoes not. -
Run
make -C src/bin/initdb checkat least once a day, and the full regression before submitting. -
Write the commit subject as
area: imperative summary, and add the two AI statements if AI tools were used.