Get Started

Migrate from Heroku to Render

Bring your Heroku apps and data to the Render platform.

This guide helps you move your Heroku-hosted apps and datastores to Render.

You’ll learn:

  • How Heroku concepts map to the Render platform
  • How to model a Heroku app as one or more Render services
  • How to move your Heroku datastores to PostgreSQL and Redis on Render

Why migrate?

Many developers find that running on Render reduces costs and provides more capabilities out of the box, such as private networking, long-lived connections, and built-in DDoS protection.

Learn more:

Get support

If you need any help with your migration, please reach out to our support team via the chat bubble in the Render Dashboard.

Migrating a large database? We’re previewing an upcoming tool for low-downtime PostgreSQL migration and are looking for organizations with a large (50+ GB) Heroku Postgres database to migrate. We’ll work with selected organizations to help ensure a successful, speedy migration.

Apply for the preview.

Concept mapping

Most Heroku concepts map cleanly to comparable functionality on Render:

HerokuRender

Your app’s web process

Web service

Your app’s other processes

Background workers

Release phase

Pre-deploy command

Heroku Scheduler / clock processes

Cron jobs

Config vars

Environment variables

Dyno

An instance of a service

Dyno type (Eco, Basic, etc.)

Instance type (Free, Starter, etc.)

Heroku Postgres

PostgreSQL on Render

Heroku Key-Value Store

Redis on Render

1. Prepare to migrate

First, let’s make sure you have all the accounts and app details you need to migrate successfully.

Create your Render account

Sign up for Render

Catalog your Heroku resources

Identify the Heroku apps you want to migrate. Note the following for each:

  • Processes defined in the app’s Procfile
  • Defined config vars (i.e., environment variables)
  • Any attached Heroku Postgres and Heroku Key-Value Store add-ons

You can continue using many Heroku add-ons after moving your app to Render.

For example, if you’re using Heroku’s Sendgrid add-on, you can set all of your app’s SENDGRID_* environment variables on your new Render service.

2. Recreate your app on Render

Next, we’ll spin up Render resources that correspond to your Heroku app’s processes and datastores.

Create datastores

We recommend creating any necessary PostgreSQL and Redis instances on Render before you deploy the apps that use them. This way, your apps can connect to those datastores on their very first deploy.

We won’t move your existing data from Heroku to Render yet.

We’ll do this as part of the final migration process.

Follow these steps for each Heroku Postgres and Heroku Key-Value Store add-on you want to move:

  1. In the Render Dashboard, click New > PostgreSQL or New > Redis:

    Creating a new web service in the Render Dashboard

  2. Specify the following:

    • Your datastore’s name
    • The region where you want to host the datastore
    • Which instance type to run on
      • Render offers a free instance type for both PostgreSQL and Redis to help you get started. See details.
    • Your starting storage (PostgreSQL only)
      • Start with a small amount of storage (1 GB or 5 GB) for testing. You can increase storage later at any time.

  3. Click the Create button.

    Render provisions your new datastore, and it becomes available within a minute or two.

  4. After your datastore becomes available, open its Info page in the Render Dashboard and click the Connect dropdown in the top right:

    Viewing a database's internal URL

  5. Copy your datastore’s internal URL. Your Render services will use this URL to connect to the datastore over a private network.

    • External clients (like your local development environment) can instead connect to the datastore via its external URL, which is available in the same dropdown.

  6. Repeat this set of steps for each Heroku Postgres and Heroku Key-Value Store add-on you want to move.

Create services based on your Procfile

Most Heroku apps define a file named Procfile in their repo’s root directory. This file defines startup commands for each of the app’s distinct processes.

Here’s an example Procfile for a generic Node.js app (the same concepts apply to any language):

# Procfile

# web process
web: npm run start

# non-web process
worker: npm run worker

# release phase command
release: db-migrate -e prod up

Let’s look at how to replicate this configuration on Render.

The web and release processes

Your Heroku app’s web process is the only process that receives HTTP traffic from the internet. On Render, this corresponds to a web service. Every web service receives an onrender.com subdomain, and you can add your own custom domains.

  1. In the Render Dashboard, click New > Web Service:

    Creating a new web service in the Render Dashboard

  2. Specify the following:

    • Your project repo and branch to deploy (from GitHub, GitLab, or Bitbucket)
    • The runtime for your app’s language (Node.js, Python, etc.)
    • The region where you want to host the service
      • Choose the same region as your datastores to enable low-latency private network communication.
    • Which instance type to run on (similar to Heroku dyno types)

  3. Provide the commands that Render will use to build and run your code:

    CommandValue

    Build Command

    In most cases, provide the same command you use to build your project locally, such as npm install for Node.js or pip install -r requirements.txt for Python.

    If necessary for your framework, modify the command to create a production build instead of a development build.

    Pre-deploy Command (optional)

    Provide the same command as your Procfile’s release process, if any.

    Similar to Heroku’s release phase, Render runs the pre-deploy command just before each deploy of your service. Use it to run database migrations and other setup tasks.

    Start Command

    Provide the same command as your Procfile’s web process.

    Common examples of start commands include npm run start for Node.js and gunicorn your_application.wsgi for Python.

    Here are commands for the example Node.js Procfile above:

    Setting deploy-related commands in the Render Dashboard

  4. Set any required environment variables for your web service:

    Setting environment variables in the Render Dashboard

    • For datastore connections, provide the internal datastore URLs you copied earlier.
      • These environment variables are usually named DATABASE_URL for PostgreSQL and REDIS_URL for Redis.
    • For other environment variables, copy over the values from your Heroku app’s config vars.
    • You can make changes to your service’s environment variables at any time after your service is created. See details.

  5. Click Deploy Web Service.

You’re all set! Render kicks off your service’s first deploy. You can view the build logs in the Render Dashboard.

When the deploy completes, your service will be live at its onrender.com subdomain. If you encounter any issues, see Troubleshooting Deploys.

Non-web processes

If your app defines non-web processes in its Procfile, those processes don’t receive incoming network traffic. Instead, they usually process jobs from a queue. On Render, these correspond to background workers:

Creating a new background worker in the Render Dashboard

The steps for creating a background worker are similar to those for creating a web service. The key differences are:

  • Your background worker probably doesn’t need to run a pre-deploy command if your web service already handles database migrations.
  • Render does not provide a free instance type for background workers.

Complete the background worker creation process for every non-web process in your app’s Procfile, specifying the appropriate build and start command for each.

Services do not share environment variables by default.

If your web service and background workers require some of the same environment variables, you can do one of the following:

  • Manually set the environment variables for both services
  • Create an environment group and apply it to both services

3. Swap over to your Render infrastructure

With everything up and running on Render, we’re ready to move your data and DNS configuration over from Heroku.

This final migration process requires downtime for your app.

Schedule your migration for off hours to minimize the impact on your users.

For assistance with a complex migration, please reach out to our support team in the Render Dashboard.

Scale up your Render datastores

Before you move over your data, make sure your Render PostgreSQL and Redis instances have sufficient storage and compute resources to handle your current requirements. You can upgrade as needed in the Render Dashboard.

PostgreSQL

  • You can increase your storage at any time without downtime, but you can’t decrease it.
  • You can upgrade or downgrade your instance type at any time. Your database will be unavailable for a few minutes during the change.

Redis

  • You can upgrade your instance type at any time. Your Redis instance will be unavailable for a few minutes during the change.
  • You can’t downgrade your instance type.

Enable maintenance mode on Heroku

When you’re ready to kick off the migration, put your Heroku app into maintenance mode so that it no longer accepts user traffic. This helps ensure that no changes are made to your datastores during the migration.

Using the Heroku CLI, run:

heroku maintenance:on --app <YOUR HEROKU APP NAME>

Export data from Heroku Postgres

  1. Create a backup of your database.

    Using the Heroku CLI, run:

    heroku pg:backups:capture --app <YOUR HEROKU APP NAME>

  2. Download the backup.

    Using the Heroku CLI, run:

    heroku pg:backups:download --app <YOUR HEROKU APP NAME>

    This downloads a file named latest.dump to your local computer.

Import data into Render PostgreSQL

  1. Obtain your Render PostgreSQL database’s External Database URL from its Info page in the Render Dashboard.

  2. Import latest.dump into your Render PostgreSQL database.

    pg_restore --verbose  --no-acl --no-owner -d <YOUR RENDER DB EXTERNAL CONNECTION STRING> latest.dump

If your database is larger than 20GB or under heavy load, use Heroku’s instructions to create a backup of your data.

After the backup completes, you can use the same pg_restore command above to import the data to your Render PostgreSQL database.

Consider using the --jobs flag available to both the pg_dump and pg_restore commands to reduce the time required for backup and restore.

Update your DNS records

If your Heroku app uses a custom domain, follow the instructions to update your DNS configuration to point to Render instead of Heroku. Apply each app’s custom domain to the corresponding Render web service.

Note that it will take some time for your DNS changes to propagate, and for Render to then provision a TLS certificate for your domain.

Next steps

Congratulations! You’ve successfully migrated your Heroku app to Render.

Next, explore more of Render’s capabilities. Here are a few to get you started: