# Amazon Aurora endpoint connections Amazon Aurora typically involves a cluster of DB instances instead of a single instance. Each connection is handled by a specific DB instance. When you connect to an Aurora cluster, the host name and port that you specify point to an intermediate handler called an *endpoint*. Aurora uses the endpoint mechanism to abstract these connections. Thus, you don't have to hardcode all the hostnames or write your own logic for balancing and rerouting connections when some DB instances aren't available. For certain Aurora tasks, different instances or groups of instances perform different roles. For example, the primary instance handles all data definition language (DDL) and data manipulation language (DML) statements. Up to 15 Aurora Replicas handle read-only query traffic. **Topics** + [ ## Types of Aurora endpoints ](#Aurora.Overview.Endpoints.Types) + [ ## Viewing the endpoints for an Aurora cluster ](#Aurora.Endpoints.Viewing) + [ ## How Aurora endpoints work with high availability ](#Aurora.Overview.Endpoints.HA) + [ # Cluster endpoints for Amazon Aurora ](Aurora.Endpoints.Cluster.md) + [ # Reader endpoints for Amazon Aurora ](Aurora.Endpoints.Reader.md) + [ # Instance endpoints for Amazon Aurora ](Aurora.Endpoints.Instance.md) + [ # Custom endpoints for Amazon Aurora ](Aurora.Endpoints.Custom.md) ## Types of Aurora endpoints Using endpoints, you can map each connection to the appropriate instance or group of instances based on your use case. For example, to perform DDL statements you can connect to whichever instance is the primary instance. To perform queries, you can connect to the reader endpoint, with Aurora automatically performing connection-balancing among all the Aurora Replicas. For clusters with DB instances of different capacities or configurations, you can connect to custom endpoints associated with different subsets of DB instances. For diagnosis or tuning, you can connect to a specific instance endpoint to examine details about a specific DB instance. An endpoint is represented as an Aurora-specific URL that contains a host address and a port. The following types of endpoints are available from an Aurora DB cluster. **Cluster endpoint** Connect to the primary instance of your cluster to develop and test applications, and perform transformations like `INSERT` statements and DDL, DML, and ETL operations. Find the cluster endpoint location by using the AWS Management Console, AWS CLI, or Amazon RDS API, as described in [Viewing the endpoints for an Aurora cluster](#Aurora.Endpoints.Viewing). For more information about cluster endpoints, see [Cluster endpoints for Amazon Aurora](Aurora.Endpoints.Cluster.md). **Reader endpoint** Perform queries. Aurora automatically performs connection-balancing among all the Aurora Replicas. Find the reader endpoint location by using the AWS Management Console, AWS CLI, or Amazon RDS API, as described in [Viewing the endpoints for an Aurora cluster](#Aurora.Endpoints.Viewing). For more information about reader endpoints, see [Reader endpoints for Amazon Aurora](Aurora.Endpoints.Reader.md). **Instance endpoint** Examine details about a specific DB instance for diagnosis or tuning. You can find the instance endpoint location for each of your instances in the AWS Management Console only, on the instance detail page for your instance. For more information about instance endpoints, see [Instance endpoints for Amazon Aurora](Aurora.Endpoints.Instance.md). **Custom endpoint** Connect to different subsets of DB instances on the DB cluster. This is useful when you have different instance capacities and configurations within your DB cluster. Find the custom endpoint locations by using the AWS Management Console, AWS CLI, or Amazon RDS API, as described in [Viewing the endpoints for an Aurora cluster](#Aurora.Endpoints.Viewing). For more information about custom endpoints, see [Custom endpoints for Amazon Aurora](Aurora.Endpoints.Custom.md). **Aurora Global Database writer endpoint** Aurora Global Database has a special kind of endpoint that serves the same purpose as the cluster endpoint of a standalone Aurora cluster. It handles both write and read requests. When a secondary cluster becomes the new primary cluster due to a switchover or failover, Aurora automatically switches this endpoint to point to the cluster endpoint of the new primary cluster, in the other AWS Region. That way, you don't have to encode the AWS Region into the connection string for your application, and you don't have to change the connection string when the layout of the global database changes. Aurora creates this endpoint when you set up an Aurora Global Database, for example by choosing **Add Region** for an Aurora cluster in the AWS Management Console. For information on how you can use this type of endpoint with Aurora Global Database, see [Connecting to Amazon Aurora Global Database](aurora-global-database-connecting.md). ## Viewing the endpoints for an Aurora cluster While you can only find the instance endpoint location on the instance detail page in the AWS Management Console, you can use the console, AWS CLI, or Amazon RDS API to find the locations of cluster, reader, and custom endpoints. ------ #### [ Console ] In the AWS Management Console, find the cluster endpoint, the reader endpoint, and any custom endpoints in the instance details page for your cluster. You see the instance endpoint in the detail page for each instance. When you connect, append the associated port number, following a colon, to the endpoint name shown on the detail page. ------ #### [ AWS CLI ] With the AWS CLI, you find the writer, reader, and any custom endpoints in the output of the [describe-db-clusters](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-clusters.html) command. For example, the following command shows the endpoint attributes for all clusters in your current AWS Region. ``` aws rds describe-db-clusters --query '*[].{Endpoint:Endpoint,ReaderEndpoint:ReaderEndpoint,CustomEndpoints:CustomEndpoints}' ``` ------ #### [ Amazon RDS API ] With the Amazon RDS API, you retrieve the endpoints by calling the [DescribeDBClusterEndpoints](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusterEndpoints.html) operation. ------ ## How Aurora endpoints work with high availability For clusters where high availability is important, use the cluster endpoint for read/write or general-purpose connections and the reader endpoint for read-only connections. The writer and reader endpoints manage DB instance failover better than instance endpoints do. Unlike the instance endpoints, the writer and reader endpoints automatically change which DB instance they connect to if a DB instance in your cluster becomes unavailable. For more information about cluster and reader endpoints, see [Cluster endpoints for Amazon Aurora](Aurora.Endpoints.Cluster.md) and [Reader endpoints for Amazon Aurora](Aurora.Endpoints.Reader.md). If the primary DB instance of a DB cluster fails, Aurora automatically fails over to a new primary DB instance. It does so by either promoting an existing Aurora Replica to a new primary DB instance or creating a new primary DB instance. If a failover occurs, you can use the cluster endpoint to reconnect to the newly promoted or created primary DB instance, or use the reader endpoint to reconnect to one of the Aurora Replicas in the DB cluster. During a failover, the reader endpoint might direct connections to the new primary DB instance of a DB cluster for a short time after an Aurora Replica is promoted to the new primary DB instance. If you design your own application logic to manage connections to instance endpoints, you can manually or programmatically discover the resulting set of available DB instances in the DB cluster. Use the [https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-clusters.html](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-clusters.html) AWS CLI command or [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusters.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusters.html) RDS API operation to find the DB cluster and reader endpoints, DB instances, whether DB instances are readers, and their promotion tiers. You can then confirm their instance classes after failover and connect to an appropriate instance endpoint. For more information about failovers, see [Fault tolerance for an Aurora DB cluster](Concepts.AuroraHighAvailability.md#Aurora.Managing.FaultTolerance). For more information about high availability in Amazon Aurora, see [High availability for Amazon Aurora](Concepts.AuroraHighAvailability.md). # Cluster endpoints for Amazon Aurora A *cluster endpoint* (or *writer endpoint*) for an Aurora DB cluster connects to the current primary DB instance for that DB cluster. This endpoint is the only one that can perform write operations such as DDL statements. Because of this, the cluster endpoint is the one that you connect to when you first set up a cluster or when your cluster only contains a single DB instance. Each Aurora DB cluster has one cluster endpoint and one primary DB instance. You use the cluster endpoint for all write operations on the DB cluster, including inserts, updates, deletes, and DDL changes. You can also use the cluster endpoint for read operations, such as queries. The cluster endpoint provides failover support for read/write connections to the DB cluster. If the current primary DB instance of a DB cluster fails, Aurora automatically fails over to a new primary DB instance. During a failover, the DB cluster continues to serve connection requests to the cluster endpoint from the new primary DB instance, with minimal interruption of service. The following example illustrates a cluster endpoint for an Aurora MySQL DB cluster. ``` mydbcluster.cluster-c7tj4example.us-east-1.rds.amazonaws.com:3306 ``` Each Aurora cluster has a single built-in cluster endpoint, whose name and other attributes are managed by Aurora. You can't create, delete, or modify this kind of endpoint. You use the cluster endpoint when you administer your cluster, perform extract, transform, load (ETL) operations, or develop and test applications. The cluster endpoint connects to the primary instance of the cluster. The primary instance is the only DB instance where you can create tables and indexes, run `INSERT` statements, and perform other DDL and DML operations. The physical IP address pointed to by the cluster endpoint changes when the failover mechanism promotes a new DB instance to be the read/write primary instance for the cluster. If you use any form of connection pooling or other multiplexing, be prepared to flush or reduce the time-to-live for any cached DNS information. Doing so ensures that you don't try to establish a read/write connection to a DB instance that became unavailable or is now read-only after a failover. # Reader endpoints for Amazon Aurora A *reader endpoint* for an Aurora DB cluster provides connection-balancing support for read-only connections to the DB cluster. Use the reader endpoint for read operations, such as queries. By processing those statements on the read-only Aurora Replicas, this endpoint reduces the overhead on the primary instance. It also helps the cluster to scale the capacity to handle simultaneous `SELECT` queries, proportional to the number of Aurora Replicas in the cluster. Each Aurora DB cluster has one reader endpoint. If the cluster contains one or more Aurora Replicas, the reader endpoint balances each connection request among the Aurora Replicas. In that case, you can only perform read-only statements such as `SELECT` in that session. If the cluster only contains a primary instance and no Aurora Replicas, the reader endpoint connects to the primary instance. In that case, you can perform write operations through the endpoint. The following example illustrates a reader endpoint for an Aurora MySQL DB cluster. ``` mydbcluster.cluster-ro-c7tj4example.us-east-1.rds.amazonaws.com:3306 ``` You use the reader endpoint for read-only connections for your Aurora cluster. This endpoint uses a connection-balancing mechanism to help your cluster handle a query-intensive workload. The reader endpoint is the endpoint that you supply to applications that do reporting or other read-only operations on the cluster. The reader endpoint balances connections to available Aurora Replicas in an Aurora DB cluster. It doesn't balance individual queries. If you want to balance each query to distribute the read workload for a DB cluster, open a new connection to the reader endpoint for each query. Each Aurora cluster has a single built-in reader endpoint, whose name and other attributes are managed by Aurora. You can't create, delete, or modify this kind of endpoint. If your cluster contains only a primary target (instance or DB shard group) and no Aurora Replicas, the reader endpoint connects to the primary instance. In that case, you can perform write operations through this endpoint. **Tip** Through RDS Proxy, you can create additional read-only endpoints for an Aurora cluster. These endpoints perform the same kind of connection-balancing as the Aurora reader endpoint. Applications can reconnect more quickly to the proxy endpoints than the Aurora reader endpoint if reader instances become unavailable. The proxy endpoints can also take advantage of other proxy features such as multiplexing. For more information, see [Using reader endpoints with Aurora clusters](rds-proxy-endpoints.md#rds-proxy-endpoints-reader). # Instance endpoints for Amazon Aurora An *instance endpoint* connects to a specific DB instance within an Aurora cluster. Each DB instance in a DB cluster has its own unique instance endpoint. So there is one instance endpoint for the current primary DB instance of the DB cluster, and there is one instance endpoint for each of the Aurora Replicas in the DB cluster. The instance endpoint provides direct control over connections to the DB cluster, for scenarios where using the cluster endpoint or reader endpoint might not be appropriate. For example, your client application might require more fine-grained connection balancing based on workload type. In this case, you can configure multiple clients to connect to different Aurora Replicas in a DB cluster to distribute read workloads. For an example that uses instance endpoints to improve connection speed after a failover for Aurora PostgreSQL, see [Fast failover with Amazon Aurora PostgreSQL](AuroraPostgreSQL.BestPractices.FastFailover.md). For an example that uses instance endpoints to improve connection speed after a failover for Aurora MySQL, see [MariaDB Connector/J failover support - case Amazon Aurora](https://mariadb.org/mariadb-connectorj-failover-support-case-amazon-aurora/). The following example illustrates an instance endpoint for a DB instance in an Aurora MySQL DB cluster. ``` mydbinstance.c7tj4example.us-east-1.rds.amazonaws.com:3306 ``` Each DB instance in an Aurora cluster has its own built-in instance endpoint, whose name and other attributes are managed by Aurora. You can't create, delete, or modify this kind of endpoint. You might be familiar with instance endpoints if you use Amazon RDS. However, with Aurora you typically use the writer and reader endpoints more often than the instance endpoints. In day-to-day Aurora operations, the main way that you use instance endpoints is to diagnose capacity or performance issues that affect one specific instance in an Aurora cluster. While connected to a specific instance, you can examine its status variables, metrics, and so on. Doing this can help you determine what's happening for that instance that's different from what's happening for other instances in the cluster. In advanced use cases, you might configure some DB instances differently than others. In this case, use the instance endpoint to connect directly to an instance that is smaller, larger, or otherwise has different characteristics than the others. Also, set up failover priority so that this special DB instance is the last choice to take over as the primary instance. We recommend that you use custom endpoints instead of the instance endpoint in such cases. Doing so simplifies connection management and high availability as you add more DB instances to your cluster. # Custom endpoints for Amazon Aurora A *custom endpoint* for an Aurora cluster represents a set of DB instances that you choose. When you connect to the endpoint, Aurora performs connection balancing and chooses one of the instances in the group to handle the connection. You define which instances this endpoint refers to, and you decide what purpose the endpoint serves. An Aurora DB cluster has no custom endpoints until you create one. You can create up to five custom endpoints for each provisioned Aurora cluster or Aurora Serverless v2 cluster. The custom endpoint provides balanced database connections based on criteria other than the read-only or read/write capability of the DB instances. For example, you might define a custom endpoint to connect to instances that use a particular AWS instance class or a particular DB parameter group. Then you might tell particular groups of users about this custom endpoint. For example, you might direct internal users to low-capacity instances for report generation or ad hoc (one-time) querying, and direct production traffic to high-capacity instances. Because the connection can go to any DB instance that is associated with the custom endpoint, we recommend that you make sure that all the DB instances within that group share some similar characteristic. Doing so ensures that the performance, memory capacity, and so on, are consistent for everyone who connects to that endpoint. This feature is intended for advanced users with specialized kinds of workloads where it isn't practical to keep all the Aurora Replicas in the cluster identical. With custom endpoints, you can predict the capacity of the DB instance used for each connection. When you use custom endpoints, you typically don't use the reader endpoint for that cluster. The following example illustrates a custom endpoint for a DB instance in an Aurora MySQL DB cluster. ``` myendpoint.cluster-custom-c7tj4example.us-east-1.rds.amazonaws.com:3306 ``` You use custom endpoints to simplify connection management when your cluster contains DB instances with different capacities and configuration settings. Previously, you might have used the CNAMES mechanism to set up Domain Name Service (DNS) aliases from your own domain to achieve similar results. By using custom endpoints, you can avoid updating CNAME records when your cluster grows or shrinks. Custom endpoints also mean that you can use encrypted Transport Layer Security/Secure Sockets Layer (TLS/SSL) connections. Instead of using one DB instance for each specialized purpose and connecting to its instance endpoint, you can have multiple groups of specialized DB instances. In this case, each group has its own custom endpoint. This way, Aurora can perform connection balancing among all the instances dedicated to tasks such as reporting or handling production or internal queries. The custom endpoints distribute connections across instances passively, using DNS to return the IP address of one of the instances randomly. If one of the DB instances within a group becomes unavailable, Aurora directs subsequent custom endpoint connections to one of the other DB instances associated with the same endpoint. **Topics** + [ # Considerations for custom endpoints in Amazon Aurora ](Aurora.Endpoints.Custom.Considerations.md) + [ # Creating a custom endpoint ](aurora-custom-endpoint-creating.md) + [ # Viewing custom endpoints ](aurora-endpoint-viewing.md) + [ # Editing a custom endpoint ](aurora-endpoint-editing.md) + [ # Deleting a custom endpoint ](aurora-endpoints-custom-deleting.md) + [ # AWS CLI examples for custom endpoints for Amazon Aurora ](Aurora.Endpoint.Tutorial.md) # Considerations for custom endpoints in Amazon Aurora Use the following sections to manage, specify properties, and use membership rules for custom endpoints. **Topics** + [ ## Managing custom endpoints ](#Aurora.Endpoints.Custom.Managing) + [ ## Specifying properties for custom endpoints ](#Aurora.Endpoints.Custom.Properties) + [ ## Membership rules for custom endpoints ](#Aurora.Endpoints.Custom.Membership) ## Managing custom endpoints Because newly created Aurora clusters have no custom endpoints, you must create and manage these objects yourself. You do so using the AWS Management Console, AWS CLI, or Amazon RDS API. **Note** You must also create and manage custom endpoints for Aurora clusters restored from snapshots. Custom endpoints are not included in the snapshot. You create them again after restoring, and choose new endpoint names if the restored cluster is in the same region as the original one. To work with custom endpoints from the AWS Management Console, you navigate to the details page for your Aurora cluster and use the controls under the **Custom Endpoints** section. To work with custom endpoints from the AWS CLI, you can use these operations: + [create-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster-endpoint.html) + [describe-db-cluster-endpoints](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-cluster-endpoints.html) + [modify-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster-endpoint.html) + [delete-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-db-cluster-endpoint.html) To work with custom endpoints through the Amazon RDS API, you can use the following functions: + [CreateDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBClusterEndpoint.html) + [DescribeDBClusterEndpoints](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusterEndpoints.html) + [ModifyDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBClusterEndpoint.html) + [DeleteDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteDBClusterEndpoint.html) ## Specifying properties for custom endpoints The maximum length for a custom endpoint name is 63 characters. The name format is the following: ``` endpoint_name.cluster-custom-customer_DNS_identifier.AWS_Region.rds.amazonaws.com ``` You can't reuse the same custom endpoint name for more than one cluster in the same AWS Region. The custom DNS identifier is a unique identifier associated with your AWS account in a particular AWS Region. Each custom endpoint has an associated type that determines which DB instances are eligible to be associated with that endpoint. Currently, the type can be `READER` or `ANY`. The following considerations apply to the custom endpoint types: + You can't select the custom endpoint type in the AWS Management Console. All the custom endpoints you create through the AWS Management Console have a type of `ANY`. You can set and modify the custom endpoint type using the AWS CLI or Amazon RDS API. + Only reader DB instances can be part of a `READER` custom endpoint. + Both reader and writer DB instances can be part of an `ANY` custom endpoint. Aurora directs connections to cluster endpoints with type `ANY` to any associated DB instance with equal probability. The `ANY` type applies to clusters using any replication topology. + If you try to create a custom endpoint with a type that isn't appropriate based on the replication configuration for a cluster, Aurora returns an error. ## Membership rules for custom endpoints When you add a DB instance to a custom endpoint or remove it from a custom endpoint, any existing connections to that DB instance remain active. You can define a list of DB instances to include in, or exclude from, a custom endpoint. We refer to these lists as *static* and *exclusion* lists, respectively. You can use the inclusion/exclusion mechanism to further subdivide the groups of DB instances, and to make sure that the set of custom endpoints covers all the DB instances in the cluster. Each custom endpoint can contain only one of these list types. In the AWS Management Console: + The choice is represented by the check box **Attach future instances added to this cluster**. When you keep the check box clear, the custom endpoint uses a static list containing only the DB instances specified on the page. When you choose the check box, the custom endpoint uses an exclusion list. In this case, the custom endpoint represents all DB instances in the cluster (including any that you add in the future) except the ones not selected on the page. + The console doesn't allow you to specify the endpoint type. Any custom endpoint created using the console is of type `ANY`. Therefore, Aurora doesn't change the membership of the custom endpoint when DB instances change roles between writer and reader due to failover or promotion. In the AWS CLI and Amazon RDS API: + You can specify the endpoint type. Therefore, when the endpoint type is set to `READER`, endpoint membership is automatically adjusted during failovers and promotions. For example, a custom endpoint with type `READER` includes an Aurora Replica that is then promoted to be a writer DB instance. The new writer instance is no longer part of the custom endpoint. + You can add individual members to and remove them from the lists after they change their roles. Use the [modify-db-cluster-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/rds/modify-db-cluster-endpoint.html) AWS CLI command or [ModifyDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBClusterEndpoint.html) API operation. You can associate a DB instance with more than one custom endpoint. For example, suppose that you add a new DB instance to a cluster, or that Aurora adds a DB instance automatically through the autoscaling mechanism. In these cases, the DB instance is added to all custom endpoints for which it is eligible. Which endpoints the DB instance is added to is based on the custom endpoint type of `READER` or `ANY`, plus any static or exclusion lists defined for each endpoint. For example, if the endpoint includes a static list of DB instances, newly added Aurora Replicas aren't added to that endpoint. Conversely, if the endpoint has an exclusion list, newly added Aurora Replicas are added to the endpoint, if they aren't named in the exclusion list and their roles match the type of the custom endpoint. If an Aurora Replica becomes unavailable, it remains associated with any custom endpoints. For example, it remains part of the custom endpoint when it is unhealthy, stopped, rebooting, and so on. However, you can't connect to it through those endpoints until it becomes available again. # Creating a custom endpoint Create a custom endpoint using the AWS Management Console, AWS CLI, or the Amazon RDS API. ## Console To create a custom endpoint with the AWS Management Console, go to the cluster detail page and choose the `Create custom endpoint` action in the **Endpoints** section. Choose a name for the custom endpoint, unique for your user ID and region. To choose a list of DB instances that remains the same even as the cluster expands, keep the check box **Attach future instances added to this cluster** clear. When you choose that check box, the custom endpoint dynamically adds any new instances as you add them to the cluster. ![\[Create custom endpoint page with fields for endpoint identifier, instance type selection, and static/exclusion options.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraCreateCustomEndpoint.png) You can't select the custom endpoint type in the AWS Management Console. All custom endpoints you create through the AWS Management Console have a type of `ANY`. ## AWS CLI To create a custom endpoint with the AWS CLI, run the [create-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster-endpoint.html) command. The following command creates a custom endpoint attached to a specific cluster. Initially, the endpoint is associated with all the Aurora Replica instances in the cluster. A subsequent command associates it with a specific set of DB instances in the cluster. For Linux, macOS, or Unix: ``` aws rds create-db-cluster-endpoint --db-cluster-endpoint-identifier custom-endpoint-doc-sample \ --endpoint-type reader \ --db-cluster-identifier cluster_id aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier custom-endpoint-doc-sample \ --static-members instance_name_1 instance_name_2 ``` For Windows: ``` aws rds create-db-cluster-endpoint --db-cluster-endpoint-identifier custom-endpoint-doc-sample ^ --endpoint-type reader ^ --db-cluster-identifier cluster_id aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier custom-endpoint-doc-sample ^ --static-members instance_name_1 instance_name_2 ``` ## RDS API To create a custom endpoint with the RDS API, run the [CreateDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBClusterEndpoint.html) operation. # Viewing custom endpoints ## Console To view custom endpoints with the AWS Management Console, go to the cluster detail page for the cluster and look under the **Endpoints** section. This section contains information only about custom endpoints. The details for the built-in endpoints are listed in the main **Details** section. To see the details for a specific custom endpoint, select its name to bring up the detail page for that endpoint. The following screenshot shows how the list of custom endpoints for an Aurora cluster is initially empty. ![\[Endpoints page with no custom endpoints.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraCustomEndpointEmptyList.png) After you create some custom endpoints for that cluster, they are shown under the **Endpoints** section. ![\[Endpoints page with two custom endpoints.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraCustomEndpointList.png) Clicking through to the detail page shows which DB instances the endpoint is currently associated with. ![\[DB instances associated with a custom endpoint.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraCustomEndpointDetail.png) To see the additional detail of whether new DB instances added to the cluster are automatically added to the endpoint also, open the **Edit** page for the endpoint. ## AWS CLI To view custom endpoints with the AWS CLI, run the [describe-db-cluster-endpoints](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-cluster-endpoints.html) command. The following command shows the custom endpoints associated with a specified cluster in a specified region. The output includes both the built-in endpoints and any custom endpoints. For Linux, macOS, or Unix: ``` aws rds describe-db-cluster-endpoints --region region_name \ --db-cluster-identifier cluster_id ``` For Windows: ``` aws rds describe-db-cluster-endpoints --region region_name ^ --db-cluster-identifier cluster_id ``` The following shows some sample output from a `describe-db-cluster-endpoints` command. The `EndpointType` of `WRITER` or `READER` denotes the built-in read/write and read-only endpoints for the cluster. The `EndpointType` of `CUSTOM` denotes endpoints that you create and choose the associated DB instances. One of the endpoints has a non-empty `StaticMembers` field, denoting that it is associated with a precise set of DB instances. The other endpoint has a non-empty `ExcludedMembers` field, denoting that the endpoint is associated with all DB instances *other than* the ones listed under `ExcludedMembers`. This second kind of custom endpoint grows to accommodate new instances as you add them to the cluster. ``` { "DBClusterEndpoints": [ { "Endpoint": "custom-endpoint-demo.cluster-c7tj4example.ca-central-1.rds.amazonaws.com", "Status": "available", "DBClusterIdentifier": "custom-endpoint-demo", "EndpointType": "WRITER" }, { "Endpoint": "custom-endpoint-demo.cluster-ro-c7tj4example.ca-central-1.rds.amazonaws.com", "Status": "available", "DBClusterIdentifier": "custom-endpoint-demo", "EndpointType": "READER" }, { "CustomEndpointType": "ANY", "DBClusterEndpointIdentifier": "powers-of-2", "ExcludedMembers": [], "DBClusterIdentifier": "custom-endpoint-demo", "Status": "available", "EndpointType": "CUSTOM", "Endpoint": "powers-of-2.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "StaticMembers": [ "custom-endpoint-demo-04", "custom-endpoint-demo-08", "custom-endpoint-demo-01", "custom-endpoint-demo-02" ], "DBClusterEndpointResourceIdentifier": "cluster-endpoint-W7PE3TLLFNSHXQKFU6J6NV5FHU", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:powers-of-2" }, { "CustomEndpointType": "ANY", "DBClusterEndpointIdentifier": "eight-and-higher", "ExcludedMembers": [ "custom-endpoint-demo-04", "custom-endpoint-demo-02", "custom-endpoint-demo-07", "custom-endpoint-demo-05", "custom-endpoint-demo-03", "custom-endpoint-demo-06", "custom-endpoint-demo-01" ], "DBClusterIdentifier": "custom-endpoint-demo", "Status": "available", "EndpointType": "CUSTOM", "Endpoint": "eight-and-higher.cluster-custom-123456789012.ca-central-1.rds.amazonaws.com", "StaticMembers": [], "DBClusterEndpointResourceIdentifier": "cluster-endpoint-W7PE3TLLFNSHYQKFU6J6NV5FHU", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:eight-and-higher" } ] } ``` ## RDS API To view custom endpoints with the RDS API, run the [DescribeDBClusterEndpoints.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusterEndpoints.html.html) operation. # Editing a custom endpoint You can edit the properties of a custom endpoint to change which DB instances are associated with the endpoint. You can also change an endpoint between a static list and an exclusion list. If you need more details about these endpoint properties, see [Membership rules for custom endpoints](Aurora.Endpoints.Custom.Considerations.md#Aurora.Endpoints.Custom.Membership). You can continue connecting to and using a custom endpoint while the changes from an edit action are in progress. ## Console To edit a custom endpoint with the AWS Management Console, you can select the endpoint on the cluster detail page, or bring up the detail page for the endpoint, and choose the **Edit** action. ![\[Editing a custom endpoint.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraEditCustomEndpoint.png) ## AWS CLI To edit a custom endpoint with the AWS CLI, run the [modify-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster-endpoint.html) command. The following commands change the set of DB instances that apply to a custom endpoint and optionally switches between the behavior of a static or exclusion list. The `--static-members` and `--excluded-members` parameters take a space-separated list of DB instance identifiers. For Linux, macOS, or Unix: ``` aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier my-custom-endpoint \ --static-members db-instance-id-1 db-instance-id-2 db-instance-id-3 \ --region region_name aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier my-custom-endpoint \ --excluded-members db-instance-id-4 db-instance-id-5 \ --region region_name ``` For Windows: ``` aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier my-custom-endpoint ^ --static-members db-instance-id-1 db-instance-id-2 db-instance-id-3 ^ --region region_name aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier my-custom-endpoint ^ --excluded-members db-instance-id-4 db-instance-id-5 ^ --region region_name ``` ## RDS API To edit a custom endpoint with the RDS API, run the [ModifyDBClusterEndpoint.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBClusterEndpoint.html.html) operation. # Deleting a custom endpoint Delete a custom endpoint using the AWS Management Console, AWS CLI, or the Amazon RDS API. ## Console To delete a custom endpoint with the AWS Management Console, go to the cluster detail page, select the appropriate custom endpoint, and select the **Delete** action. ![\[Delete custom endpoint page.\]](http://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/images/AuroraDeleteCustomEndpoint.png) ## AWS CLI To delete a custom endpoint with the AWS CLI, run the [delete-db-cluster-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-db-cluster-endpoint.html) command. The following command deletes a custom endpoint. You don't need to specify the associated cluster, but you must specify the region. For Linux, macOS, or Unix: ``` aws rds delete-db-cluster-endpoint --db-cluster-endpoint-identifier custom-end-point-id \ --region region_name ``` For Windows: ``` aws rds delete-db-cluster-endpoint --db-cluster-endpoint-identifier custom-end-point-id ^ --region region_name ``` ## RDS API To delete a custom endpoint with the RDS API, run the [DeleteDBClusterEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteDBClusterEndpoint.html) operation. # AWS CLI examples for custom endpoints for Amazon Aurora The following tutorial uses AWS CLI examples with Unix shell syntax to show how you might define a cluster with several "small" DB instances and a few "big" DB instances, and create custom endpoints to connect to each set of DB instances. To run similar commands on your own system, you should be familiar enough with the basics of working with Aurora clusters and AWS CLI usage to supply your own values for parameters such as region, subnet group, and VPC security group. This example demonstrates the initial setup steps: creating an Aurora cluster and adding DB instances to it. This is a heterogeneous cluster, meaning not all the DB instances have the same capacity. Most instances use the AWS instance class `db.r4.4xlarge`, but the last two DB instances use `db.r4.16xlarge`. Each of these sample `create-db-instance` commands prints its output to the screen and saves a copy of the JSON in a file for later inspection. ``` aws rds create-db-cluster --db-cluster-identifier custom-endpoint-demo --engine aurora-mysql \ --engine-version 8.0.mysql_aurora.3.04.0 --master-username $MASTER_USER --manage-master-user-password \ --db-subnet-group-name $SUBNET_GROUP --vpc-security-group-ids $VPC_SECURITY_GROUP \ --region $REGION for i in 01 02 03 04 05 06 07 08 do aws rds create-db-instance --db-instance-identifier custom-endpoint-demo-${i} \ --engine aurora --db-cluster-identifier custom-endpoint-demo --db-instance-class db.r4.4xlarge \ --region $REGION \ | tee custom-endpoint-demo-${i}.json done for i in 09 10 do aws rds create-db-instance --db-instance-identifier custom-endpoint-demo-${i} \ --engine aurora --db-cluster-identifier custom-endpoint-demo --db-instance-class db.r4.16xlarge \ --region $REGION \ | tee custom-endpoint-demo-${i}.json done ``` The larger instances are reserved for specialized kinds of reporting queries. To make it unlikely for them to be promoted to the primary instance, the following example changes their promotion tier to the lowest priority. This example specifies the `--manage-master-user-password` option to generate the master user password and manage it in Secrets Manager. For more information, see [Password management with Amazon Aurora and AWS Secrets Manager](rds-secrets-manager.md). Alternatively, you can use the `--master-password` option to specify and manage the password yourself. ``` for i in 09 10 do aws rds modify-db-instance --db-instance-identifier custom-endpoint-demo-${i} \ --region $REGION --promotion-tier 15 done ``` Suppose that you want to use the two "bigger" instances only for the most resource-intensive queries. To do this, you can first create a custom read-only endpoint. Then you can add a static list of members so that the endpoint connects only to those DB instances. Those instances are already in the lowest promotion tier, making it unlikely either of them will be promoted to the primary instance. If one of them is promoted to the primary instance, it becomes unreachable through this endpoint because we specified the `READER` type instead of the `ANY` type. The following example demonstrates the create and modify endpoint commands, and sample JSON output showing the initial and modified state of the custom endpoint. ``` $ aws rds create-db-cluster-endpoint --region $REGION \ --db-cluster-identifier custom-endpoint-demo \ --db-cluster-endpoint-identifier big-instances --endpoint-type reader { "EndpointType": "CUSTOM", "Endpoint": "big-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "DBClusterEndpointIdentifier": "big-instances", "DBClusterIdentifier": "custom-endpoint-demo", "StaticMembers": [], "DBClusterEndpointResourceIdentifier": "cluster-endpoint-W7PE3TLLFNSHXQKFU6J6NV5FHU", "ExcludedMembers": [], "CustomEndpointType": "READER", "Status": "creating", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:big-instances" } $ aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier big-instances \ --static-members custom-endpoint-demo-09 custom-endpoint-demo-10 --region $REGION { "EndpointType": "CUSTOM", "ExcludedMembers": [], "DBClusterEndpointIdentifier": "big-instances", "DBClusterEndpointResourceIdentifier": "cluster-endpoint-W7PE3TLLFNSHXQKFU6J6NV5FHU", "CustomEndpointType": "READER", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:big-instances", "StaticMembers": [ "custom-endpoint-demo-10", "custom-endpoint-demo-09" ], "Status": "modifying", "Endpoint": "big-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "DBClusterIdentifier": "custom-endpoint-demo" } ``` The default `READER` endpoint for the cluster can connect to either the "small" or "big" DB instances, making it impractical to predict query performance and scalability when the cluster becomes busy. To divide the workload cleanly between the sets of DB instances, you can ignore the default `READER` endpoint and create a second custom endpoint that connects to all other DB instances. The following example does so by creating a custom endpoint and then adding an exclusion list. Any other DB instances you add to the cluster later will be added to this endpoint automatically. The `ANY` type means that this endpoint is associated with eight instances in total: the primary instance and another seven Aurora Replicas. If the example used the `READER` type, the custom endpoint would only be associated with the seven Aurora Replicas. ``` $ aws rds create-db-cluster-endpoint --region $REGION --db-cluster-identifier custom-endpoint-demo \ --db-cluster-endpoint-identifier small-instances --endpoint-type any { "Status": "creating", "DBClusterEndpointIdentifier": "small-instances", "CustomEndpointType": "ANY", "EndpointType": "CUSTOM", "Endpoint": "small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "StaticMembers": [], "ExcludedMembers": [], "DBClusterIdentifier": "custom-endpoint-demo", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:small-instances", "DBClusterEndpointResourceIdentifier": "cluster-endpoint-6RDDXQOC3AKKZT2PRD7ST37BMY" } $ aws rds modify-db-cluster-endpoint --db-cluster-endpoint-identifier small-instances \ --excluded-members custom-endpoint-demo-09 custom-endpoint-demo-10 --region $REGION { "DBClusterEndpointIdentifier": "small-instances", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:c7tj4example:cluster-endpoint:small-instances", "DBClusterEndpointResourceIdentifier": "cluster-endpoint-6RDDXQOC3AKKZT2PRD7ST37BMY", "CustomEndpointType": "ANY", "Endpoint": "small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "EndpointType": "CUSTOM", "ExcludedMembers": [ "custom-endpoint-demo-09", "custom-endpoint-demo-10" ], "StaticMembers": [], "DBClusterIdentifier": "custom-endpoint-demo", "Status": "modifying" } ``` The following example checks the state of the endpoints for this cluster. The cluster still has its original cluster endpoint, with `EndPointType` of `WRITER`, which you would still use for administration, ETL, and other write operations. It still has its original `READER` endpoint, which you wouldn't use because each connection to it might be directed to a "small" or "big" DB instance. The custom endpoints make this behavior predictable, with connections guaranteed to use one of the "small" or "big" DB instances based on the endpoint you specify. ``` $ aws rds describe-db-cluster-endpoints --region $REGION { "DBClusterEndpoints": [ { "EndpointType": "WRITER", "Endpoint": "custom-endpoint-demo.cluster-c7tj4example.ca-central-1.rds.amazonaws.com", "Status": "available", "DBClusterIdentifier": "custom-endpoint-demo" }, { "EndpointType": "READER", "Endpoint": "custom-endpoint-demo.cluster-ro-c7tj4example.ca-central-1.rds.amazonaws.com", "Status": "available", "DBClusterIdentifier": "custom-endpoint-demo" }, { "Endpoint": "small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "CustomEndpointType": "ANY", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:small-instances", "ExcludedMembers": [ "custom-endpoint-demo-09", "custom-endpoint-demo-10" ], "DBClusterEndpointResourceIdentifier": "cluster-endpoint-6RDDXQOC3AKKZT2PRD7ST37BMY", "DBClusterIdentifier": "custom-endpoint-demo", "StaticMembers": [], "EndpointType": "CUSTOM", "DBClusterEndpointIdentifier": "small-instances", "Status": "modifying" }, { "Endpoint": "big-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com", "CustomEndpointType": "READER", "DBClusterEndpointArn": "arn:aws:rds:ca-central-1:111122223333:cluster-endpoint:big-instances", "ExcludedMembers": [], "DBClusterEndpointResourceIdentifier": "cluster-endpoint-W7PE3TLLFNSHXQKFU6J6NV5FHU", "DBClusterIdentifier": "custom-endpoint-demo", "StaticMembers": [ "custom-endpoint-demo-10", "custom-endpoint-demo-09" ], "EndpointType": "CUSTOM", "DBClusterEndpointIdentifier": "big-instances", "Status": "available" } ] } ``` The final examples demonstrate how successive database connections to the custom endpoints connect to the various DB instances in the Aurora cluster. The `small-instances` endpoint always connects to the `db.r4.4xlarge` DB instances, which are the lower-numbered hosts in this cluster. ``` $ mysql -h small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com -u $MYUSER -p mysql> select @@aurora_server_id; +-------------------------+ | @@aurora_server_id | +-------------------------+ | custom-endpoint-demo-02 | +-------------------------+ $ mysql -h small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com -u $MYUSER -p mysql> select @@aurora_server_id; +-------------------------+ | @@aurora_server_id | +-------------------------+ | custom-endpoint-demo-07 | +-------------------------+ $ mysql -h small-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com -u $MYUSER -p mysql> select @@aurora_server_id; +-------------------------+ | @@aurora_server_id | +-------------------------+ | custom-endpoint-demo-01 | +-------------------------+ ``` The `big-instances` endpoint always connects to the `db.r4.16xlarge` DB instances, which are the two highest-numbered hosts in this cluster. ``` $ mysql -h big-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com -u $MYUSER -p mysql> select @@aurora_server_id; +-------------------------+ | @@aurora_server_id | +-------------------------+ | custom-endpoint-demo-10 | +-------------------------+ $ mysql -h big-instances.cluster-custom-c7tj4example.ca-central-1.rds.amazonaws.com -u $MYUSER -p mysql> select @@aurora_server_id; +-------------------------+ | @@aurora_server_id | +-------------------------+ | custom-endpoint-demo-09 | +-------------------------+ ```