How to Use Homebrew to Install PostgreSQL on Mac

PostgreSQL is a reliable, open-source relational database system known for its flexibility and performance, especially in handling large datasets. If you’re using macOS, you can install and manage PostgreSQL easily using Homebrew, a popular package manager that simplifies installation and updates for software.

In this article, I’ll guide you through setting up PostgreSQL on a Mac with Homebrew, plus provide a few essential PostgreSQL commands to get you started. If you have landed on this page but are really using the Windows opearting system, I would visit our other tutorial instead: How to Install PostgreSQL on Windows and Mac OS X, which shows you how to install and test your installation on Windows. 

I’m assuming also that if you are trying to install PostgreSQL, you are probably interested in becoming great at it. To get started, read our Beginner’s Guide to PostgresQL and move on to a full course. Personally, I recommend our PostgreSQL Summary Stats and Window Functions course because knowing window functions is how you would do interesting things, like calculating moving averages, rankings, and cumulative sums. 

Before Installing Postgres with Homebrew

Before we begin, make sure you have:

• Xcode installed (it’s required for Homebrew)
• Homebrew installed on your macOS
• Basic understanding of SQL. (If you’re new to SQL, check out Introduction to SQL on DataCamp for a quick start.)

How to Install Homebrew

Homebrew is a popular package manager for macOS that simplifies the installation, updating, and management of software on your system. It lets users install command-line tools and applications easily using simple terminal commands. I’ll run through how to install Homebrew real quickly, but for another set of detailed instructions, you can also check out our How to Install and Use Homebrew tutorial. 

To install the latest version of Homebrew on your computer, open your terminal and run the command below.

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

Once you run the installation command above, you will be prompted to enter your system password. Enter the password to begin the installation.

Next, after the installation is complete, let’s use the command below to check if Homebrew has been added to the system path.

echo $PATH

The command above will list all the paths in your system path. If /opt/homebrew/bin is not included, you must add it by running the command below.

export PATH=$PATH:/opt/homebrew/bin

To verify whether Homebrew is installed and configured successfully, run the command below.

brew doctor

How to Install and Configure PostgreSQL

Now, let’s install PostgreSQL using the Homebrew package manager. To do this, run the command below in your terminal.

brew install postgresql@17

After the installation, run the command below to add PostgreSQL to the system path.

echo 'export PATH="/usr/local/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
export LDFLAGS="-L/usr/local/opt/postgresql@17/lib"
export CPPFLAGS="-I/usr/local/opt/postgresql@17/include"

How to Start and Stop PostgreSQL Service

Now, let's start the PostgreSQL service. To do this, simply run the command below in your terminal.

brew services start postgresql@17

To verify that the PostgreSQL service is running, run the command below to view the list of running services on your system.

brew services list

In your terminal, you should see the status of postgresql@17 as started, indicating that the PostgreSQL service is running correctly.

You can stop the PostgreSQL service at any time by running the stop command below.

brew services stop postgresql@17

How to Create a PostgreSQL User

Now that the PostgreSQL service is running on your computer, let’s create a superuser for the PostgreSQL database. To create the superuser account, run the command below in your terminal, replacing the <username> placeholder with your desired username:

createuser --superuser <username>

Testing Installation with Basic PostgreSQL Commands

Let's write basic PostgreSQL commands for creating databases, viewing lists of all databases, and deleting databases. First, run the command below to start the PostgreSQL prompt, which will allow you to execute PostgreSQL commands.

psql postgres

Now, to create a new database, run the Postgres command below on your terminal, replacing the <your_database> placeholder with your desired database name:

CREATE DATABASE <your_database>;

To list all databases on your PostgreSQL server, run the following command within the psql prompt:

\l

Or 

SELECT datname FROM pg_database;

After running the command above, all your PostgreSQL databases will be displayed, as shown in the screenshot below.

To delete an existing database, use the following command, replacing the <your_database> with the name of the database you want to drop:

DROP DATABASE <your_database>;

Troubleshooting

When working with PostgreSQL, you may encounter some common issues. Here are a few troubleshooting steps:

Step 1

Ensure that PostgreSQL is added to your system PATH. If it is not, add it by running the following command:

echo 'export PATH="/usr/local/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc

Step 2

A version mismatch between the psql client and the PostgreSQL server can cause errors. Updating both to the same version can resolve this issue. To update both, run the command below.

brew update
brew upgrade postgresql

Using PostgreSQL Without Installing the Server

You can install PostgreSQL client utilities (such as psql) without installing the full server. This is useful for connecting to an external PostgreSQL database. To install the PostgreSQL client using Homebrew, run the following command:

brew install libpq

After the installation, you need to add libpq to your system PATH. You can accomplish this using the command below.

echo 'export PATH="/usr/local/opt/libpq/bin:$PATH"' >> ~/.zshrc

Conclusion

PostgreSQL is a feature-rich database management system that caters to a wide range of applications and industries. In this article, we learned how to install and configure PostgreSQL on a macOS system using Homebrew, and we tested our installation with basic PostgreSQL commands.

Enroll in a DataCamp course. I recommended earlier our PostgreSQL Summary Stats and Window Functions course. I also want to suggest our Functions for Manipulating Data in PostgreSQL, which covers functions more generally, such as ones working with dates and times, and our Cleaning Data in PostgreSQL Databases, which teaches you how to work with messy data.