Local Setup for Heroku Postgres
Last updated May 16, 2023
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.
- Install Postgres.app and follow setup instructions.
- Install the postgres CLI tools.
- Open up a new terminal window to ensure your changes have been saved.
- Verify that it worked correctly. The OS X version of
psqlmust point to the path containing the
If you’re using version 10, the output looks similar to:
$ which psql /Applications/Postgres.app/Contents/Versions/latest/bin/psql
This command works correctly:
$ createdb $ psql -h localhost psql (10.14) 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_restore. To make these available in every terminal session, add the
/bin directory that ships with Postgres.app to your PATH (preferably in
.zshrc, or similar):
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.
psql client is typically installed in
$ which psql /usr/bin/psql
The following command works correctly:
$ psql psql (9.3.5) Type "help" for help. maciek# \q