AWS – Promoting an RDS read replica to master

How to set a static IP address on Windows Server 2019

We’re going to show you how to promote an RDS read replica to be a primary instance. There are a few reasons you might like to do this:

  • To handle a table migration that would typically cause a large amount of downtime, especially when messing with columns or indexes
  • Because you need to implement sharding
  • Recovery from failure, should you choose not to deploy your existing primary in multi-AZ mode (not recommended)

Getting ready

You’re going to need the unique ID that has been assigned to an RDS read replica. If you followed the Creating a database with automatic failover and Creating a database read replica recipes, then you’ll be all set.

It’s also a good idea to have backups enabled on this read replica before promoting it. This shortens the promotion process because you won’t need to wait for a backup to be taken. You’ll want to set the backup retention period to a value between 1 and 8.

Enabling backups on your read replica will cause it to reboot!

To enable backups, you can use the following CLI command:

aws rds modify-db-instance \
  --db-instance-identifier <identifier-for-read-replica> \
  --backup-retention-period <days-to-keep-backups-for> \
You can drop the --apply-immediately parameter if you prefer to wait for the reboot to happen during the configured maintenance window. But you’ll still want to wait until after the reboot happens before you continue with the promotion process.
To ensure that you have the most up-to-date data before promotion, you’ll want to stop all write traffic to the current source primary DB before going ahead. It’s also a good idea to make sure that the replication lag on your read replica is 0 (you can check this in CloudWatch).

How to do it…

Complete the following steps to learn how to promote a read replica to master:

  1. Run the following command to promote your read replica to a primary DB instance. This command will cause your read replica to reboot:
      aws rds promote-read-replica \
        --db-instance-identifier <identifier-for-read-replica>
  1. If you wish to then go ahead and configure your new primary RDS instance to run in a multi-AZ configuration, then you’ll need to run this additional command. Expect to wait a while for this operation to complete:
      aws rds modify-db-instance \
        --db-instance-identifier <identifier-for-new-primary> \
        --multi-az \

How it works…

Promoting a read replica can serve several different purposes, such as allowing you to apply time-consuming schema changes without disrupting your primary instance, or to split your database into shards by partitioning data onto multiple primary instances.

The read replica reboots when you promote it and the promotion can take a while since there are significant changes that have to be made to the database configuration to disconnect it as a replica and bring it up as a primary. Configuration items such as backup retention and parameter groups are copied from the original primary to the newly promoted primary.

Transactions to the read replica must be stopped before promotion, and the database must be in a read-only state.

Comments are closed.