AWS Database Blog

How to rename and retain the endpoint name for Amazon RDS

Amazon Relational Database Service (Amazon RDS) is a managed database service that simplifies database setup, operation, and scaling. An Amazon RDS endpoint is a unique network address assigned to each database instance within RDS, enabling applications to connect and interact with the database. Endpoints are DNS names that resolve to the database’s current IP address. They’re used in application configurations to establish secure connections and manage database operations efficiently. RDS endpoints abstract the underlying database infrastructure, providing seamless integration with AWS services and applications.

For tasks that involve restoring a database snapshot (where Amazon RDS always creates a new database instance) or promoting a read replica to replace an existing RDS instance, you might need to update the application configuration to point to the new RDS database endpoint. This can be cumbersome, depending on how and where the application refers to the RDS endpoint.

In this post, we provide a step-by-step guide to update the endpoint name for a new RDS instance while keeping the existing endpoint name, along with key considerations for this process.

Solution overview

To rename an existing RDS DB instance you can use the AWS Management Console, AWS Command Line Interface (AWS CLI), or Amazon RDS API to modify the RDS endpoint name. In this post, I use the console to demonstrate the process. For instructions, see Renaming to replace an existing DB instance.

The high-level steps to this solution, as shown in the following diagram, are:

  1. Stop the traffic connecting to the active primary RDS DB instance.
  2. Rename the existing primary RDS DB instance to indicate it’s no longer primary. The DB instance will be rebooted when it’s renamed. For instructions, see Renaming a DB instance
  3. Modify the restored instance to match the endpoint name of the previous primary DB instance if the target DB instance is created before Step 2 or if a read replica is promoted. For instructions, see Modifying an Amazon RDS DB instance. For scenarios where the target DB instance is being created or restored after step 2, you can give the new RDS instance the name of the previous primary DB instance. See Creating an Amazon RDS DB instance.
  4. Associate any read replicas with the new primary DB instance.

Deployment

Because renaming an Amazon RDS DB instance requires downtime to redirect the existing workload traffic to a new RDS instance, be aware of the following considerations before you rename a DB instance

In the demonstration, I use two existing Amazon RDS DB instances. The primary instance endpoint name is test-instance.cxvub4jf47su.ap-southeast-1.rds.amazonaws.com. The name of the DB instance to be replaced is restored-instance.cxvub4jf47su.ap-southeast-1.rds.amazonaws.com, as shown in the following figures.

  1. Use the Amazon RDS console to navigate to the test instance, as shown in the following figure.
  1. The second figure shows the restored instance.
  1. Rename and modify the DB instance identifier for the existing primary instance. Note: This will require a reboot, so choose an appropriate time to make the change. The following figure shows renaming the existing instance.
  1. As shown in the following figure, select Apply immediately, and then Modify DB instance.
  1. After the modification is applied, the existing primary RDS instance is rebooted, changing the state to Renaming, as shown in the following figure.
  1. When the process is complete, the existing primary RDS instance is available with the renamed endpoint, as shown in the following figure.
  1. Modify the restored instance to match the earlier existing primary instance’s endpoint, as shown in the following figure.
  1. After rebooting, the instance is available with the assigned name as test-instance, as shown in the following figure.

The renamed endpoint for the restored or promoted instance will be same as the previous instance. This allows the applications to connect to the new instance seamlessly with no changes.

Depending on the use case, you can either stop or delete the older instance.
Note: If you delete the old primary DB instance, you are responsible for deleting any unwanted DB snapshots of that instance. For reference, see Stopping an Amazon RDS DB instance or Deleting a DB instance.

Considerations

  • Renaming the instance to retain an existing endpoint is only possible within the same AWS Region and account because the DB endpoint URL includes a suffix unique to an account and Region.
  • When a DB instance is renamed, the old DNS name that was used by the DB instance is immediately deleted, although it might remain cached for a few minutes. The new DNS name for the renamed DB instance becomes effective in about 10 minutes. The renamed DB instance isn’t available until the new name is effective.
  • All read replicas associated with a DB instance remain associated with that instance after it’s renamed. You need to create new read replicas for the newly created or modified instance. For example, consider an RDS instance that serves as a production database and has associated read replicas. If you rename the DB instance and then replace it by restoring a DB snapshot with the new instance as a production environment, the old DB instance that was renamed will still have the read replicas associated with it.
  • Amazon CloudWatch metrics and events associated with the name of a DB instance are maintained if you reuse a DB instance name. For example, if you promote a read replica and rename it to be the name of the previous primary DB instance, the events and metrics associated with the old primary DB instance are associated with the newly renamed instance.
  • DB instance tags are not modified with the DB instance, regardless of renaming. If a change is necessary, it must be made explicitly.
  • DB snapshots for the renamed DB instance are retained.

Clean up

Complete the following steps to clean up the resources you created in this post. On the Amazon RDS console, in the navigation pane, choose Databases.

  1. Select the RDS instances that you created for this tutorial and want to delete.
  2. On the Actions menu, choose Delete.
  3. To take a final snapshot, choose Create final snapshot and enter a name for the snapshot.
  4. To retain automated backups, choose Retain automated backups.
  5. Enter delete in the box.
  6. Choose Delete.

Conclusion

In this post, you learned how to modify and retain the same endpoint name for existing Amazon RDS DB instances. This applies to use cases where you want to replace an endpoint name by creating a completely new DB instance, restoring a DB instance snapshot, or promoting a read replica. You also learned the key considerations when modifying endpoint names.

If you have any comments or questions, leave them in the comments section. To know more about AWS RDS, see getting started with Amazon RDS.

About the Author

Kanwar Nain Singh is a Senior Specialist Database Solutions Architect with Amazon Web Services. He has experience engineering and architecting migrations and modernization of relational and non-relational database stacks on AWS Cloud.