Local Setup for Heroku Postgres

Last updated September 03, 2024

Heroku recommends running Postgres locally to ensure parity between environments. There are several pre-packaged installers for installing PostgreSQL in your local environment.

After Postgres is installed and you can connect, you must export the DATABASE_URL environment variable for your app to connect to it when running locally:

-- for Mac and Linux
$ export DATABASE_URL=postgres://$(whoami)
-- for Windows
$ set DATABASE_URL=postgres://$(whoami)

Postgres connects to the local database matching your user account name (which is set up as part of the installation).

Set up Postgres on Mac

Postgres.app requires Mac OS 10.7 or above.

  1. Install Postgres.app and follow setup instructions.
  2. Install the postgres CLI tools.
  3. Open up a new terminal window to ensure your changes have been saved.
  4. Verify that it worked correctly. The OS X version of psql must point to the path containing the Postgres.app directory.

The output looks similar to:

$ which psql
/Applications/Postgres.app/Contents/Versions/latest/bin/psql

Start your local Postgres server and this command works correctly:

$ createdb
$  psql -h localhost
psql (16.4)
Type "help" for help.
=# \q

Also, verify that the app is set to automatically start at login.

PostgreSQL ships with several useful binaries including pg_dump and pg_restore. To make these available in every terminal session, add the /bin directory that ships with Postgres.app to your PATH (preferably in .profile, .bashrc, .zshrc, or similar):

PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

Set up Postgres on Windows

Install Postgres on Windows by using the Windows installer.

Remember to update your PATH environment variable to add the bin directory of your Postgres installation. The directory is similar to: C:\Program Files\PostgreSQL\<VERSION>\bin. Commands like heroku pg:psql depend on the PATH and don’t work if the PATH is incorrect.

Set up Postgres on Linux

Install Postgres via your package manager. The actual package manager command you use depends on your distribution. The following works on Ubuntu, Debian, and other Debian-derived distributions:

$ sudo apt-get install postgresql

If you don’t have a package manager on your distribution or the Postgres package isn’t available, install Postgres on Linux using one of the Generic installers.

The psql client is typically installed in /usr/bin:

$ which psql
/usr/bin/psql

Start your local Postgres server and this command works correctly:

$ createdb
$  psql -h localhost
psql (16.4)
Type "help" for help.
=# \q

Feedback

Log in to submit feedback.