PostgreSQL has traditionally been built using the Autotools build system (configure + make). But PostgreSQL has another type of build system named meson, a modern build system designed to improve build speed, maintainability, and developer experience.
In this article, we will explain how to build PostgreSQL 18 from source using the Meson build system. The steps below outline the complete workflow, from cloning the PostgreSQL source code to running a fully functional PostgreSQL server.
This guide is based on a practical setup performed on a Linux environment.
Cloning the PostgreSQL Source Code
The first step is to download the PostgreSQL source code from the official repository.
git clone https://git.postgresql.org/git/postgresql.git -b REL_18_STABLE postgresql
This command clones the PostgreSQL repository and checks out the REL_18_STABLE branch, which contains the PostgreSQL 18 stable source code.
After cloning, move into the project directory.
cd postgresql
You can verify the source tree using:
ls
Typical output:
aclocal.m4 build config configure configure.ac contrib COPYRIGHT doc GNUmakefile.in HISTORY Makefile meson.build meson_options.txt README.md src
Important observations:
- src/ - contains the PostgreSQL source code
- contrib/ - contains additional extensions
- meson.build - configuration file for the Meson build system
- meson_options.txt - Meson build options
The presence of meson.build indicates that PostgreSQL supports the Meson build system.
Installing the Meson Build System
Meson must be installed before starting the build process.
First, verify the installed version:
meson --version
Example output:
1.10.1
If Meson is not installed, install it using pip:
pip3 install meson
Meson works together with Ninja, which is a fast build tool used by Meson to compile the project.
Configuring the Build Directory
Meson uses a separate build directory. This keeps build files separate from source code.
Run the following command:
meson setup build
This command performs several tasks:
- Detects the compiler
- Checks system dependencies
- Generates build configuration
- Creates the build directory
Example output:
The Meson build system
Version: 1.10.1
Source dir: /home/cybrosys/postgresql
Build dir: /home/cybrosys/postgresql/build
Build type: native build
Project name: postgresql
Project version: 18.3
Meson automatically checks many dependencies such as:
- gcc compiler
- perl
- python
- flex
- bison
- openssl
- zstd
- curl
For example:
Program perl found: YES
Program python3 found: YES
Program flex found: YES
Program bison found: YES
Program openssl found: YES
Once configuration finishes, a new directory called build is created.
Exploring the Build Directory
After configuration, check the build directory.
ls build
Example contents:
build.ninja compile_commands.json config contrib doc meson-info meson-logs meson-private meson-uninstalled src
Important files:
- build.ninja - instructions used by Ninja to compile PostgreSQL
- compile_commands.json - compilation database for IDE tools
- meson-logs - build configuration logs
Building PostgreSQL
Once the configuration step is complete, PostgreSQL can be compiled using Ninja.
ninja -C build
Example output:
ninja: Entering directory `build'
[2290/2290] Linking target src/interfaces/ecpg/test/pg_regress_ecpg
This command compiles the entire PostgreSQL source code including:
- core server
- command line utilities
- extensions in contrib
You can also verify that extensions are compiled.
Example:
ls build/contrib/hstore
Output:
hstore.so.p
This indicates that PostgreSQL extensions are successfully compiled.
Installing PostgreSQL
After the compilation is finished, PostgreSQL can be installed into the system.
ninja -C build install
Result :
ninja: Entering directory `build'
[79/80] Installing files
Installing subdir /home/cybrosys/postgres_meson/src/include/access to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/gistxlog.h to /usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/rmgrlist.h to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/hash_xlog.h to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/xlogrecord.h to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/gist.h to /usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/brin_pageops.h to /usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/heapam.h to /usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/clog.h to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/tsmapi.h to/usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/tupdesc.h to /usr/local/pgsql/include/server/access
Installing /home/cybrosys/postgres_meson/src/include/access/multixact.h to/usr/local/pgsql/include/server/access
This copies the PostgreSQL binaries and libraries into:
/home/cybrosys/usr/local/pgsql
Creating the PostgreSQL System User
For security reasons, PostgreSQL should run under a dedicated user.
adduser postgres
Creating the Data Directory
PostgreSQL stores database files inside a data directory.
Create the directory:
mkdir -p /usr/local/pgsql/data
Assign ownership to the postgres user:
chown postgres /usr/local/pgsql/data
Initializing the Database Cluster
Switch to the postgres user.
su - postgres
Initialize the PostgreSQL data directory.
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
This command creates the PostgreSQL system catalog and initial database structure.
Starting the PostgreSQL Server
Start the PostgreSQL server using pg_ctl.
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
Explanation:
- -D - data directory
- -l - log file location
If the server starts successfully, PostgreSQL is ready to accept connections.
Creating a Test Database
Create a test database.
/usr/local/pgsql/bin/createdb odoo_db
Connecting to PostgreSQL
Connect using the PostgreSQL interactive terminal.
/usr/local/pgsql/bin/psql odoo_db
If the connection succeeds, the PostgreSQL server built using Meson is working correctly.
Traditional PostgreSQL Build Method
Before Meson support was introduced, PostgreSQL was typically built using Autotools.
The traditional process looks like this:
./configure
make
make install
Explanation:
- Configure detects system dependencies.
- Make compiles the source code.
- make install installs PostgreSQL.
Although this method works reliably, it has some limitations.
The traditional PostgreSQL build process uses the Autotools build system, which typically relies on the configure, make, and make install workflow. In this approach, the configuration step is handled by the configure script, which checks the system environment and dependencies before generating Makefiles. Compilation is then performed using the make tool. One limitation of this approach is that build files are usually generated within the source tree itself, which can make the project directory cluttered. Additionally, the configuration and dependency detection process can be relatively slower because it depends on shell-based scripts. While this system has been reliable for many years, the development experience can sometimes feel complex, especially for developers who frequently modify the source code and rebuild the database.
In contrast, the Meson build system provides a more modern and efficient approach for building PostgreSQL. Meson uses Ninja as its backend build tool, which is designed for high-speed incremental builds. Instead of generating build files inside the source directory, Meson creates a separate build directory, keeping the source code clean and organized. During the setup phase, Meson automatically performs dependency checks and configures the build environment in a structured way. This makes the configuration process faster and more transparent compared to the traditional method. Another advantage is that incremental builds are significantly quicker with Ninja, which improves productivity when developers repeatedly compile the source code after making changes. Overall, Meson offers a cleaner development workflow, faster build times, and a more modern build infrastructure compared to the traditional Autotools-based approach.
Key advantages of Meson:
- Faster build times
- Better dependency detection
- Cleaner build directory separation
- Easier debugging and development
Why Meson Matters for PostgreSQL Developers
For developers working with the PostgreSQL source code, the Meson build system offers significant advantages:
- Faster compilation cycles
- Easier modification of source code
- Better integration with development tools
- Improved build diagnostics
For developers who frequently modify PostgreSQL internals, Meson simplifies the build workflow and reduces development time.
Building PostgreSQL from source is essential for developers who want to explore or modify the internal database engine. With PostgreSQL 18, the Meson build system provides a modern alternative to the traditional Autotools workflow.
Using Meson with Ninja improves build performance and simplifies project configuration. This makes it especially useful for developers working with PostgreSQL internals or customizing the database engine.
By following the steps described above, PostgreSQL can be successfully compiled, installed, and executed using the Meson build system.