1. Overview

When verifying PostgreSQL patches on MacOS, I couldn’t find a straightforward blog to follow for setting up the environment quickly. This blog aims to document the steps I took to set up a PostgreSQL development environment on MacOS (verified on Apple Silicon M2). I hope it will be helpful for others when facing a similar task.

2. Installing Homebrew

To build PostgreSQL, certain tools and libraries need to be installed. If these are not managed by the default MacOS installation, a third-party package manager like Homebrew can be used. This blog will guide you through the steps of installing Homebrew and the necessary tools and libraries required to compile PostgreSQL and run make check-world tests.

To install Homebrew, open a terminal and execute the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions to complete the installation. Once installed, add Homebrew to your PATH by running the provided commands in the terminal.

Additionally, you need to install Apple’s command line developer tools by running xcode-select --install. This will open a GUI dialog window to complete the installation.

3. Installing Tools and Libraries with Homebrew

To install the necessary tools and libraries using Homebrew, execute the following commands in the terminal:

% brew install git

If you encounter an error related to running under Rosetta 2 in ARM, use the arch -arm64 prefix with Homebrew commands. For example:

% arch -arm64 brew install git

Install the icu4c library, otherwise you can use –without-icu during configure step.

% arch -arm64 brew install icu4c

To have icu4c in your PATH, add the following lines to your ~/.zshrc file:

export PATH="/opt/homebrew/opt/icu4c/bin:$PATH"
export PATH="/opt/homebrew/opt/icu4c/sbin:$PATH"

For compilers to find icu4c, set the following environment variables:

export LDFLAGS="-L/opt/homebrew/opt/icu4c/lib"
export CPPFLAGS="-I/opt/homebrew/opt/icu4c/include"

Finally, install pkg-config and update the PKG_CONFIG_PATH:

% arch -arm64 brew install pkg-config
% export PKG_CONFIG_PATH="/opt/homebrew/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"

4. Compiling PostgreSQL and Running Tests

Clone the PostgreSQL repository from github:

% git clone https://github.com/postgres/postgres.git
% cd postgres

Configure and compile PostgreSQL with default configuration settings:

% ./configure
% make -j

To run the the basic tests, use the following command:

% make check

If see an error with some information similar to dyld[69058]: Library not loaded: during make check testing, then you need to workaround this issue by installing PostgreSQL once either sudo make install if you use default prefix during configure process or make install if you specified the prefix pointing to your directory.

If your make check passed all the test cases, then it is time to run additional tests, including TAP tests, consider enabling --enable-tap-tests during the configure process. For example:

% ./configure --enable-tap-tests
% make -j
% make check-world

If you encounter errors due to missing Perl modules, you can install them from CPAN. Below is the example I used to install the missing perl modules on my MacOS:

% sudo perl -MCPAN -e 'install Bundle::CPAN'
% sudo perl -MCPAN -e 'install IPC::Run'
% sudo perl -MCPAN -e 'install Test::Harness'
% sudo perl -MCPAN -e 'install Test::Simple'
% sudo perl -MCPAN -e 'install Time::HiRes'

Alternatively, you can install perlbrew locally and manage your Perl modules separately.

To install the latest Perl 5.36, execute the following commands:

% \curl -L https://install.perlbrew.pl | bash
% source ~/perl5/perlbrew/etc/bashrc
% perlbrew --notest install perl-5.36.1

Once perlbrew and perl are installed, update your shell’s configuration file to use the local Perl modules. For example, add the following lines to your ~/.bashrc:

# Load perlbrew
source $HOME/perl5/perlbrew/etc/bashrc

# Set the desired Perl version
perlbrew switch perl-5.36.1

And include the following line in your ~/.zshrc file if you want to persist the setup for all terminals.

source ~/.bashrc

When you want to switch back to the system Perl that comes with MacOS, remove the source ~/.bashrc line from ~/.zshrc or run perlbrew off in a particular terminal to temporarily disable perlbrew.

5. Summary

In this blog post, I shared the steps I followed to set up a PostgreSQL development environment on MacOS. By installing the necessary tools and libraries, compiling PostgreSQL, and running tests, you can verify patches and contribute to the PostgreSQL community. I hope this guide proves helpful to others facing similar challenges.

David Zhang

A software developer specialized in C/C++ programming with experience in hardware, firmware, software, database, network, and system architecture. Now, working in HighGo Software Inc, as a senior PostgreSQL architect.