Migrating From Heroku to Render: A Runbook for an App With Real Users
You’ve decided to move your app from Heroku to Render, or you’re close to deciding, and you’ve started reading. What you’ve found so far probably falls into two piles. One is Render’s own documentation, which is clear and accurate and written around a single generic app. The other is a long tail of first-person migration diaries from people who moved one project once and wrote up what happened. Both are useful, but neither tells you what changes when the app has paying customers, a database that’s written to every minute, and a Sidekiq queue full of jobs that can’t simply stop because you changed a DNS record.
This post is the runbook we’d want if we were in your position. It assumes you’ve already made the bigger call about whether and how to move (our post on cloud migration for a custom application covers that decision), and it goes straight at the specifics of a Heroku-to-Render move for a Rails app.
Start with Render’s migration docs, and know where they stop
Render publishes a Heroku migration guide that covers the mechanics well, and you should follow it for the actual commands. It walks through creating the Postgres database, Key Value instance, web service, and workers in the Render dashboard, and it describes a cutover where you put the Heroku app into maintenance mode, copy the database across with pg_dump and pg_restore, and then update DNS. We won’t repeat that syntax here, because the source will stay better maintained than any copy of it.
What the docs leave to you is most of what makes a production move nerve-wracking. They say plainly that the cutover requires downtime, even if brief, but they don’t describe how to keep that window short or what to do if the new environment misbehaves after you switch. There’s no rollback procedure, and Redis comes up only at the step where you create the new instance, with nothing about the data already sitting inside the old one. Render’s longer guide to leaving Heroku fills in some of the strategy, including a rollback approach, but it treats Rails as one framework among many and stops at mapping your workers when it gets to background jobs.
How Heroku concepts map to Render
It helps to name the pieces once so the rest of this post can refer to them. Each process type in your Procfile becomes its own Render service, so the web process becomes a web service and each worker process becomes a background worker. Heroku Scheduler entries become Render cron jobs. Config vars become environment variables, which you can collect into environment groups and share across services. Heroku Postgres becomes Render Postgres, and Heroku Redis becomes Render Key Value.
The mapping is mostly mechanical, and the docs cover the details. The two rows that deserve real planning time are the workers and the database, because those are where data is in motion at the moment you switch.
Background jobs are the part that breaks
A Sidekiq queue doesn’t pause because traffic moves somewhere else. Your Heroku workers read from Heroku Redis and your Render workers will read from Render Key Value, so any job enqueued on the old side during the switch is invisible to the new one, and any job that was mid-run when its worker stopped needs a plan. The answer is to drain the queue deliberately before the database moves.
Sidekiq gives you the tools to do that. Sending a worker the TSTP signal puts it into quiet mode, where it stops fetching new jobs but keeps working on the ones it already has. TERM asks it to shut down within its timeout, and any job that hasn’t finished when the timeout runs out is forcefully stopped and pushed back to Redis to run again when Sidekiq starts up. That timeout defaults to 25 seconds, chosen because Heroku requires every process to exit within 30. That keeps jobs from being lost, but it means a job that was halfway through when the worker stopped will run again from the beginning, so it had better be safe to run twice. Before migration day, go through your job classes and find the ones that charge a card, send an email, or call an outside API without first checking whether the work was already done.
Then sequence the drain. Stop new work from arriving (maintenance mode does most of this, since web requests stop reaching the app), quiet the workers, and watch the queues empty. The busy queues aren’t the only state in Redis, though. Sidekiq keeps scheduled jobs, retries, and dead jobs in sorted sets, and Sidekiq::ScheduledSet.new.size and Sidekiq::RetrySet.new.size tell you how many are waiting. Those jobs won’t come across if you start Render Key Value empty, so decide in advance whether you’ll let them come due before the cutover, copy them into the new Redis with a short script, or let them go because losing them is harmless. If you skip this step, a weekly report scheduled for next Tuesday can quietly vanish, and nobody will notice until the week after.
Scheduled tasks need the same care. During the transition each one should be enabled on exactly one platform, because a nightly billing task that runs on both Heroku Scheduler and a Render cron job charges customers twice. Turn off the Heroku Scheduler entry in the same step that turns on its Render replacement.
Cutting over the database
The constraint that shapes the whole plan is that Heroku doesn’t support logical replication, so you can’t keep a Render database trailing the live Heroku one by a few seconds and switch over at leisure. Render’s own guide says this directly and concludes that zero downtime isn’t a realistic goal for this particular move. What you can realistically aim for is a short, rehearsed write freeze.
So most of the effort moves to the days before the switch. We deliver major Rails and Ruby upgrades with zero downtime, and the same habits apply here even though the result can’t be identical. Stand the Render environment up completely before any traffic reaches it, with every service deployed, every environment variable set, and a recent copy of the data restored so you can test the app through a temporary hostname. Then rehearse the dump and restore against a fresh copy of production and time it from start to finish. That number is your downtime, and knowing it ahead of time lets you schedule the freeze for your quietest hour and tell customers how long it will last.
On the day itself the sequence is short. Put Heroku into maintenance mode, drain and stop the workers as described above, take the final dump, restore it into Render Postgres, start the Render workers, check the app through its temporary hostname, and change DNS. Render’s guide cites two of its customers’ moves as reference points, with ReadMe’s cutover taking about 90 seconds of downtime and BeerMenus’s about fifteen minutes. Where your app lands between those depends mostly on the size of your database, which is why the rehearsal matters so much.
Write the rollback down before you need it
Lower your DNS time-to-live several days before the move, so that when you change the record, traffic follows within minutes and can follow back just as quickly. Then write down, before cutover, what counts as failure: an error rate above a number you pick, a health check that doesn’t pass, or a job that should have run in the first hour and didn’t. Agree on a deadline as well. If the new environment isn’t healthy by a set time after the switch, you roll back without debating it in the moment.
Rolling back only works if Heroku is still there to roll back to. Keep the Heroku app, its database, and its add-ons intact for a defined window after cutover, with the database kept read-only and the worker dynos scaled to zero instead of deleted. Render’s guide also lists replaying enqueued jobs as part of the cutover plan, and the drain work above is what keeps that list short. Remember that anything written to Render Postgres after the switch has to come back with you if you fall back, so keep the decision window measured in hours and make the call early.
Running production apps on both platforms
We run production client applications on both platforms today. The Wine Spies runs on Render, another client application we maintain runs on Heroku, and eclipticideas.com itself is a Rails 8 application deployed to Render. Because we work on both sides every week, we know where the platforms differ in practice, from how workers start to how scheduled work is configured.
If your app also needs a framework upgrade, plan that as its own project. Our cloud migration guide explains why combining a major upgrade with a host move stacks two risks on top of each other, and our guide to upgrading Rails 6 to 7 covers the upgrade side.
Where to start on your own migration
Spend an hour building three lists for your app. The first is every Sidekiq job class, with a note on whether it’s safe to run twice, plus a count of the scheduled and retry jobs sitting in Redis right now. The second is your database size and how long a dump and restore takes against a copy of it. The third is your current DNS TTL alongside every entry in Heroku Scheduler. Any line you can’t fill in is a risk to plan for before migration day, and the finished lists are the most useful thing you can bring to a planning call. If you’d like to walk through yours with us, book an intro call.