Ruby Database Provisioning
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")