Working with Amazon RDS Proxy endpoints - Amazon Relational Database Service
Overview of proxy endpointsProxy endpoints for Multi-AZ DB clusterAccessing RDS 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 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 RDS instance endpoints. If you aren't familiar with RDS endpoints, find more information in Connecting to a DB instance running the MySQL database engine and Connecting to a DB instance running the PostgreSQL database engine.

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.

Proxy endpoints for Multi-AZ DB cluster

By default, the endpoint that you connect to when you use RDS Proxy with a Multi-AZ DB 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 a Multi-AZ DB cluster, then 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 a Multi-AZ DB cluster. Doing so helps you to take advantage of the read scalability of a Multi-AZ DB 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 Multi-AZ DB cluster as needed. 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.

Reader endpoints for Multi-AZ DB clusters

With RDS Proxy, you can create and use reader endpoints. However, these endpoints only work for proxies associated with Multi-AZ DB clusters. If you use the RDS CLI or API, you might see the TargetRole attribute with a value of READ_ONLY. You can take advantage of such proxies by changing the target of a proxy from an RDS DB instance to a Multi-AZ DB cluster.

You can create and connect to read-only endpoints called reader endpoints when you use RDS Proxy with Multi-AZ DB clusters.

How reader endpoints help application availability

In some cases, a reader instance in your cluster might become unavailable. If that occurs, connections that use a reader endpoint of a DB proxy can recover more quickly than ones that use the Multi-AZ DB cluster reader endpoint. RDS Proxy routes connections to only the available reader instance 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 instance without any interruption to your application. If a reader instance is in an unavailable state, all client connections to that instance endpoint are closed.

If the connection is pinned, the next query on the connection returns an error. However, your application can immediately reconnect to the same proxy 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 instance.

If your Multi-AZ DB cluster doesn't have any available reader instances, RDS Proxy attempts to connect to a reader endpoint when it becomes 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.

How reader endpoints help query scalability

Reader endpoints for a proxy help with Multi-AZ DB cluster query scalability in the following ways:

  • 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.

Accessing RDS databases across VPCs

By default, the components of your RDS technology stack are all in the same Amazon VPC. For example, suppose that an application running on an Amazon EC2 instance connects to an Amazon RDS DB instance. 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 Amazon RDS DB instance 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 Amazon RDS DB instance. 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 RDS 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 RDS for the steps to set up another VPC to use RDS 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 Amazon RDS DB instance 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 Amazon RDS DB instance, 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 Amazon RDS DB instance, 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 RDS DB 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. RDS Proxy can use one of the reader instances for each connection to the endpoint. That way, a query-intensive application can take advantage of a Multi-AZ DB cluster's clustering capability. 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 RDS 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. When the proxy is associated with a Multi-AZ DB 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 Multi-AZ DB clusters, see Reader endpoints for Multi-AZ DB 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.