Last updated February 06, 2023

Due to how the buildpack release API functions, Heroku’s Ruby support (implemented by the Ruby buildpack) can only add an add-on to an application on the first deployment. To skip this provisioning behavior, see Skip Auto-Provisioning a Database.

By default, the lowest-cost Heroku Postgres plan is added to any Ruby app that has the pg gem dependency, when deployed for the first time.

For backward compatibility with previous stacks on Heroku, all apps that deploy with the railties gem have a Heroku Postgres database auto-provisioned by default.

Skip Auto-Provisioning a Database

Developers using the heroku/ruby buildpack to deploy new applications who don’t want a Heroku Postgres database auto-provisioned can opt out by setting the HEROKU_SKIP_DATABASE_PROVISION environment variable:

$ heroku config:set HEROKU_SKIP_DATABASE_PROVISION=1

This setting prevents the database from being requested. This environment variable only affects heroku/ruby users and only affects applications without a successful first deployment. You must manually remove the add-on on any applications that already deployed with an auto-provisioned database.

This environment variable interface is experimental and subject to change. We emit deprecation warnings from the heroku/ruby buildpack on deployment with additional details before making any changes.

Using a Different Database with Rails

If you’re using a database other than Heroku Postgres, the default behavior of provisioning a Postgres database for Rails apps can conflict with your configuration. For detailed information about how exactly your version of Rails connects to the database, see Rails database connection behavior.

When Heroku auto-provisions a Heroku Postgres database for your application, it sets the database to the DATABASE_URL config var if that variable hasn’t already been set. With all versions of Rails on Heroku, any information present in the DATABASE_URL environment variable takes precedence. This behavior is a problem if you’re not using a Postgres database, as your application tries to connect to the auto-provisioned Heroku Postgres database by default.

If you want to use a non-Heroku Postgres database for your Rails app, you can opt out of database auto-provisioning.

If you don’t opt out of auto-provisioning, you can still set the DATABASE_URL or delete it to prevent your app from trying to use the Heroku Postgres database.

Setting the DATABASE_URL config var

You can set a DATABASE_URL config var on your app. This prevents Heroku from setting the Heroku Postgres database add-on to that variable.

$ heroku config:set DATABASE_URL=<scheme>://<username>:<password>@<host>

Replace the example values with the credentials and address for your database.

If you’re using pipelines or review apps, this strategy won’t work as you don’t have the ability to heroku config:set before you deploy each review app.

Instead, you can dynamically assign the value of DATABASE_URL inside of your code. You must assign this value before the database is initialized. For example:

ENV["DATABASE_URL"] = "mysql://#{ ENV['MY_DATABASE_PASSWORD'] }:#{ ENV['MY_DATABASE_USERNAME'] }@#{ ENV['MY_DATABASE_HOST'] }"

You can place this in an initializer, or directly in your config/database.yml inside of an ERB code section. The important thing is that this code is run before your application attempts to connect to the database.

Deleting the DATABASE_URL config var

Alternatively, if your production database credentials are in your config/database.yml you can ensure that your app doesn’t use DATABASE_URL by deleting it before the connection gets initialized.

ENV.delete("DATABASE_URL")