Local Setup for Heroku Postgres

Last updated December 15, 2025

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)

By default, Postgres connects to the local database matching your user account name that you set as part of the Postgres.app server initialization. You can also create different local databases with the createdb Postgres command and adapt your DATABASE_URL environment variable accordingly to point to them.

Set up Postgres on Mac

Postgres.app requires macOS 10.7 or later.

  1. Install Postgres.app and follow the setup instructions.
  2. Install the Postgres CLI tools.
  3. Open a new terminal window to ensure that you saved your changes.
  4. Verify that it worked correctly. The macOS 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 in the Postgres app and confirm that you can connect to your default local database correctly:

$ psql -h localhost
psql (17.7 (Postgres.app))
Type "help" for help.

user=# \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, create a new database, and connect to it using psql:

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