Migrating an Application to Another Region
Last updated March 09, 2020
Table of Contents
Follow the steps outlined in this article to copy all add-on services, config vars, and Heroku Postgres data to a new app in the other region and migrate live traffic to the new app.
In this guide,
sourceapp is the original (source) app and
targetapp is the migrated (target) app.
Before beginning an app migration, please understand the proposed process as well as any nuances that are specific to your application. The following is the recommended migration approach.
heroku forkto create
targetappas a fork of
targetappadd-on provisioning and config vars.
Cut-over live traffic
- Prepare DNS and data for migration
sourceappin maintenance mode
- Migrate production data
- Move custom domains from
- Adjust DNS settings to point to
Begin the verification phase by forking the application to create a copy in another region, for example the
eu region. This will copy all Heroku Postgres data and config vars and will re-provision all add-ons. Depending on the size of your database this process may take some time.
Only Heroku Postgres data is automatically copied to the new application. All other add-ons are simply re-provisioned. Please consider the ramifications of this approach and plan for proper data migration with any other applicable add-ons.
heroku fork command is no longer included with the Heroku CLI by default, but it is available via a plugin with the following command:
heroku plugins:install heroku-fork
With this installed the following command will be available:
heroku fork forks
sourceapp to a new
targetapp should not exist prior to the fork command.
$ heroku fork --from sourceapp --to targetapp --region eu Creating fork targetapp... done Copying slug... done Adding heroku-postgresql:hobby-dev... done Creating database backup from sourceapp... .. done Restoring database backup to targetapp... .. done Copying config vars... done Fork complete, view it at http://targetapp.herokuapp.com/
--region us if your app is in the
eu region and you are migrating to
When forking to a different region than
sourceapp some add-ons may fail provisioning if they’re not available in the new region or are outdated plans.
$ heroku fork --from sourceapp --to targetapp --region eu Creating fork targetapp... done Copying slug... ........ done Adding airbrake:developer... done Adding bonsai:test... skipped (not found) Adding komrade:test... skipped (This app is in region eu, komrade:test is only available region us) ...
If the add-ons can’t be provisioned because the original plan no longer exists, upgrade the plan on the source app to ensure a seamless migration.
$ heroku addons:upgrade memcachier:dev -a sourceapp Upgrading to memcachier:dev on sourceapp... done, v207 (free)
Re-run the fork command until it succeeds without error. Prior to each run make sure incomplete provisions of
targetapp are destroyed.
$ heroku apps:destroy -a targetapp
Manual add-on configuration
There are some add-ons that require additional configuration after provisioning. There may be others beyond the add-ons listed below so please review your app’s add-ons for any that require manual configuration steps.
Although the forking process re-provisions the SSL Endpoint on
targetapp it does not migrate the required certs on your behalf. If your app uses SSL you need to add the original certs to your SSL endpoint instance on
$ heroku certs:add server.crt server.key -a targetapp Resolving trust chain... done Adding SSL Endpoint to targetapp... done targetapp now served by targetapp.herokuapp.com
The Heroku Scheduler add-on requires that the job schedule be manually transferred. Open the scheduler dashboard for both
targetapp side-by-side to view the diffs and manually copy the jobs.
$ heroku addons:open scheduler -a sourceapp $ heroku addons:open scheduler -a targetapp
Once forking has completed and all add-on configuration has been duplicated, open the forked application to verify it’s functioning properly before proceeding with the final migration steps.
$ heroku open -a targetapp
If your app uses OAuth, or any other domain-specific external service, you may have to provision a new service for use during this verification phase when the domain is not the same as your production setup.
Once your forked app has been verified to be functioning properly you can begin the cut-over process.
Apps with custom domains should manually adjust their DNS settings as opposed to performing an app rename or using a DNS add-on. These alternatives are either not supported or incur non-trivial downtime.
If your app has custom domains, you should lower the TTL for each of them with your DNS provider to a low value, such as 60 or 120 seconds. This minimizes the amount of downtime that results from changing your records during the migration process and allows you to quickly correct any DNS related errors.
To ensure that all DNS caches are updated with the new TTL, you should wait at least as long as the previous TTL before proceeding with the migration.
Although the app-forking process creates a new database, it’s only used to verify the new app’s setup. The actual database migration should occur only when the
sourceapp is in maintenance mode (to avoid data being written during the migration) and should be done in a way that minimizes application downtime.
If you have a production tier database you can provision a follower in advance and wait until it is up-to-date with the master database before cutting over apps. (Development tier database users can bypass this step as their database migration will occur completely during the cut-over phase).
Provision a new database (of the same plan) on
targetapp to follow the current database on
$ heroku addons:create heroku-postgresql:standard-0 -a targetapp --follow `heroku config:get DATABASE_URL -a sourceapp` Adding heroku-postgresql:standard-0 on targetapp... done, v32 ($50/mo) Attached as HEROKU_POSTGRESQL_CHARCOAL_URL Follower will become available for read-only queries when up-to-date Use `heroku pg:wait` to track status. $ heroku pg:wait -a targetapp Waiting for database HEROKU_POSTGRESQL_CHARCOAL_URL... / available
After the follower has become available it may take some time for it to receive all the data from the source database. Use the
pg:info command to view how many commits behind the follower is from the source database.
$ heroku pg:info -a targetapp === HEROKU_POSTGRESQL_CHARCOAL_URL Plan: Standard 0 Status: available Region: eu-west-1 ... Behind By: 47980 commits
Only when the follower is, at most, a few hundred commits behind should you begin the application migration.
To ensure that no data modification occurs during the migration process,
sourceapp should be put in maintenance mode.
From this point forward the source application will be inaccessible to your users. Only when the app has been migrated and all DNS propagation complete will the target app be accessible. Please plan for this downtime appropriately.
$ heroku maintenance:on -a sourceapp Enabling maintenance mode for sourceapp... done
sourceapp in maintenance mode it’s now safe to migrate data to
targetapp. The approach you take here depends on your Heroku Postgres database tier.
Production tier database
If you have a production tier database and have created a follower database on
targetapp, wait until it is fully caught up (0 commits behind) and promote it to be the master.
$ heroku pg:info -a targetapp === HEROKU_POSTGRESQL_CHARCOAL_URL Plan: Standard 0 Status: available Location: eu-west-1 ... Behind By: 0 commits $ heroku pg:unfollow -a targetapp HEROKU_POSTGRESQL_CHARCOAL_URL Unfollowing HEROKU_POSTGRESQL_CHARCOAL_URL... done $ heroku pg:promote -a targetapp HEROKU_POSTGRESQL_CHARCOAL_URL Promoting HEROKU_POSTGRESQL_CHARCOAL_URL to DATABASE_URL... done
The follower database is now the primary database for
targetapp and its location has been copied to the
DATABASE_URL config var.
If you are using a hobby database (
hobby-basic) you will need to use PG Backups to transfer your database. You can use
pg:copy to transfer the database directly:
$ heroku pg:copy sourceapp::DATABASE_URL DATABASE_URL -a targetapp
This process can take some time depending on the size of your database.
Other add-on providers may have a different procedure for migration, or no migration functionality at all. Whether the data needs to be migrated is a question of how you’re using that add-on. Please see the documentation for your add-on providers for more information.
heroku ps to examine your dynos, copy the dyno formation from
$ heroku ps -a sourceapp === web: `bundle exec thin start -p $PORT` web.1: up 2013/02/12 18:56:17 (~ 20h ago) web.2: up 2013/02/12 19:14:45 (~ 19h ago) $ heroku scale web=2 -a targetapp
Check your logs to ensure the dynos started properly.
$ heroku logs -t -n 1000 -a targetapp
targetapp to receive user activity, Heroku must know which domain is served by your app. List the custom domains on the old app:
$ heroku domains -a sourceapp === sourceapp Domain Names www.example.com
For each of these domains, remove them from the
sourceapp and add them to
$ heroku domains:remove -a sourceapp www.example.com Removing www.example.com from sourceapp... done $ heroku domains:add -a targetapp www.example.com Adding www.example.com to targetapp... done
To route traffic to your new app, adjust the DNS settings so any custom domains resolve to
targetapp. Add the following CNAME record in your DNS provider’s control panel.
A-records are not supported. If required, use a DNS-level redirect or ALIAS record to resolve the root domain to
If you’re using the SSL Endpoint add-on, no additional DNS configuration is required (this differs from the default region behavior, which requires using a domain like
tokyo-123.herokussl.com). All traffic to
www.example.com can now be served over SSL.
If you’ve adjusted your DNS TTL to a low value it shouldn’t take more than a few minutes for requests to be routed to targetapp. Inspect the logs on targetapp to verify that requests are properly resolved and handled.
$ heroku logs -t -a targetapp
Once the DNS changes propagate all requests to your custom domain should be served by the new EU location.
Update git remotes
Forking your application doesn’t automatically create a new git remote in your current project. To deploy to
targetapp you will need to establish the git remote yourself. Use
heroku info to retrieve the Git URL of the new application and the set it manually.
$ heroku info -a targetapp === targetapp ... Git URL: email@example.com:targetapp.git ... $ git remote add forked firstname.lastname@example.org:targetapp.git
In this example,
targetapp‘s git remote is named
forked. Deploy to this app with:
$ git push forked master
If you wish to make the new app the default deployment target (after migration) you can rename the git remotes.
$ git remote rename heroku old $ git remote rename forked heroku
targetapp is now the default deployment target for all future deploys. After a reasonable period of time, be sure to de-provision any unused resources on
Forked app state
Forked apps are as close to the source app as possible. However, there are some differences.
No users from the source app are transferred over to the forked app. You need to add collaborators yourself.
$ heroku access:add email@example.com -a targetapp
Any enabled Heroku Labs features on
sourceapp are not re-enabled on
targetapp. You will need to re-enable these yourself.