Skip to main content

Migrate from Heroku to Supabase

Supabase is one of the best free alternatives to Heroku Postgres. This guide shows how to migrate your Heroku Postgres database to Supabase. This migration requires the pg_dump and psql CLI tools, which are installed automatically as part of the complete PostgreSQL installation package.

Alternatively, use the Heroku to Supabase migration tool to migrate in just a few clicks.

Quick demo

Retrieve your Heroku database credentials

  1. Log in to your Heroku account and select the project you want to migrate.
  2. Click Resources in the menu and select your Heroku Postgres database.
  3. Click Settings in the menu.
  4. Click View Credentials and save the following information:
    • Host ($HEROKU_HOST)
    • Database ($HEROKU_DATABASE)
    • User ($HEROKU_USER)
    • Password ($HEROKU_PASSWORD)

Retrieve your Supabase Host

  1. If you're new to Supabase, create a project.
  2. Go to the Database settings for your project in the Supabase Dashboard.
  3. Under Connection Info, note your Host ($SUPABASE_HOST).

Export your Heroku database to a file

Use pg_dump with your Heroku credentials to export your Heroku database to a file (e.g., heroku_dump.sql).

pg_dump --clean --if-exists --quote-all-identifiers \
--no-owner --no-privileges > heroku_dump.sql

Import the database to your Supabase project

Use psql to import the Heroku database file to your Supabase project.

psql -h $SUPABASE_HOST -U postgres -f heroku_dump.sql 

(Optional) Post processing

If you're using GraphQL with your Supabase project, you may need to run the following SQL command in the Supabase Dashboard (SQL Editor) to make sure the new tables show up:

select graphql.rebuild_schema();

Additional options

  • To only migrate a single database schema, add the --schema=PATTERN parameter to your pg_dump command.
  • To exclude a schema: --exclude-schema=PATTERN.
  • To only migrate a single table: --table=PATTERN.
  • To exclude a table: --exclude-table=PATTERN.

Run pg_dump --help for a full list of options.