How to install PostgreSQL on macOS

The following instructions to install PostgreSQL are based on macOS.

For Windows and Linux, go to https://www.postgresql.org/download/ and choose your package. It should not differ a lot, especially past the installation phase.

On macOS we’ll use Homebrew. If you don’t have Homebrew installed yet, go to https://brew.sh/ and follow the instructions there.

Once you are done, get back and in the command line run:

brew install postgresql@18

I recommend the versioned formula (postgresql@18 at the time of writing) over the plain postgresql name. With a versioned formula, a routine brew upgrade cannot silently move you to a new major version — and a PostgreSQL major version change is a data-directory migration, not an ordinary update.

After it finished, run:

brew services start postgresql@18

to start PostgreSQL as a daemon, which means it will keep running in the background, listening for connections.

The versioned formula is keg-only, so add its bin directory to your path if Homebrew tells you to:

echo 'export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc

Open a new terminal and verify the install:

psql --version
brew services list

psql --version should print the version you installed, and the service should show started. If psql is not found, the path line above is missing or the shell has not reloaded it.

postgresql is the more complex to pronounce name of PostgreSQL, but they are the same thing. It just embeds SQL in the name. What’s SQL? SQL, pronouced “sequel”, means Structured Query Language, and it’s a special language we use to interact with a relational database.

If you’re new to databases, it’s a lot of new terms for you! A relational database organizes the data into tables, and provides a way to insert and extract data from those tables. That’s SQL.

And we’re going to use it soon.

Right after we log in to PostgreSQL!

Go back to the command line, and type

psql postgres

This will give you access to the postgres database, which is created by default, with your macOS username. Homebrew automatically created your user at installation.

Now that we are into the psql application, we can create a new database:

CREATE DATABASE test;

Don’t forget the semicolon ;, because it’s needed by SQL otherwise the command will not run.

Now in a new line, we switch to this database using

\c test

The prompt will tell something like this:

You are now connected to database "test" as user "flaviocopes"..

Now we’re going to create a new table.

Use this syntax:

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL
);

Now if you run this, and no error shows up, you will have the table in the system.

You can see it by running the command

\dt

which will show you the database tables:

If you did any error, you can delete the table by running the command

DROP TABLE users

To finally quit psql, run

\q

or just type quit.

A note on upgrades

Minor updates (say 18.1 to 18.2) are safe, ordinary package updates. Moving between major versions (18 to 19) is a cluster upgrade: back up first and use pg_upgrade or a dump and restore. Do not uninstall the old server and hope its data follows the new package — that is how people end up with a running new server and an orphaned old data directory.

A GUI client

Now that you know how things work under the hood, I will show you an easier way to work with PostgreSQL, and other databases too: the TablePlus app. It works on macOS, Windows and Linux.

Connect to the database:

specifying the test database name:

In addition to be able to inspect tables with a Graphical User Interface:

It also allows us to work with SQL queries, very easily: