Heroku Free Tier Deprecation | Migrating to other DB vendors

Heroku recently announced that they are deprecating free resource plans, starting November 28, for their Heroku Dynos, Heroku Postgres among others.

What does this mean for you as a Hasura Cloud user?

You will need to either upgrade your Heroku account or migrate your Heroku Postgres database to a different database provider before November 28.

In this post, we will look at how to take a backup of your Heroku Postgres DB and Hasura Metadata / Migrations so that you can migrate to a different DB vendor.

Export Heroku Postgres DB using pg_dump

If you are on Heroku free tier Postgres, you can make use of standard Postgres tools like pg_dump and psql to export/import the database.

Find the Heroku Postgres connection string of the DB attached to your Hasura Cloud instance. Head to Hasura Cloud Dashboard and navigate to the project details -> ENV vars section. Under Custom ENV vars, look out for PG_DATABASE_URL env. It should have the Postgres Connection String of the Heroku DB.

If you have multiple Heroku Postgres instances connected to your Hasura Cloud project, then the ENVs would follow the pattern of PG_DATABASE_URL* where * would represent the number of such connections. You will get an ENV value that looks something like the one below:

Heroku Postgres Connection String Hasura Cloud ENV
Heroku Postgres Connection String Hasura Cloud ENV

The connection string is of the format:


Copy the individual sections of the connection string if required. But since we are using pg_dump to take a backup, we can simply pass the connection string directly.

pg_dump <connection-string> > dump.sql

This dump.sql will now have all the schemas along with the data in the database.

Import Database Dump

You can now import this SQL into the database vendor of choice. Some of the popular vendors that give a free tier Postgres Database (with limits).

There are more of course and you can choose the vendor and import the SQL into their instance.

Hasura CLI Migrations and Metadata

If you already have a Hasura CLI project that contains migrations and metadata, you can skip this step. In case you don't, follow the below steps to create migration files and export metadata from your Heroku Postgres instance.

# create a project
hasura init
cd hasura

# create an aggregate migration file from the SQL dump
hasura migrate create init --sql-from-file <path-to-dump.sql>

# head to migrations directory to mark the generated one as applied
cd migrations/default

# copy the version number of the first migration directory/file
hasura migrate apply --endpoint <hasura-project-url> --admin-secret <admin-secret> --version 1627564572630 --skip-execution

# export metadata
hasura metadata export --endpoint <hasura-project-url> --admin-secret <admin-secret>

In case you have more than one such free Heroku Postgres DB attached to your instance, repeat the above steps for the pg_dump and the Hasura CLI migrations on the same project with the db name being different.

Connect Hasura Project to New DB

This will involve the following steps to remove the old DB, connect the new DB and apply hasura metadata.

  • Remove the old Heroku Postgres DB connection.
  • Connect the new database as a data source in Hasura
  • Apply migrations (skip execution) and apply metadata.

Remove the old Heroku Postgres DB connection.

In your project's Hasura Console, head to Data tab. Click on Remove button for the Heroku Postgres DB source that is already added. Type the source name to confirm and delete.

Connect new database as a data source in Hasura

Once the old connection is removed, add the new DB connection string to your Cloud Project's ENV vars so that it can be referenced in the Hasura Console Data tab connect database step.

Head to Cloud Dashboard -> Project Details -> ENV Vars and update the connection string of PG_DATABASE_URL to point to the new value.

Apply migrations and metadata

Once you have imported your DB to a new vendor, you can apply the migrations and metadata to the same project.

# apply migrations but skip execution
hasura migrate apply --endpoint <hasura-project-url> --admin-secret <admin-secret> --version 1627564572630 --skip-execution

# apply metadata
hasura metadata apply --endpoint <hasura-project-url> --admin-secret <admin-secret>

# reload metadata
hasura metadata reload --endpoint <hasura-project-url> --admin-secret <admin-secret>

That's it! You can now verify if the new connection and the API is working by heading to Hasura Console API Explorer and trying out a GraphQL query.

Next steps

We have guides for connecting to various cloud database vendors in your Hasura Cloud project apart from the free tier Postgres vendors mentioned in this post above.

In case you are stuck with the migration, ping us or the community on Discord or create a GitHub issue for help.

We have an exciting announcement to make soon around a native DB integration that will have a similar or better experience than connecting to Heroku Postgres. Watch out for the announcement :)

29 Sep, 2022
Subscribe to stay up-to-date on all things Hasura. One newsletter, once a month.
Accelerate development and data access with radically reduced complexity.