mirror of
https://github.com/hasura/graphql-engine.git
synced 2025-01-05 22:34:22 +03:00
cc30f08f6e
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4261 GitOrigin-RevId: 3d80068acdd61b5350fc36ec3444db47508f9c09
131 lines
6.0 KiB
ReStructuredText
131 lines
6.0 KiB
ReStructuredText
.. meta::
|
|
:description: Automatically sync database URL of a Heroku Postgres into a Hasura Cloud project
|
|
:keywords: hasura, docs, project, team, heroku, database url, sync
|
|
|
|
.. _heroku_database_url_sync:
|
|
|
|
Heroku database integration
|
|
===========================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 2
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Hasura Cloud makes it easy for you to use Heroku Postgres as a datasource in your Hasura Cloud projects. It makes sure that the ``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.
|
|
|
|
.. _cloud_connect_existing_heroku_db:
|
|
|
|
Connecting an existing Heroku database
|
|
--------------------------------------
|
|
|
|
You can connect your Heroku database to your Hasura project by following these steps:
|
|
|
|
1. Go to your Hasura Cloud dashboard and head to the settings section of the desired project
|
|
2. Go to ``Integrations`` tab and click on the Heroku integration under ``Databases``
|
|
|
|
.. thumbnail:: /img/graphql/cloud/projects/heroku-integration.png
|
|
:alt: Heroku Integration
|
|
:width: 1100px
|
|
|
|
3. 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 Vars`` tab of your project.
|
|
|
|
4. Now you can go ahead to your project console's ``Data`` tab and connect the database through the env var that you created.
|
|
|
|
.. thumbnail:: /img/graphql/cloud/projects/heroku-db-connect.png
|
|
:alt: Heroku DB Connect
|
|
:width: 600px
|
|
|
|
This completes your integration setup, you can now go ahead, track tables and try out Hasura's GraphQL APIs.
|
|
|
|
.. note::
|
|
|
|
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
|
|
------------------------------
|
|
|
|
1. Go to your project console's ``Data`` tab and click ``Data Manager`` on top left corner of the page.
|
|
|
|
2. Click the ``Connect Database`` button and choose the ``Create Heroku Database`` tab.
|
|
|
|
.. thumbnail:: /img/graphql/cloud/projects/console-heroku-db-create.png
|
|
:alt: Heroku DB Create
|
|
:width: 700px
|
|
|
|
3. Click the ``Heroku`` button to login and create a database.
|
|
|
|
This creates a Heroku app, installs Heroku Postgres in it and sets the Postgres connection URI in ``PG_DATABASE_URL_*`` 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.
|
|
|
|
.. note::
|
|
|
|
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 :ref:`above <cloud_connect_existing_heroku_db>`
|
|
|
|
Opt out of Heroku database URL sync
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If your project has Heroku database URL sync enabled, you can opt out using the following methods:
|
|
|
|
Option 1:
|
|
*********
|
|
|
|
1. Go to the ``Env vars`` tab of your project and click on the env var that is involved in the Heroku database URL sync.
|
|
|
|
2. Click on ``Opt out of the sync`` button next to Heroku note.
|
|
|
|
.. thumbnail:: /img/graphql/cloud/projects/heroku-db-sync-enabled-new.png
|
|
:alt: Enabled DB Sync
|
|
:width: 1100px
|
|
|
|
Option 2:
|
|
*********
|
|
|
|
You can also opt out of Heroku database URL sync by deleting the integration from project integrations page.
|
|
|
|
.. thumbnail:: /img/graphql/cloud/projects/heroku-delete-integration.png
|
|
:alt: Delete Heroku Integration
|
|
:width: 1100px
|
|
|
|
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:
|
|
|
|
1. `Heroku Releases <https://devcenter.heroku.com/articles/releases>`__: Whenever a config variable of a Heroku app changes, a new
|
|
``release`` is made for that app.
|
|
2. `Heroku Webhooks <https://devcenter.heroku.com/articles/app-webhooks>`__: Heroku allows us to get notifications about these releases on a webhook.
|
|
|
|
Whenever Postgres credentials of a Heroku app are rotated:
|
|
|
|
1. The ``DATABASE_URL`` config variable of the Heroku app gets updated with the new credentials.
|
|
2. The config variable change triggers a new release, which notifies Hasura Cloud's webhook.
|
|
3. 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.
|
|
4. This way, your project is always configured with the correct database URL.
|