Connecting Rails to a PostgreSQL DB on Heroku

Paulo Carvalho
2 min readAug 10, 2022

This week we had to do a quick deployment of a backend for one of our clients and we decided to use Heroku. During the deployment, we noticed the official documentation was missing two key configurations which are highlighted below.


We had to deploy a simple Rails backend to Heroku for one of our clients. Given we had a very small number of hours available for the deployment, we opted for Heroku instead of the usual AWS Elastic Beanstalk or equivalents. That way we could have a deploy running in 1 to 2 hours of work instead of the usual 6 to 8.

However, upon configuring the deployment we noticed that the oficial Heroku documentation does not include two important configurations required to run a real application.

1 — Run Migrations

Whenever a new version of the application is deployed we should run the corresponding migrations. Rails does not complain in production about missing migrations but your code sure will!

To that end, edit your Procfile (spelled exactly like that with capital P on the root of your repo):

release: rails db:migrate
web: bundle exec puma -t 5:5 -p ${PORT:-3000} -e ${RACK_ENV:-development}

This will ensure that migrations run automatically with every deploy from your CICD.

2 — Connect to the Database

Heroku allows you to easily add a PostgreSQL database as an add-on with your deployment. However, the documentation does not make it clear how to connect to it.

It is quite straightforward. You can use the DATABASE_URL environment variable that is automatically made available in your virtual machine. You can check its value by opening the Heroku console of your instance and executing the bash command env. To make use of this environment variable just add the url key in your database.yml as shown below:

default: &default
adapter: postgresql
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
timeout: 5000
url: <%= ENV['DATABASE_URL'] %>
<<: *default
database: my_app_development
<<: *default
database: my_app_test
<<: *default


Heroku makes it easy to quickly deploy your application. However, you may end up losing some time configuring your app due to the two small configurations shown above.

Hope this helps! If you have any questions or just want to chat about startups, entrepreneurship, software development or engineering just send me an email on or leave a comment here.



Paulo Carvalho

Want to chat about startups, consulting or engineering? Just send me an email on