How To Install Postgresql On Mac

June 27, 2017

How To Install Postgresql On Mac

I started off programming Ruby on Rails applications on a Windows machine with an Ubuntu virtual machine running on top. But when I got my first job at a startup in California, I received a brand new shiny Macbook laptop.

Postgresql Logo 3 Colors

I had never used a Mac before as I considered them overpriced relative to a desktop I could setup with Linux. But since that’s what I was given, that’s what I was used. One of the first things I had to do is figure out how to get Postgres up and running.

Eventually, I had to learn a good way to upgrade it as well. At my first job, I found that using Heroku’s Postgres app. At my next job, I used the homebrew package manager since that’s how our team used it.

So what follows is a mini-guide I put together on how to install postgresql on Mac as well as how to upgrade it with homebrew.

Now if you want to use Heroku’s Postgres app, it’s pretty easy and is a good alternative to homebrew.

Installing Postgres via Homebrew

This guide assumes that you have homebrew installed. If you don’t, you can find some instructions here.

Once you do that, all you have to do is issue the following command in your terminal:

$ brew install postgres

It should install the latest version of Postgres available via Homebrew. Pretty easy, right?

Upgrading Postgres via Homebrew

Ok, so let’s say you have to upgrade postgres. I had to follow these steps when I was upgrading to Postgres 9.6

Step 1 – Turn off Postgres

The first step is to turn off the postgres service if it’s running in the background.

$ brew services stop postgresql

Step 2 – Upgrade

Next, we’ll use homebrew to upgrade it to the latest version.

$ brew update && brew upgrade postgresql

Step 3 – Switch

Finally, we’ll switch to the new version using the following command.

brew switch 9.6.1

You’ll see output like the following:

Cleaning /usr/local/Cellar/postgresql/9.5.4_1
Cleaning /usr/local/Cellar/postgresql/9.6.1
375 links created for /usr/local/Cellar/postgresql/9.6.1

Step 4 – Ensuring Postgresql Starts Automatically At Startup (optional, but makes your life easier)

Now to ensure postgres starts automatically every time you start your Mac, you’ll need to do some extra setup.

I got the following setup from this blog post at tunnelsup.

Step A – You’ll need to setup LaunchAgents

Create the directory ~/Library/LaunchAgents if it doesn’t exist already.

Step B – Copy the plist file to ~/Library/LaunchAgents/

There’s a plist file that comes with the postgres install from homebrew.

When upgrading to 9.6.2, my plist was at /usr/local/Cellar/postgresql/9.6.2/homebrew.mxcl.postgresql.plist.

Copy the plist file to the LaunchAgents directory.

cp /usr/local/Cellar/postgresql/9.3.4/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/

Step C – Load launchctl

Now use launchctl to load the file using this command:

$ launchctl load -w homebrew.mxcl.postgresql.plist

You can also use a ruby gem called lunchy. I haven’t tried it but this blog post describes the process.

General Troubleshooting Tips And Useful Commands

The following command will show you if you have multiple versions of postgres installed.

$ brew info postgresql

This troubleshooting gist describes how to migrate data from one version of Postgres to another.

Troubleshooting Guide for Rails developers

This part gives you some common troubleshooting tips if you’re a Rails developer.

Since I primarily use Postgres for Ruby on Rails work, when I was upgrading I had a connection issue described below.

If you get a connection issue with a message such as the following:

Is the server running locally and accepting
    connections on Unix domain socket "/tmp/.s.PGSQL.5432"?

Then try running this in your terminal:

$ postgres -D /usr/local/var/postgres

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 9.5, which is not compatible with this version 9.6.1.

If you see the above “FATAL…”, then issue the following commands:

WARNING: Before you issue the following commands, please make sure you back up your old local Postgres data if you need it. See the gist referenced in the General Troubleshooting Tips And Useful Commands section.

$ rm -rf /usr/local/var/postgres && initdb /usr/local/var/postgres -E utf8

After running the above rm and initdb commands, you should see something similar to the following.

The files belonging to this database system will be owned by user "bpark".
This user must also own the server process.

The database cluster will be initialized with locale "en_US.UTF-8".
The default text search configuration will be set to "english".

Data page checksums are disabled.

creating directory /usr/local/var/postgres ... ok
creating subdirectories ... ok
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting dynamic shared memory implementation ... posix
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok

WARNING: enabling "trust" authentication for local connections
You can change this by editing pg_hba.conf or using the option -A, or
--auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

pg_ctl -D /usr/local/var/postgres -l logfile start


If you want to install Postgres via homebrew, follow the steps above. Make sure you backup your local data if you need it so you don’t accidentally erase something you need to keep. Other than that, let me know if you have any issues in the comments.