Promoting an RDS Read Replica to Primary is a critical operation that allows you to failover to a standby database instance without data loss.
Let’s see how this actually works with a quick example. Imagine you have a primary RDS instance my-primary-db and a read replica my-primary-db-replica.
First, we need to identify the replica we want to promote. You can find this in the AWS RDS console under your database instances. It will have a "Replication role" of "Replica".
aws rds describe-db-instances --db-instance-identifier my-primary-db-replica --query "DBInstances[*].DBInstanceStatus"
This command will show you the current status of the replica. If it’s available, you’re good to go.
Now, to promote it, you use the promote-read-replica command.
aws rds promote-read-replica --db-instance-identifier my-primary-db-replica
This command doesn’t return much on success, but the RDS console will show the DBInstanceStatus changing from replicating to promoting and finally to available.
Once the replica is available, it’s no longer a replica. It’s a standalone, primary database instance. Its endpoint will remain the same, but it will now accept writes. Your application should be configured to connect to the primary endpoint.
The key to this operation is that RDS ensures the replica is fully caught up with the primary before it allows the promotion to complete. This is what guarantees no data loss. It waits for all pending replication events to be applied.
The most surprising truth about promoting an RDS Read Replica is that the original primary instance, if it’s still running, doesn’t automatically shut down or become unavailable. It continues to operate as an independent database. This means you need to manually ensure that your application is pointing to the new primary and that the old primary is no longer accepting write traffic, or is decommissioned. Failing to do this can lead to split-brain scenarios where both instances accept writes, corrupting your data.
To verify the promotion, you can check the instance details in the RDS console. The "Replication role" will no longer be "Replica". You can also try connecting to the instance with a write operation.
# Example: Connect using psql and try an INSERT
psql -h my-primary-db-replica.abcdefg12345.us-east-1.rds.amazonaws.com -U admin -d mydb
# Inside psql:
# CREATE TABLE test_promotion (id serial primary key, message varchar(255));
# INSERT INTO test_promotion (message) VALUES ('Promotion successful!');
# SELECT * FROM test_promotion;
If the insert and select succeed, the promotion is complete and the instance is now a writable primary.
The next step in managing your high-availability strategy after promoting a replica is to consider creating a new read replica from the newly promoted primary, or even a new multi-AZ deployment for enhanced resilience.