Getting started

This page walks through building PostgreSQL from source, running the regression tests, and starting a server. It is aimed at engineers new to the codebase, not DBAs running a production cluster — for that, see the installation chapter of the manual.

The canonical instructions live in doc/src/sgml/installation.sgml. What follows is a developer-oriented summary.

Prerequisites

Required:

• A C99 compiler (gcc or clang)
• GNU make ≥ 3.81 (or Meson + Ninja for the alternative build)
• Perl ≥ 5.14 (used during the build for code generation, and for the TAP test harness)
• A bison/yacc and flex/lex (for the grammar and scanner; bundled cached generated files mean you can sometimes skip these)
• Readline or libedit (for psql line editing)
• Zlib (for compressed dumps)

Frequently used optional dependencies:

• OpenSSL — for SSL/TLS support and pgcrypto
• ICU — for collation support (mandatory in recent versions)
• LLVM — for JIT'd expression evaluation
• libxml2, libxslt — for XML support
• Python, Perl, Tcl headers — for PL/Python, PL/Perl, PL/Tcl
• liburing — for the io_uring AIO method (Linux)

On Debian/Ubuntu, sudo apt-get build-dep postgresql-15 (or whichever version) pulls in roughly the right set.

Configure and build (autoconf flow)

./configure --prefix=$HOME/pgsql --enable-debug --enable-cassert --enable-tap-tests
make -j$(nproc)
make install

Useful configure flags for development:

Flag	Effect
--enable-debug	Build with -g.
--enable-cassert	Enable Assert() checks. Worth the cost during development.
--enable-tap-tests	Build the Perl-based TAP test infrastructure.
--with-llvm	Build the JIT layer.
--with-icu	ICU collation support.
--with-openssl	SSL/TLS.
CFLAGS="-Og -ggdb3"	Decent debugging optimization.

./configure --help prints the full list. Generated files end up in the source tree itself; out-of-tree builds are also supported with mkdir build && cd build && ../configure.

Configure and build (Meson flow)

PostgreSQL also ships a Meson build that produces the same artifacts. It is faster for incremental builds and is the recommended path for new contributors on Linux/macOS.

meson setup build --prefix=$HOME/pgsql -Dcassert=true -Ddebug=true
ninja -C build
ninja -C build install

Configure flags map onto -D options. See meson_options.txt in the repo root for the full list. The Meson and autoconf builds must stay in sync; if you add a new .c file, add it to both Makefile and meson.build in that directory.

Initialize and start a cluster

After install, create a data directory and start the server:

$HOME/pgsql/bin/initdb -D $HOME/pgdata
$HOME/pgsql/bin/pg_ctl -D $HOME/pgdata -l logfile start
$HOME/pgsql/bin/createdb mydb
$HOME/pgsql/bin/psql mydb

initdb lays down the system catalogs and on-disk layout. pg_ctl is a wrapper that starts/stops the postmaster and tails the log. See pg_ctl and src/bin/pg_ctl/.

Running tests

PostgreSQL has three main test suites, all driven by make check variants.

Core regression tests. SQL scripts whose output is diffed against expected files. Lives under src/test/regress/.

make check                  # in-tree, builds a temp cluster
make check-world            # everything: core + contrib + TAP

A regression failure produces a regression.diffs file showing the unexpected output.

TAP tests. Perl scripts (*.pl) that exercise multi-process scenarios — replication, recovery, pg_dump round-trips, authentication, etc. They use the harness in src/test/perl/PostgreSQL/Test/. Run individually:

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

TAP tests need --enable-tap-tests at configure time.

Isolation tests. Driven by src/test/isolation/, these run multiple sessions concurrently to test for race conditions, locking behavior, and transaction visibility. Each test specifies a permutation — an explicit interleaving of session steps.

make check -C src/test/isolation

For more on the test infrastructure, see Testing.

A typical edit/build/test loop

1. Edit a backend file (e.g., add a new GUC in src/backend/utils/misc/guc_tables.c).
2. ninja -C build (or make -j).
3. make install if you want the change in your installed prefix; otherwise the in-tree make check rebuilds and tests against the build tree.
4. make check for fast core-regression coverage.
5. For multi-process changes: make check -C src/test/recovery or wherever the relevant TAP suite lives.
6. Before posting a patch: make check-world, run pgindent, regenerate typedefs.list if needed.

Repository layout

The source tree is organized roughly like this:

postgres/
├── src/
│   ├── backend/        # the server (postmaster + backends)
│   ├── bin/            # frontend command-line tools (psql, pg_dump, ...)
│   ├── common/         # code shared between frontend and backend
│   ├── fe_utils/       # frontend-only utility code (used by src/bin)
│   ├── include/        # public + internal headers
│   ├── interfaces/     # client libraries (libpq, ecpg)
│   ├── pl/             # procedural languages (plpgsql, plperl, plpython, pltcl)
│   ├── port/           # platform abstraction
│   ├── test/           # regression, isolation, TAP, modules
│   └── tools/          # developer tools (pgindent, msvc helpers, ...)
├── contrib/            # optional first-party extensions (pg_stat_statements, postgres_fdw, ...)
├── doc/                # SGML documentation source
├── config/             # autoconf helpers
└── meson.build         # top-level Meson build

For a pointer to each subsystem's wiki page see Systems.