How to start PostgreSQL server on Mac OS X via Homebrew

Posted by: AJ Welch

Install PostgreSQL via Homebrew

Likely most OS X users know of Homebrew, but Homebrew is a package manager for OS X that allows you to easily install and run a massive library of applications and utilities with ease.

We won’t go through the entire (albeit short) installation process of Homebrew, but if you wish to install Homebrew and use it for PostgreSQL management, check out the installation command on the official documentation. If you aren’t sure if Homebrew is installed, try the which brew command from the terminal to verify.

Once Homebrew is installed, you can install PostgreSQL by issuing the following commands in your terminal:

$ brew update
$ brew doctor
$ brew install postgres

The first two commands are used to update Homebrew and report any potential issues (if necessary). Then, of course, brew install postgres is the one-line command for installing PostgreSQL.

You should see a good deal of useful information in the output during installation, much of which should be copied down for use in the next sections.

Using a LaunchAgent and plist to launch PostgreSQL on startup

In most cases, you’ll likely wish to have PostgreSQL launch when you start up your system, so you’ll need to tell your computer this is your desire.

First, you’ll need to create a directory for your LaunchAgents to reside (if the directory doesn’t exist already). LaunchAgents in OS X are simple scripts used by launchd that cause the system to run programs or code during startup.

Create your user-specific LaunchAgents directory with this command, if necessary:

$ mkdir -p ~/Library/LaunchAgents

Now you’ll need to create a symbolic link from the script that actually allows Postgres to run to the LaunchAgents directory. A symbolic link is similar to creating a new copy of a file for use in another directory, but since the link is ‘symbolic’, the link is just a forwarding address: any request made to that symbolic link location is actually “forwarded along” or redirected to where the real file actually resides.

Link to the plist (property list) file that was generated by Homebrew and place that new symbolic link in LaunchAgents with this command:

$ ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents

Note: Double-check that the command is correct: It should’ve been part of the installation output mentioned above when Homebrew installed Postgres initially.

Finally, we load the new symbolic link’ed LaunchAgent file using the launchctl load command, which is specifically what informs the computer to run this script and start Postgres when the computer launches. Again, the exact command to enter for your own installation will be an output during Homebrew’s Postgres installation, but it should look something like this:

$ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Manually starting PostgreSQL

To manually startup Postgres without rebooting, again you should be able to use the command that was output during the installation, like so:

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

This will attempt to launch Postgres in daemon mode, which means it will be running as a background process without taking over your terminal.

Start/Stop PostgreSQL without Homebrew

In the event that you don’t have (or don’t wish to use) Homebrew for Postgres, yet you have Postgres installed already, you can also manually start it with pg_ctl, which is the launch utility provided by Postgres itself.

This will start Postgres (assuming default directories):

$ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start

And this will stop Postgres:

pg_ctl -D /usr/local/var/postgres stop -s -m fast

Startup troubleshooting: did you run initdb?

In some cases, if you have trouble running Postgres, be sure you’ve executed the initdb command one time, which causes Postgres to initialize the database cluster for a new installation and allows you to connect with the default postgres user.