Working with Amazon RDS Proxy endpoints - Amazon Aurora
Overview of proxy endpointsUsing reader endpoints with Aurora clustersAccessing Aurora databases across VPCsCreating a proxy endpointViewing proxy endpointsModifying a proxy endpointDeleting a proxy endpointLimitations for proxy endpoints
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with Amazon RDS Proxy endpoints

Learn about endpoints for RDS Proxy and how to use them. By using proxy endpoints, you can take advantage of the following capabilities:

  • You can use multiple endpoints with a proxy to monitor and troubleshoot connections from different applications independently.

  • You can use reader endpoints with Aurora DB clusters to improve read scalability and high availability for your query-intensive applications.

  • You can use a cross-VPC endpoint to allow access to databases in one VPC from resources such as Amazon EC2 instances in a different VPC.

Overview of proxy endpoints

Working with RDS Proxy endpoints involves the same kinds of procedures as with Aurora DB cluster and reader endpoints. If you aren't familiar with Aurora endpoints, find more information in Amazon Aurora connection management.

By default, the endpoint that you connect to when you use RDS Proxy with an Aurora cluster has read/write capability. As a result, this endpoint sends all requests to the writer instance of the cluster. All of those connections count against the max_connections value for the writer instance. If your proxy is associated with an Aurora DB cluster, you can create additional read/write or read-only endpoints for that proxy.

You can use a read-only endpoint with your proxy for read-only queries. You do this the same way that you use the reader endpoint for an Aurora provisioned cluster. Doing so helps you to take advantage of the read scalability of an Aurora cluster with one or more reader DB instances. You can run more simultaneous queries and make more simultaneous connections by using a read-only endpoint and adding more reader DB instances to your Aurora cluster as needed.

Tip

When you create a proxy for an Aurora cluster using the Amazon Web Services Management Console, you can have RDS Proxy automatically create a reader endpoint. For information about the benefits of a reader endpoint, see Using reader endpoints with Aurora clusters.

For a proxy endpoint that you create, you can also associate the endpoint with a different virtual private cloud (VPC) than the proxy itself uses. By doing so, you can connect to the proxy from a different VPC, for example a VPC used by a different application within your organization.

For information about limits associated with proxy endpoints, see Limitations for proxy endpoints.

In the RDS Proxy logs, each entry is prefixed with the name of the associated proxy endpoint. This name can be the name you specified for a user-defined endpoint. Or, it can be the special name default for the default endpoint of a proxy that performs read/write requests.

Each proxy endpoint has its own set of CloudWatch metrics. You can monitor the metrics for all endpoints of a proxy. You can also monitor metrics for a specific endpoint, or for all the read/write or read-only endpoints of a proxy. For more information, see Monitoring RDS Proxy metrics with Amazon CloudWatch.

A proxy endpoint uses the same authentication mechanism as its associated proxy. RDS Proxy automatically sets up permissions and authorizations for the user-defined endpoint, consistent with the properties of the associated proxy.

To learn how proxy endpoints work for DB clusters in an Aurora global database, see How RDS Proxy endpoints work with global databases.

Using reader endpoints with Aurora clusters

You can create and connect to read-only endpoints called reader endpoints when you use RDS Proxy with Aurora clusters. These reader endpoints help to improve the read scalability of your query-intensive applications. Reader endpoints also help to improve the availability of your connections if a reader DB instance in your cluster becomes unavailable.

Note

When you specify that a new endpoint is read-only, RDS Proxy requires that the Aurora cluster has one or more reader DB instances. In some cases, you might change the target of the proxy to an Aurora cluster containing only a single writer or a multi-writer Aurora cluster. If you do, any requests to the reader endpoint fail with an error. Requests also fail if the target of the proxy is an RDS instance instead of an Aurora cluster.

If an Aurora cluster has reader instances but those instances aren't available, RDS Proxy waits to send the request instead of returning an error immediately. If no reader instance becomes available within the connection borrow timeout period, the request fails with an error.

How reader endpoints help application availability

In some cases, one or more reader instances in your cluster might become unavailable. If so, connections that use a reader endpoint of a DB proxy can recover more quickly than ones that use the Aurora reader endpoint. RDS Proxy routes connections to only the available reader instances in the cluster. There isn't a delay due to DNS caching when an instance becomes unavailable.

If the connection is multiplexed, RDS Proxy directs subsequent queries to a different reader DB instance without any interruption to your application. During the automatic switchover to a new reader instance, RDS Proxy checks the replication lag of the old and new reader instances. RDS Proxy makes sure that the new reader instance is up to date with the same changes as the previous reader instance. That way, your application never sees stale data when RDS Proxy switches from one reader DB instance to another.

If the connection is pinned, the next query on the connection returns an error. However, your application can immediately reconnect to the same endpoint. RDS Proxy routes the connection to a different reader DB instance that's in available state. When you manually reconnect, RDS Proxy doesn't check the replication lag between the old and new reader instances.

If your Aurora cluster doesn't have any available reader instances, RDS Proxy checks whether this condition is temporary or permanent. The behavior in each case is as follows:

  • Suppose that your cluster has one or more reader DB instances, but none of them are in the Available state. For example, all reader instances might be rebooting or encountering problems. In that case, attempts to connect to a reader endpoint wait for a reader instance to become available. If no reader instance becomes available within the connection borrow timeout period, the connection attempt fails. If a reader instance does become available, the connection attempt succeeds.

  • Suppose that your cluster has no reader DB instances. In that case, RDS Proxy returns an error immediately if you try to connect to a reader endpoint. To resolve this problem, add one or more reader instances to your cluster before you connect to the reader endpoint.

How reader endpoints help query scalability

Reader endpoints for a proxy help with Aurora query scalability in the following ways:

  • As you add reader instances to your Aurora cluster, RDS Proxy can route new connections to any reader endpoints to the different reader instances. That way, queries performed using one reader endpoint connection don't slow down queries performed using another reader endpoint connection. The queries run on separate DB instances. Each DB instance has its own compute resources, buffer cache, and so on.

  • Where practical, RDS Proxy uses the same reader DB instance for all the queries issue using a particular reader endpoint connection. That way, a set of related queries on the same tables can take advantage of caching, plan optimization, and so on, on a particular DB instance.

  • If a reader DB instance becomes unavailable, the effect on your application depends on whether the session is multiplexed or pinned. If the session is multiplexed, RDS Proxy routes any subsequent queries to a different reader DB instance without any action on your part. If the session is pinned, your application gets an error and must reconnect. You can reconnect to the reader endpoint immediately and RDS Proxy routes the connection to an available reader DB instance. For more information about multiplexing and pinning for proxy sessions, see Overview of RDS Proxy concepts.

  • The more reader DB instances that you have in the cluster, the more simultaneous connections you can make using reader endpoints. For example, suppose that your cluster has four reader DB instances, each configured to support 200 simultaneous connections. Suppose also that your proxy is configured to use 50% of the maximum connections. Here, the maximum number of connections that you can make through the reader endpoints in the proxy is 100 (50% of 200) for reader 1. It's also 100 for reader 2, and so on, for a total of 400. If you double the number of cluster reader DB instances to eight, then the maximum number of connections through the reader endpoints also doubles, to 800.

Examples of using reader endpoints

The following Linux example shows how you can confirm that you're connected to an Aurora MySQL cluster through a reader endpoint. The innodb_read_only configuration setting is enabled. Attempts to perform write operations such as CREATE DATABASE statements fail with an error. And you can confirm that you're connected to a reader DB instance by checking the DB instance name using the aurora_server_id variable.

Tip

Don't rely only on checking the DB instance name to determine whether the connection is read/write or read-only. Remember that DB instances in an Aurora cluster can change roles between writer and reader when failovers happen. 

$ mysql -h endpoint-demo-reader.endpoint.proxy-demo.us-east-1.rds.amazonaws.com -u admin -p
...
mysql> select @@innodb_read_only;
+--------------------+
| @@innodb_read_only |
+--------------------+
|                  1 |
+--------------------+
mysql> create database shouldnt_work;
ERROR 1290 (HY000): The MySQL server is running with the --read-only option so it cannot execute this statement

mysql> select @@aurora_server_id;
+---------------------------------------+
| @@aurora_server_id                    |
+---------------------------------------+
| proxy-reader-endpoint-demo-instance-3 |
+---------------------------------------+

The following example shows how your connection to a proxy reader endpoint can keep working even when the reader DB instance is deleted. In this example, the Aurora cluster has two reader instances, instance-5507 and instance-7448. The connection to the reader endpoint begins using one of the reader instances. During the example, this reader instance is deleted by a delete-db-instance command. RDS Proxy switches to a different reader instance for subsequent queries. 

$ mysql -h reader-demo.endpoint.proxy-demo.us-east-1.rds.amazonaws.com
  -u my_user -p
...
mysql> select @@aurora_server_id;
+--------------------+
| @@aurora_server_id |
+--------------------+
| instance-5507      |
+--------------------+

mysql> select @@innodb_read_only;
+--------------------+
| @@innodb_read_only |
+--------------------+
|                  1 |
+--------------------+

mysql> select count(*) from information_schema.tables;
+----------+
| count(*) |
+----------+
|      328 |
+----------+

While the mysql session is still running, the following command deletes the reader instance that the reader endpoint is connected to. 

aws rds delete-db-instance --db-instance-identifier instance-5507 --skip-final-snapshot

Queries in the mysql session continue working without the need to reconnect. RDS Proxy automatically switches to a different reader DB instance. 

mysql> select @@aurora_server_id;
+--------------------+
| @@aurora_server_id |
+--------------------+
| instance-7448      |
+--------------------+

mysql> select count(*) from information_schema.TABLES;
+----------+
| count(*) |
+----------+
|      328 |
+----------+

Accessing Aurora databases across VPCs

By default, the components of your Aurora technology stack are all in the same Amazon VPC. For example, suppose that an application running on an Amazon EC2 instance connects to an Aurora DB cluster. In this case, the application server and database must both be within the same VPC.

With RDS Proxy, you can set up access to an Aurora DB cluster in one VPC from resources in another VPC, such as EC2 instances. For example, your organization might have multiple applications that access the same database resources. Each application might be in its own VPC.

To enable cross-VPC access, you create a new endpoint for the proxy. The proxy itself resides in the same VPC as the Aurora DB cluster. However, the cross-VPC endpoint resides in the other VPC, along with the other resources such as the EC2 instances. The cross-VPC endpoint is associated with subnets and security groups from the same VPC as the EC2 and other resources. These associations let you connect to the endpoint from the applications that otherwise can't access the database due to the VPC restrictions.

The following steps explain how to create and access a cross-VPC endpoint through RDS Proxy:

  1. Create two VPCs, or choose two VPCs that you already use for Aurora work. Each VPC should have its own associated network resources such as an internet gateway, route tables, subnets, and security groups. If you only have one VPC, you can consult Getting started with Amazon Aurora for the steps to set up another VPC to use Aurora successfully. You can also examine your existing VPC in the Amazon EC2 console to see the kinds of resources to connect together.

  2. Create a DB proxy associated with the Aurora DB cluster that you want to connect to. Follow the procedure in Creating an RDS Proxy.

  3. On the Details page for your proxy in the RDS console, under the Proxy endpoints section, choose Create endpoint. Follow the procedure in Creating a proxy endpoint.

  4. Choose whether to make the cross-VPC endpoint read/write or read-only.

  5. Instead of accepting the default of the same VPC as the Aurora DB cluster, choose a different VPC. This VPC must be in the same Amazon Region as the VPC where the proxy resides.

  6. Now instead of accepting the defaults for subnets and security groups from the same VPC as the Aurora DB cluster, make new selections. Make these based on the subnets and security groups from the VPC that you chose.

  7. You don't need to change any of the settings for the Secrets Manager secrets. The same credentials work for all endpoints for your proxy, regardless of which VPC each endpoint is in.

  8. Wait for the new endpoint to reach the Available state.

  9. Make a note of the full endpoint name. This is the value ending in Region_name.rds.amazonaws.com that you supply as part of the connection string for your database application.

  10. Access the new endpoint from a resource in the same VPC as the endpoint. A simple way to test this process is to create a new EC2 instance in this VPC. Then, log into the EC2 instance and run the mysql or psql commands to connect by using the endpoint value in your connection string.

Creating a proxy endpoint

To create a proxy endpoint

  1. Sign in to the Amazon Web Services Management Console and open the Amazon RDS console at https://console.amazonaws.cn/rds/.

  2. In the navigation pane, choose Proxies.

  3. Click the name of the proxy that you want to create a new endpoint for.

    The details page for that proxy appears.

  4. In the Proxy endpoints section, choose Create proxy endpoint.

    The Create proxy endpoint window appears.

  5. For Proxy endpoint name, enter a descriptive name of your choice.

  6. For Target role, choose whether to make the endpoint read/write or read-only.

    Connections that use read/write endpoints can perform any kind of operations, such as data definition language (DDL) statements, data manipulation language (DML) statements, and queries. These endpoints always connect to the primary instance of the Aurora cluster. You can use read/write endpoints for general database operations when you only use a single endpoint in your application. You can also use read/write endpoints for administrative operations, online transaction processing (OLTP) applications, and extract-transform-load (ETL) jobs.

    Connections that use a read-only endpoint can only perform queries. When there are multiple reader instances in the Aurora cluster, RDS Proxy can use a different reader instance for each connection to the endpoint. That way, a query-intensive application can take advantage of Aurora's clustering capability. You can add more query capacity to the cluster by adding more reader DB instances. These read-only connections don't impose any overhead on the primary instance of the cluster. That way, your reporting and analysis queries don't slow down the write operations of your OLTP applications.

  7. For Virtual Private Cloud (VPC), choose the default to access the endpoint from the same EC2 instances or other resources that normally use to access the proxy or its associated database. To set up cross-VPC access for this proxy, choose a VPC other than the default. For more information about cross-VPC access, see Accessing Aurora databases across VPCs.

  8. For Subnets, RDS Proxy fills in the same subnets as the associated proxy by default. To restrict access to the endpoint to only a portion of the VPC's address range being able to connect to it, remove one or more subnets.

  9. For VPC security group, you can choose an existing security group or create a new one. RDS Proxy fills in the same security group or groups as the associated proxy by default. If the inbound and outbound rules for the proxy are appropriate for this endpoint, then keep the default choice.

    If you choose to create a new security group, specify a name for the security group on this page. Then edit the security group settings from the EC2 console later.

  10. Choose Create proxy endpoint.

To create a proxy endpoint, use the Amazon CLI create-db-proxy-endpoint command.

Include the following required parameters:

  • --db-proxy-name value

  • --db-proxy-endpoint-name value

  • --vpc-subnet-ids list_of_ids. Separate the subnet IDs with spaces. You don't specify the ID of the VPC itself.

You can also include the following optional parameters:

  • --target-role { READ_WRITE | READ_ONLY }. This parameter defaults to READ_WRITE. The READ_ONLY value affects only Aurora provisioned clusters that contain one or more reader DB instances. When the proxy is associated with an Aurora cluster that only contains a writer DB instance, you can't specify READ_ONLY. For more information about the intended use of read-only endpoints with Aurora clusters, see Using reader endpoints with Aurora clusters .

  • --vpc-security-group-ids value. Separate the security group IDs with spaces. If you omit this parameter, RDS Proxy uses the default security group for the VPC. RDS Proxy determines the VPC based on the subnet IDs that you specify for the --vpc-subnet-ids parameter.

Example

The following example creates a proxy endpoint named my-endpoint.

For Linux, macOS, or Unix:

aws rds create-db-proxy-endpoint \
  --db-proxy-name my-proxy \
  --db-proxy-endpoint-name my-endpoint \
  --vpc-subnet-ids subnet_id subnet_id subnet_id ... \
  --target-role READ_ONLY \
  --vpc-security-group-ids security_group_id ]

For Windows:

aws rds create-db-proxy-endpoint ^
  --db-proxy-name my-proxy ^
  --db-proxy-endpoint-name my-endpoint ^
  --vpc-subnet-ids subnet_id_1 subnet_id_2 subnet_id_3 ... ^
  --target-role READ_ONLY ^
  --vpc-security-group-ids security_group_id

To create a proxy endpoint, use the RDS API CreateDBProxyEndpoint action.

Viewing proxy endpoints

To view the details for a proxy endpoint

  1. Sign in to the Amazon Web Services Management Console and open the Amazon RDS console at https://console.amazonaws.cn/rds/.

  2. In the navigation pane, choose Proxies.

  3. In the list, choose the proxy whose endpoint you want to view. Click the proxy name to view its details page.

  4. In the Proxy endpoints section, choose the endpoint that you want to view. Click its name to view the details page.

  5. Examine the parameters whose values you're interested in. You can check properties such as the following:

    • Whether the endpoint is read/write or read-only.

    • The endpoint address that you use in a database connection string.

    • The VPC, subnets, and security groups associated with the endpoint.

To view one or more proxy endpoints, use the Amazon CLI describe-db-proxy-endpoints command.

You can include the following optional parameters:

  • --db-proxy-endpoint-name

  • --db-proxy-name

The following example describes the my-endpoint proxy endpoint.

Example

For Linux, macOS, or Unix:

aws rds describe-db-proxy-endpoints \
  --db-proxy-endpoint-name my-endpoint

For Windows:

aws rds describe-db-proxy-endpoints ^
  --db-proxy-endpoint-name my-endpoint

To describe one or more proxy endpoints, use the RDS API DescribeDBProxyEndpoints operation.

Modifying a proxy endpoint

To modify one or more proxy endpoints

  1. Sign in to the Amazon Web Services Management Console and open the Amazon RDS console at https://console.amazonaws.cn/rds/.

  2. In the navigation pane, choose Proxies.

  3. In the list, choose the proxy whose endpoint you want to modify. Click the proxy name to view its

  4. In the Proxy endpoints section, choose the endpoint that you want to modify. You can select it in the list, or click its name to view the details page.

  5. On the proxy details page, under the Proxy endpoints section, choose Edit. Or, on the proxy endpoint details page, for Actions, choose Edit.

  6. Change the values of the parameters that you want to modify.

  7. Choose Save changes.

To modify a proxy endpoint, use the Amazon CLI modify-db-proxy-endpoint command with the following required parameters:

  • --db-proxy-endpoint-name

Specify changes to the endpoint properties by using one or more of the following parameters:

  • --new-db-proxy-endpoint-name

  • --vpc-security-group-ids. Separate the security group IDs with spaces.

The following example renames the my-endpoint proxy endpoint to new-endpoint-name.

Example

For Linux, macOS, or Unix:

aws rds modify-db-proxy-endpoint \
  --db-proxy-endpoint-name my-endpoint \
  --new-db-proxy-endpoint-name new-endpoint-name

For Windows:

aws rds modify-db-proxy-endpoint ^
  --db-proxy-endpoint-name my-endpoint ^
  --new-db-proxy-endpoint-name new-endpoint-name

To modify a proxy endpoint, use the RDS API ModifyDBProxyEndpoint operation.

Deleting a proxy endpoint

You can delete an endpoint for your proxy using the console as described following.

Note

You can't delete the default proxy endpoint that RDS Proxy automatically creates for each proxy.

When you delete a proxy, RDS Proxy automatically deletes all the associated endpoints.

To delete a proxy endpoint using the Amazon Web Services Management Console

  1. In the navigation pane, choose Proxies.

  2. In the list, choose the proxy whose endpoint you want to endpoint. Click the proxy name to view its details page.

  3. In the Proxy endpoints section, choose the endpoint that you want to delete. You can select one or more endpoints in the list, or click the name of a single endpoint to view the details page.

  4. On the proxy details page, under the Proxy endpoints section, choose Delete. Or, on the proxy endpoint details page, for Actions, choose Delete.

To delete a proxy endpoint, run the delete-db-proxy-endpoint command with the following required parameters:

  • --db-proxy-endpoint-name

The following command deletes the proxy endpoint named my-endpoint.

For Linux, macOS, or Unix:

aws rds delete-db-proxy-endpoint \
  --db-proxy-endpoint-name my-endpoint

For Windows:

aws rds delete-db-proxy-endpoint ^
  --db-proxy-endpoint-name my-endpoint

To delete a proxy endpoint with the RDS API, run the DeleteDBProxyEndpoint operation. Specify the name of the proxy endpoint for the DBProxyEndpointName parameter.

Limitations for proxy endpoints

RDS Proxy endpoints have the following limitations:

  • Each proxy has a default endpoint that you can modify but not create or delete.

  • The maximum number of user-defined endpoints for a proxy is 20. Thus, a proxy can have up to 21 endpoints: the default endpoint, plus 20 that you create.

  • When you associate additional endpoints with a proxy, RDS Proxy automatically determines which DB instances in your cluster to use for each endpoint. You can't choose specific instances the way that you can with Aurora custom endpoints.

  • Reader endpoints aren't available for Aurora multi-writer clusters.