Cloud: Heroku database integration
Hasura Cloud makes it easy for you to use Heroku Postgres as a datasource in your Hasura Cloud projects. It makes sure
DATABASE_URL environment variable of your Heroku App stays in sync with a given environment variable of your
Hasura Cloud project. This means that whenever the database credentials of your Heroku Postgres are rotated, this
integration ensures that the linked environment variable in your Hasura Cloud project also gets updated.
Connecting an existing Heroku database
You can connect your Heroku database to your Hasura project by following these steps:
Go to your Hasura Cloud dashboard and head to the settings section of the desired project
Integrationstab and click on the Heroku integration under
Login into Heroku, enter an env var name of your choice (say
PG_DATABASE_URL) and connect the desired database from the list of databases
After a couple of seconds the env var will be updated with your connected database url and you can see it in the
Env Varstab of your project.
Now you can go ahead to your project console's
Datatab and connect the database through the env var that you created.
This completes your integration setup, you can now go ahead, track tables and try out Hasura's GraphQL APIs.
Deleting the Heroku integration from your
Integrations section does not delete the associated env var, it only stops
the database url sync. Should you want to remove the env var also, it is recommended to remove the connected database
from your console and then deleting the associated env var to prevent metadata inconsistency.
Creating a new Heroku database
Go to your project console's
Datatab and click
Data Manageron top left corner of the page.
Connect Databasebutton and choose the
Create Heroku Databasetab.
Herokubutton to login and create a database.
This creates a Heroku app, installs Heroku Postgres in it and sets the Postgres connection URI in
env var of your Hasura Cloud project. It also adds a datasource in Hasura that refers to the created Postgres database
using the env var.
Heroku database URL sync
If you use Hasura Cloud's Heroku integration, it keeps your project's Heroku database URL i.e. the associated env var in sync with the Postgres URL from a Heroku app. This is especially helpful in cases when the database credentials of Heroku Postgres are rotated automatically by Heroku.
The database sync automatically gets disconnected if you transfer the ownership of your project to another account. The new project owner can restart the sync with the Heroku account that they have connected their Hasura Cloud account to.
Enable Heroku database URL sync
If you create a project with a Heroku trial database using the Hasura console, your project has the Heroku database URL sync enabled by default, which means, Hasura Cloud keeps the database URL of your project in sync with the related Heroku Postgres.
If you have already connected your Heroku database to your Hasura Cloud project and would like to enable database URL sync on it, you can remove and re-add the database url env var with the Heroku integration as shown above
Opt out of Heroku database URL sync
If your project has Heroku database URL sync enabled, you can opt out using the following methods:
Go to the
Env varstab of your project and click on the env var that is involved in the Heroku database URL sync.
Opt out of the syncbutton next to Heroku note.
You can also opt out of Heroku database URL sync by deleting the integration from project integrations page.
How it works?
Heroku database URL sync is useful because Postgres credentials of Heroku Postgres are sometimes rotated thus making the old database URL invalid. Hasura Cloud listens to the changes in the database URL of your app and keeps the project updated. This is done using:
- Heroku Releases: Whenever a config variable of a Heroku app
changes, a new
releaseis made for that app.
- Heroku Webhooks: Heroku allows us to get notifications about these releases on a webhook.
Whenever Postgres credentials of a Heroku app are rotated:
DATABASE_URLconfig variable of the Heroku app gets updated with the new credentials.
- The config variable change triggers a new release, which notifies Hasura Cloud's webhook.
- When Hasura Cloud is notified about the new release, it fetches the newest database URL from Heroku and updates the connected env var of your project with it.
- This way, your project is always configured with the correct database URL.