Development workflow

This page is a hands-on description of the inner loop: how to make a change, build, test, and prepare a patch for posting.

Branching

PostgreSQL development happens on master. Bug fixes are backpatched to the supported REL_NN_STABLE branches, but those branches are maintained by committers only — non-committers do not push to them. As a contributor, base everything on master.

git fetch origin
git checkout master
git rebase origin/master
git checkout -b my-feature

Quick build cycle

For day-to-day editing, use an in-tree autoconf build with assertions enabled. It's fast enough for an incremental loop and you don't need to install:

./configure --enable-debug --enable-cassert --enable-tap-tests CFLAGS="-Og -ggdb3"
make -j$(nproc)
make check                  # runs core regression

Or the Meson equivalent:

meson setup build -Dcassert=true -Ddebug=true
ninja -C build
meson test -C build

The --enable-cassert (Meson: -Dcassert=true) flag is important — it turns on Assert() macros throughout the backend. Many bugs surface only with assertions on. It is more or less required for development; never benchmark a build with assertions on.

Editing a backend file

A typical change to backend code:

1. Edit the .c/.h file.
2. make -j (or ninja -C build). The build dependency graph is comprehensive; touch a header and only the files that actually use it rebuild.
3. If you added a new file, add it to both the Makefile (in the OBJS list) and the meson.build in the same directory (in the backend_sources_list or equivalent).
4. If you added a new typedef, run src/tools/find_typedef and update src/tools/pgindent/typedefs.list.

Editing the catalog

Adding or modifying a system catalog table or a built-in function is a more elaborate ritual:

• Catalog headers live in src/include/catalog/pg_*.h with annotation comments (/* OIDS */, /* === */) read by genbki.pl.
• Built-in function entries in src/include/catalog/pg_proc.dat.
• Built-in operator entries in src/include/catalog/pg_operator.dat.
• Etc.

To assign a new OID to a manually-pinned object, run:

./src/include/catalog/unused_oids

Pick one of the listed unused OIDs and use it. For automatically assigned OIDs (≥ 12000), just leave oid out of the .dat entry.

After editing .dat files, the next make regenerates postgres.bki, pg_proc_d.h, and friends. You also need a fresh data directory:

make install
initdb -D /tmp/pgdata2     # the old one's catalog is now stale

Editing the parser

src/backend/parser/gram.y is the bison grammar. Adding new SQL syntax usually involves:

1. New terminal/non-terminal in gram.y.
2. New Node type in src/include/nodes/parsenodes.h (the support functions are auto-generated).
3. Parse-analysis code in src/backend/parser/analyze.c (or a parse_*.c file).
4. Planner support if it's a new query shape; executor support if it's a new statement.

Bison output (gram.c, gram.h) is regenerated automatically. Touching gram.y causes a slow rebuild — ten to fifteen seconds on a modern machine.

Documentation

User-visible changes need documentation. Documentation source lives under doc/src/sgml/ in DocBook SGML.

make -C doc/src/sgml all

Builds HTML, man pages, and (optionally) PDF. The output lands in doc/src/sgml/html/. Open doc/src/sgml/html/index.html in a browser to preview.

Posting a patch

After your change builds and make check-world passes:

git format-patch master
git format-patch -v2 master   # for the second iteration

Attach the resulting .patch file(s) to an email to pgsql-hackers. Include:

• A subject line that summarizes the change.
• A short rationale.
• Notes on testing performed.

Reply on the same thread when you post a new revision — keeping the conversation linear is part of the workflow.

Register the patch on the commitfest at https://commitfest.postgresql.org/ to get it into the review queue.

Reviewing other people's patches

Reviewing is the fastest way to learn the codebase and the most-needed contribution. The standard workflow:

git checkout -b review/feature-x master
git apply /path/to/feature-x-v3.patch
make -j check-world

Read the patch, write feedback (correctness, style, performance, doc completeness), reply to the thread. If it looks committable, say so. If it needs work, mark it "Waiting on Author" in the commitfest app.

Debugging a regression failure

When make check fails, the unexpected output diff lives in:

src/test/regress/regression.diffs
src/test/regress/results/<failing_test>.out

Compare to src/test/regress/expected/<failing_test>.out to see what changed. The temp cluster is left running on the temporary port make check chose; you can psql -p <port> against it for ad-hoc poking.

For TAP tests:

cd src/test/recovery
make check PROVE_TESTS='t/001_stream_rep.pl' PROVE_FLAGS='-v'

Failed TAP tests leave their tmp data directories under tmp_check/ for inspection.