Last updated December 03, 2024

A Heroku Postgres database is automatically provisioned by default for Ruby apps if certain conditions are met. This article covers how to opt out of this behavior and how to use a non-Heroku Postgres database.

Heroku Postgres Database Auto-Provisioning Behavior

Heroku buildpacks can auto-provision add-ons through the v2 buildpack release API. The heroku/ruby buildpack uses this API to request to provision a Heroku Postgres database if all of these conditions are true:

• You created your account before May 15, 2023 or you asked Heroku Support to enable auto-provisioning for your account.
• The heroku/ruby buildpack is the last buildpack to execute on the first deploy.
• The HEROKU_SKIP_DATABASE_PROVISION environment variable isn’t set on the application.
• Has one of these PostgreSQL gems in Gemfile.lock

Skip Auto-Provisioning a Database

Accounts created after May 15, 2023 don’t auto-provision databases for their apps unless you asked Heroku Support to the feature for your account.

If you created your account before that date or ask Support to enable auto-provisioning, you can opt out of auto-provisioning on a per-app basis by setting the HEROKU_SKIP_DATABASE_PROVISION environment variable to any value:

$ heroku config:set HEROKU_SKIP_DATABASE_PROVISION=1

This setting skips database auto-provisioning for that app. For Review Apps, you can set this config var in your pipeline setting’s Review app config vars section.

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

Use a Different Database with Rails

If you’re using a database other than Heroku Postgres, the behavior of provisioning a Postgres database for Rails apps can conflict with your configuration. When Heroku auto-provisions a Heroku Postgres database for your application, it sets theDATABASE_URL config var. With all versions of Rails on Heroku, any information present in the DATABASE_URL environment variable takes precedence. This behavior is problematic 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, opt out of database auto-provisioning.

If you don’t opt out of auto-provisioning, delete the auto-provisioned Postgres database.

For detailed information about how exactly your version of Rails connects to the database, see Rails database connection behavior.

Use a Different Database with Review Apps

You can dynamically assign the value of DATABASE_URL inside your code. You must assign this value before the database initializes. For example:

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

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