Learn how to upgrade your Heroku database easily and with the quickest downtime. We walk you through the exact steps needs to roll over your PostgreSQL database in this quick read.

We will continue our Heroku series of blog posts with an important task you’ll encounter when your application starts to grow: upgrading your database. Most probably you started out on your Heroku journey with a smaller PostgreSQL plan - which is fine at the beginning but at some point you will likely need to upgrade. Database migrations don’t have to be time consuming. Nobody wants their website down for hours at a time. If you’d like to to upgrade your database with the shortest downtime possible, then this blog post is for you. Let’s get on with doing your PostgreSQL update with zero downtime.

Upgrading your Heroku Database

Process: We will use use PostgreSQL replication for syncing our data to the new instance, quickly replacing master with the new database by using promotion. The following are the Heroku database update methods.

NOTE: We assume that HEROKU_POSTGRESQL_OLD is your current database and HEROKU_POSTGRESQL_NEW is new database.

Step 1. Create a new follower instance:

heroku addons:create heroku-postgresql:plan-name --follow HEROKU_POSTGRESQL_OLD --app app-name

If you want to be notified when the replica is ready to run:

heroku pg:wait --app app-name

To check status of the databases manually, run:

heroku pg:info --app app-name

2. Turn on maintenance mode to prevent applications modifying the database:

# Turn on maintenance mode
heroku maintenance:on --app app-name

# Scale down workers - maintenance mode does not do it automatically.
# Remember to scale down all workers which can potentially write to the database,
# i.e. web=0 worker=0 pdf=0, etc.
heroku ps:scale web=0 --app app-name

3. Promote the follower to be a new master:

heroku pg:unfollow HEROKU_POSTGRESQL_NEW --app app-name
heroku pg:promote HEROKU_POSTGRESQL_NEW --app app-name

4. Now we are ready to bring our application back from maintenance mode:

# You need to restore all workers that have been scaled down in step 2
heroku ps:scale web=1 --app app-name
heroku maintenance:off --app app-name

And just like that, your application is using the new database as a data store! You have now learned how to update the Heroku database with no downtime. If everything is running fine you can remove the old database with this command:

heroku addons:destroy HEROKU_POSTGRESQL_OLD

Follow us at iRonin for more DevOps and Heroku hints, tips, code snippets, and more. Our team of seasoned developers and DevOps experts are on hand to help with all your bleeding edge needs to make your project fast, smooth, and efficient, including setting up your IT infrastructure, web applications development, systems consultancy, PostgreSQL administration services, Heroku configuration services, and more. Email us for a chat if you’re interested in any of our services or have any curly questions.