If you are new to PostgreSQL, the first step is installation. Some people assume that setting it up is complex, However, that's not true! Installing PostgreSQL is actually quite simple.
There are multiple ways to install PostgreSQL on macOS: you can use the EnterpriseDB installer, Postgres.app, Homebrew, and MacPorts. Each method has its own advantages:
Postgres.app offers a self-contained, GUI-based simple PostgreSQL setup.
Homebrew installs PostgreSQL with a minimal footprint, integrating seamlessly with macOS.
MacPorts offers a flexible and isolated PostgreSQL installation with robust dependency management.
In this guide, I'll walk you through each installation method step by step.
To instantly speed up your PostgreSQL database through automatic partitioning, a powerful hybrid row-columnar storage engine, and always up-to-date materialized views, try installing the TimescaleDB extension. TimescaleDB revs up PostgreSQL, expanding it for time series, real-time analytics, events, vector data, and other demanding workloads.
Installing PostgreSQL via EnterpriseDB Installers
EnterpriseDB (EDB) provides an official PostgreSQL installer for macOS, including various management tools. It is ideal for users who prefer a guided setup with a wizard and require additional PostgreSQL management tools, such as pgAdmin and StackBuilder (for downloading PostgreSQL extensions), to meet their business needs.
Download the installer
Visit the PostgreSQL installers download page and download the required PostgreSQL version. For this tutorial, I will download the PostgreSQL 16.6 installer.
This is what the download page for PostgreSQL installers looks like.
After selecting the desired PostgreSQL version, you will be redirected to the download page, and the download will start automatically.
Launch the installer
Once the download is complete, double-click the .dmg file and select the PostgreSQL-16.6-1.osx installer to launch it.
After clicking on the installer, you may see a warning since macOS often alerts users about potential risks when downloading apps from a browser instead of the App Store. However, since we downloaded the installer from a trusted source, you can simply click "Open" to proceed with the installation.
After clicking "Open," you may be prompted to enter your logged-in user's password. If a dialog appears, enter your password and press Enter. The installer will then launch, and you will see its home screen.
This is what the initial screen of the installer looks like. Click the "Next" button to continue with the installation configuration.
Choosing the PostgreSQL installation directory
Specify the installation directory for the PostgreSQL server.
If you want to change the path, enter your preferred location; otherwise, you can proceed with the default. Then, click "Next" to continue.
Selecting PostgreSQL installation components
Next, you will be asked to choose the components to install as part of the PostgreSQL setup. Here’s what each component includes:
PostgreSQL Server: The core database engine that stores and manages data.
pgAdmin 4: This web-based GUI tool manages and interacts with PostgreSQL databases.
Stack Builder: This utility helps you install additional PostgreSQL extensions.
Command Line Tools: This set of CLI utilities, including psql, can manage and query the database.
Select the components you want to install.
Note: PostgreSQL Server is required for installation.
Let's select all the options and click "Next" to proceed.
Setting the data directory path
On the next screen, you need to specify the data directory path for your PostgreSQL server.
What is the data directory?
The PostgreSQL data directory is where all database files, configurations, and transaction logs (WAL) are stored. It is defined by the data_directory parameter in postgresql.conf.
If you want to change the default path, specify your preferred location. Otherwise, you can proceed with the default setting.
Click "Next" to continue.
Setting the superuser password
On the next screen, you need to specify a password for the PostgreSQL superuser.
By default, PostgreSQL creates a superuser named "postgres," and the password you set here will be used to connect to the database with postgres user.
What is a PostgreSQL superuser?
A PostgreSQL superuser has unrestricted access to all database operations, including administrative tasks and security-sensitive actions.
Enter your desired password. Click "Next" to continue.
Configuring the PostgreSQL port
On the next screen, you need to specify the port on which the PostgreSQL instance will listen for incoming connections.
Why is the port important?
PostgreSQL requires a port to accept client connections and enable communication between the database server and applications over the network using the TCP/IP protocol.
After selecting the port, click "Next" to continue.
Configuring locale settings
On the next screen, you will be prompted to set the locale for the database cluster.
What is locale in PostgreSQL?
The locale controls how text is sorted and displayed based on language and region. For example, in English, "z" comes after "a" in sorting, but in Swedish, "ä" is treated as a separate letter and appears at the end of the alphabet.
You should change the locale if your database needs to follow specific language or regional sorting and formatting rules.
Choose the appropriate locale and click "Next" to proceed.
Review installation settings
On the second-to-last screen, the installer will display a summary of all the settings you have selected for installing PostgreSQL. Review these details carefully, then click "Next."
Confirm and start the installation
The final screen confirms that PostgreSQL is ready to be installed on your machine. Click "Next" to start the installation process.
Completing the installation
Once the installation is complete, you will be redirected to the final screen.
If you want to install additional components along with the PostgreSQL server, leave the Stack Builder checkbox selected and click "Finish."
If you don’t need additional components, uncheck the box and click "Finish" to complete the installation.
Congratulations! You have successfully installed the PostgreSQL server.
Verify the installation
To confirm that PostgreSQL is installed correctly, open the terminal on your Mac and run the following commands:
When prompted, enter the password for the postgres user. If the installation is successful, you should be able to connect to PostgreSQL.
psql (16.6)
Type "help" for help.
postgres=# SELECT version();
Version
---------------------------------------------------------------------
----------------------------------------
PostgreSQL 16.6 on x86_64-apple-darwin23.6.0, compiled by Apple clang version 16.0.0 (clang-1600.0.26.4), 64-bit
(1 row)
This confirms that PostgreSQL 16.6 is running and accessible.
Note: If you ever forget details like the port, data directory path, or other settings chosen during installation, you can find them in the installation_summary.log file inside your installation directory.
Postgres.app is a simple, native macOS application that provides a full-featured PostgreSQL installation in a single package. It is designed for developers, students, and macOS users who want an easy, hassle-free way to run PostgreSQL without dealing with complex configurations.
With a one-click setup, it includes essential tools like psql and runs PostgreSQL as a background service, making it ideal for local development and testing.
After downloading the required PostgreSQL version (we'll install PostgreSQL 16), double-click the .dmg file, then drag and drop Postgres.app into the Applications folder. That’s it—installation is complete!
Connecting to PostgreSQL via Postgres.app
Open Postgres.app from the Applications folder to launch the setup wizard. Select the user you want to connect with, and it will open the macOS Terminal, where you will be connected to PostgreSQL.
Note: I changed my port to 5437 because another PostgreSQL instance was already using the default port (5432). To do this, I went to Settings, specified the new port, and then clicked "Start" to run PostgreSQL on the non-default port.
Verifying the PostgreSQL version
Once connected to PostgreSQL in the terminal, run the following query to check the server version.
"/Applications/Postgres.app/Contents/Versions/16/bin/psql" -p5432 "postgres"
psql (16.6 (Postgres.app))
Type "help" for help.
postgres=# select version();
version
------------------------------------------------------------------------------------------------------------------------------------
PostgreSQL 16.6 (Postgres.app) on aarch64-apple-darwin21.6.0, compiled by Apple clang version 14.0.0 (clang-1400.0.29.102), 64-bit
(1 row)
postgres=#
Installing PostgreSQL via Homebrew
Homebrew is a popular package manager for macOS that allows users to easily install and manage software from the command line. Developers and system administrators can use Homebrew to install PostgreSQL with a single command, making it a quick and efficient method for those comfortable with the terminal.
Installing Homebrew (if not installed)
If Homebrew is not already installed on your system, you can install it using the following command:
Navigate to the PostgreSQL installation directory and run the following command to connect to the PostgreSQL server.
cd /usr/local/Cellar/postgresql@16/16.6/bin
mapmac@192 bin % ./psql postgres
psql (16.6 (Homebrew))
Type "help" for help.
postgres=# select version();
Version
---------------------------------------------------------------------
-------------------------------------------------------
PostgreSQL 16.6 (Homebrew) on x86_64-apple-darwin23.6.0, compiled by
Apple clang version 16.0.0 (clang-1600.0.26.4), 64-bit
(1 row)
Installing PostgreSQL Using MacPorts
MacPorts is a package management system for macOS that simplifies the installation of Unix-based software, including PostgreSQL. It is ideal for developers who need a more customizable and isolated environment, as MacPorts installs software in /opt/local, keeping it separate from system files.
Compared to Homebrew, which installs packages in /usr/local (or /opt/homebrew on Apple Silicon) and integrates more with macOS, MacPorts offers better control over dependencies and multiple PostgreSQL versions. If you need a self-contained, flexible setup or work on projects requiring specific library versions, MacPorts is a great choice for installing PostgreSQL.
After downloading, open the MacPorts installer, which will guide you through the installation steps smoothly.
After installation, run the following command in your terminal to verify the installation. It will display the installed MacPort version on your system.
port version
Version: 2.10.5
Install PostgreSQL and required packages
Run the following command to install PostgreSQL 16 and its server package:
sudo port install postgresql16 postgresql16-server
This will download and install PostgreSQL 16 along with the necessary dependencies.
Set PostgreSQL 16 as the default version
To ensure PostgreSQL 16 is used by default, run the following command, which sets PostgreSQL 16 as the default version for the postgresql command.
sudo port select postgresql postgresql16
Create the database directory
PostgreSQL requires a directory to store its database files. Create it using:
Change the ownership of the database directory to the postgres user. This step ensures PostgreSQL has the necessary permissions to access the directory.
By default, MacPorts does not start PostgreSQL automatically. To enable and start the PostgreSQL service, run
sudo port load postgresql16-server
This ensures that PostgreSQL starts immediately and also launches at system startup.
Final verification
To check if PostgreSQL is running, use:
sudo -u postgres /opt/local/lib/postgresql16/bin/pg_ctl status -D /opt/local/var/db/postgresql16/defaultdb
pg_ctl: server is running (PID: 18977)
/opt/local/lib/postgresql16/bin/postgres "-D" "/opt/local/var/db/postgresql16/defaultdb"
Now, PostgreSQL is successfully installed and running on your system!
Conclusion
This article explores four distinct methods for installing PostgreSQL on macOS: the EDB installer, Postgres.app, Homebrew, and MacPorts. It provides a detailed, step-by-step guide for each approach, outlining installation procedures, and configurations. By following this guide, you can efficiently deploy PostgreSQL on macOS and seamlessly integrate it into your development or production environment.
To instantly speed up your PostgreSQL database through automatic partitioning, a powerful hybrid row-columnar storage engine, and always up-to-date materialized views, try installing the TimescaleDB extension. TimescaleDB revs up PostgreSQL, expanding it for time series, real-time analytics, events, vector data, and other demanding workloads.
Scale PostgreSQL via Partitioning: A Dev’s Intro to Hypertables
Boosting Postgres INSERT Performance by 2x With UNNEST
