Setting up PostgreSQL on Mac OS X

What’s that? You’re making a Rails app, planning on eventually pushing it to Heroku, and you’re still running SQLite locally on your machine? Like a chump!? Come on now!

You’ve got to install Postgres locally! The good news is: It’s super easy.

First Things First

You’ll first need to install PostgreSQL. For this tutorial, we’ll use Homebrew to help us do that quickly.

Open terminal and type: brew -v
This will return the current version of brew (if you have it installed).
If you do have it installed, update it with the following command: brew update

That was pretty simple

If you saw a command not found: brew (or similar) error after you ran brew -v, then you likely need to install Homebrew. If you would like to do that now, type the following into your terminal:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Pro Tip

If at this point you’re thinking of installing Homebrew, consider first reading more about installing Homebrew in this article I wrote on How To Install Homebrew on Mac OS X 10.7+.

With brew installed, you’re golden. Time to install PostgreSQL!

Install PostgreSQL and Configure

With Brew, you can install PostgreSQL with the following command in Terminal:

brew install postgresql

You can now start your PostgreSQL server and create a database:

initdb /usr/local/var/postgres

Optional
You’ll need to have PostgreSQL running locally in order for your app (running in development mode, of course) to read and write to your Postgres database(s). If you want to have PostgreSQL start automatically each time you start your computer, enter the following three lines into Terminal one after another:

mkdir -p ~/Library/LaunchAgents
cp /usr/local/Cellar/postgresql/9.1.3/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Done and done. PostgreSQL is up and running and now all you need to do is tweak a few setting in your Rails App’s database.yml file (in the config/ folder).

In your database.yml file, you’ll see a few environments and their respective configs beneath. Most likely you’ll see three environments: development:, test:, and production:.

For now, we’ll just change the development: environment. If you haven’t changed anything, you’ll see the following as the default config for development::

development:
# adapter: sqlite3
# database: db/development.sqlite3
# pool: 5
# timeout: 5000

In order for your app to use your new PostgreSQL server, you’ll want to change the above to this:

development:
# adapter: postgresql
# database: name_of_your_app_development
# encoding: utf8
# template: template0
# host: localhost

Super-awesome Protip

You’ll want to replace name_of_your_app with the name of your app.

Editing Your Gemfile

Hold on there partner, don’t forget to tweak your Gemfile! Make sure the you’ve got the pg gem in your gemfile:

Example line entry in your Rail's `Gemfile`, if you want to use the `pg` gem:
gem 'pg'

Want To Run PostgreSQL in Production?

If you want to run Postgres in your production environment as well as your development environment, make sure to add the gem 'pg' line somewhere within the :production block—and not only within your group :development, :test do block.

Finally, you’ll want to create a new database: rake db:create and you’ll probably want to run the following command to delete your tables, recreate them, and seed them with any data you may have in your seeds.db file with the following command: rake db:reset

Trying to install PostgreSQL on your Linux machine instead?

My buddy—Eric MacAdie—offers these helpful instructions for setting up a Postgres server for Rails on a Linux machine instead of OS X.

Credit Where Credit Is Due:

Dan Manges is crazy-smart, the CTO of Braintree, and happens to be my mentor while at Code Academy The Starter League. He saved me about three hours of chin-scratching, by teaching me everything below today (in about 15 minutes). Thanks man!
(Probably worth noting that any errors below are courtesy of yours truly—and not Dan :)