Migrate from Heroku to Build

Build is Heroku-compatible at the buildpack, API and CLI level, so most conventional Heroku applications run on Build without code changes. Rather than recreating an app by hand, you connect your Heroku account and Build syncs the app across for you.

There are two parts to a migration: your application, which the sync handles in a few minutes per environment, and your data, which moves separately. You do not have to do both at once. Many teams move the application first, run it against their existing Heroku database, and move the data later.

For what changes technically once you are on Build, see Compare Build & Heroku.

1. Connect your Heroku account

In Build, open Settings and connect the Heroku integration. You are asked to authorize Build against your Heroku account, and it takes a few seconds.

You do this once per Build account, not once per app.

2. Create the app on Build

Open the team you are deploying into and click New app. Set the team, the pipeline, and which stage of that pipeline the app occupies, for example staging or production.

Give it the same name it has on Heroku. Nothing requires this, but it makes the pairing obvious once you have several apps.

3. Sync the app across

Open the app’s Settings and choose Configure Sync. Pick the Heroku app to sync from and the Build app to sync to, then choose what to bring across. On a first sync, select everything except Releases and Images, which import build history you are unlikely to need.

Click Create, then trigger the sync with the button in the top right. It usually takes two to three minutes, and you can watch it in Latest Activity.

The sync stays live after that. Heroku notifies Build whenever the app changes, so you can carry on deploying to Heroku and let Build follow along while you validate.

4. Start the app and check it

A synced app starts with its dynos at zero, so nothing is running yet. Scale your web process to one dyno, then click Open App and confirm it serves as it does on Heroku. Check your config vars arrived and the app landed in the right stage of the pipeline.

If anything is missing, fix it and run the sync again. Nothing is serving production traffic yet, so repeating this costs nothing.

Scale your workers only when you mean to run them. The synced app still points at your Heroku database, so a worker dyno started here will pick up real jobs from your production queue and act on them.

5. Repeat for your other environments

Each environment is its own Build app, synced from its own Heroku app, in its own stage of the pipeline. Start with staging and move to production once you are happy.

Your database

The sync copies configuration, not data. That includes DATABASE_URL, so a freshly synced app connects to your Heroku database. This is useful while you validate, because Build runs against real data without anything being copied.

When you are ready to move the data:

1. Provision the database on Build. Heroku Postgres is replaced by Schema To Go. Set import_url to your existing database when you create it, and Build pulls the data across for you. How long that takes depends on the size of the data.
2. Attach the new database to your app. In the add-on’s Attachments section, choose Attach to App and set the attached-as name to DATABASE. Build maps the add-on’s variables to that prefix, so your app sees DATABASE_URL. Setting the config var by hand works too, but attaching keeps the app and the add-on in step.
3. Stop syncing config vars, or the next sync will overwrite DATABASE_URL and point the app back at Heroku.
4. Redeploy.

A large production database usually wants a replication-based approach rather than an import, so that cutover is a short switch rather than a long copy.

Engineer-led migration support is included on Enterprise plans, and the data move is the part our engineers most often run with customers. Talk to us before you move production data.

6. Cut over

When you are satisfied, move traffic by pointing DNS at Build. Nothing is taken offline to do it, and your Heroku app keeps running, so you can point DNS back if you need to.

Need help

See Get support, or talk to an engineer about your migration.