# Amazon RDS Proxy By using Amazon RDS Proxy, you can allow your applications to pool and share database connections to improve their ability to scale. RDS Proxy makes applications more resilient to database failures by automatically connecting to a standby DB instance while preserving application connections. By using RDS Proxy, you can enforce AWS Identity and Access Management (IAM) authentication for clients connecting to the proxy, and the proxy can connect to databases using either IAM database authentication or credentials stored in AWS Secrets Manager. ![\[An overview of how applications connect to RDS Proxy\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/Proxy-Overview.png) Using RDS Proxy, you can handle unpredictable surges in database traffic. Otherwise, these surges might cause issues due to oversubscribing connections or new connections being created at a fast rate. RDS Proxy establishes a database connection pool and reuses connections in this pool. This approach avoids the memory and CPU overhead of opening a new database connection each time. To protect a database against oversubscription, you can control the number of database connections that are created. RDS Proxy queues or throttles application connections that can't be served immediately from the connection pool. Although latencies might increase, your application can continue to scale without abruptly failing or overwhelming the database. If connection requests exceed the limits you specify, RDS Proxy rejects application connections (that is, it sheds load). At the same time, it maintains predictable performance for the load that RDS can serve with the available capacity. ![\[A detailed view of how applications connect to RDS Proxy and the types connections involved.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/Proxy-detail.png) You can reduce the overhead to process credentials and establish a secure connection for each new connection. RDS Proxy can handle some of that work on behalf of the database. RDS Proxy is fully compatible with the engine versions that it supports. You can enable RDS Proxy for most applications with no code changes. **Topics** + [ ## Region and version availability ](#rds-proxy.RegionVersionAvailability) + [ ## Quotas and limitations for RDS Proxy ](#rds-proxy.limitations) + [ # Planning where to use RDS Proxy ](rds-proxy-planning.md) + [ # RDS Proxy concepts and terminology ](rds-proxy.howitworks.md) + [ # Getting started with RDS Proxy ](rds-proxy-setup.md) + [ # Managing an RDS Proxy ](rds-proxy-managing.md) + [ # Working with Amazon RDS Proxy endpoints ](rds-proxy-endpoints.md) + [ # Monitoring RDS Proxy metrics with Amazon CloudWatch ](rds-proxy.monitoring.md) + [ # Working with RDS Proxy events ](rds-proxy.events.md) + [ # Troubleshooting for RDS Proxy ](rds-proxy.troubleshooting.md) + [ # Using RDS Proxy with AWS CloudFormation ](rds-proxy-cfn.md) + [ # Using RDS Proxy with Blue/Green Deployments ](rds-proxy-blue-green.md) ## Region and version availability Feature availability and support varies across specific versions of each database engine, and across AWS Regions. For more information on version and Region availability of Amazon RDS with RDS Proxy, see [Supported Regions and DB engines for Amazon RDS Proxy](Concepts.RDS_Fea_Regions_DB-eng.Feature.RDSProxy.md). ## Quotas and limitations for RDS Proxy The following quotas and limitations apply to RDS Proxy: + Each AWS account ID is limited to 20 proxies. If your application requires more proxies, request an increase via the **Service Quotas** page within the AWS Management Console. In the **Service Quotas** page, select **Amazon Relational Database Service (Amazon RDS)** and locate **Proxies** to request a quota increase. AWS can automatically increase your quota or pending review of your request by Support. + Each proxy can have up to 200 associated Secrets Manager secrets, thus limiting connections to up to 200 different user accounts when using secrets. + Each proxy has a default endpoint which is provisioned across only two Availability Zones selected from the proxy's configured subnets. If subnets in more than two AZs are configured, any two will be selected. + You can add up to 20 additional proxy endpoints for each proxy. These additional endpoints are provisioned across all the Availability Zones specified during their creation. You can create, view, modify, and delete these endpoints. + For RDS DB instances in replication configurations, you can associate a proxy only with the writer DB instance, not a read replica. + Your RDS Proxy must be in the same virtual private cloud (VPC) as the database. The proxy can't be publicly accessible, although the database can be. For example, if you're prototyping your database on a local host, you can't connect to your proxy unless you set up the necessary network requirements to allow connection to the proxy. This is because your local host is outside of the proxy’s VPC. + You can't use RDS Proxy with a VPC that has its tenancy set to `dedicated`. + You can't use RDS Proxy in a VPC that has encryption controls with `Enforce Mode` enabled. + For IPv6 endpoint network types, configure your VPC and subnets to support only IPv6. For both IPv4 and IPv6 target connection network types, configure your VPC and subnets to support dual-stack mode. + If you use RDS Proxy with an RDS DB instance that has IAM authentication enabled, the proxy can connect to the database using either IAM authentication or credentials stored in Secrets Manager. Clients connecting to the proxy must authenticate using IAM credentials. For detailed configuration instructions, see [Setting up database credentials for RDS Proxy](rds-proxy-secrets-arns.md) and [Configuring IAM authentication for RDS Proxy](rds-proxy-iam-setup.md) + You can't use RDS Proxy with custom DNS when using SSL hostname validation. + Each proxy can be associated with a single target DB instance . However, you can associate multiple proxies with the same DB instance . + Any statement with a text size greater than 16 KB causes the proxy to pin the session to the current connection. + Certain Regions have Availability-Zone (AZ) restrictions to consider while creating your proxy. US East (N. Virginia) Region does not support RDS Proxy in the `use1-az3` Availability Zone. US West (N. California) Region does not support RDS Proxy in the `usw1-az2` Availability Zone. When selecting subnets while creating your proxy, make sure that you don't select subnets in the Availability Zones mentioned above. + Currently, RDS Proxy doesn't support any global condition context keys. For more information about global condition context keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*. + You can't use RDS Proxy with RDS Custom for SQL Server. + To reflect any database parameter group modification to your proxy, an instance reboot is required even if your chose to apply your changes immediately. For cluster-level parameters, a cluster-wide reboot is required. + Your proxy automatically creates the `rdsproxyadmin` DB user when you register a proxy target. This is a protected user that is essential for proxy functionality. You should avoid tampering with the `rdsproxyadmin` user in any capacity. Deleting or modifying the `rdsproxyadmin` user or its permissions can result in complete unavailability of the proxy to your application. For additional limitations for each DB engine, see the following sections: + [Additional limitations for RDS for MariaDB](#rds-proxy.limitations-mdb) + [Additional limitations for RDS for Microsoft SQL Server](#rds-proxy.limitations-ms) + [Additional limitations for RDS for MySQL](#rds-proxy.limitations-my) + [Additional limitations for RDS for PostgreSQL](#rds-proxy.limitations-pg) ### Additional limitations for RDS for MariaDB The following additional limitations apply to RDS Proxy with RDS for MariaDB databases: + Currently, all proxies listen on port 3306 for MariaDB. The proxies still connect to your database using the port that you specified in the database settings. + You can't use RDS Proxy with self-managed MariaDB databases in Amazon EC2 instances. + You can't use RDS Proxy with an RDS for MariaDB DB instance that has the `read_only` parameter in its DB parameter group set to `1`. + RDS Proxy doesn't support MariaDB compressed mode. For example, it doesn't support the compression used by the `--compress` or `-C` options of the `mysql` command. + Some SQL statements and functions can change the connection state without causing pinning. For the most current pinning behavior, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). + RDS Proxy doesn't support the MariaDB `auth_ed25519` plugin. + RDS Proxy doesn't support Transport Layer Security (TLS) version 1.3 for MariaDB databases. + Database connections processing a `GET DIAGNOSTIC` command might return inaccurate information when RDS Proxy reuses the same database connection to run another query. This can happen when RDS Proxy multiplexes database connections. For more information, see [Overview of RDS Proxy concepts](rds-proxy.howitworks.md#rds-proxy-overview). + RDS Proxy currently doesn't support the `caching_sha2_password` option for `ClientPasswordAuthType` for MariaDB. **Important** For proxies associated with MariaDB databases, don't set the configuration parameter `sql_auto_is_null` to `true` or a nonzero value in the initialization query. Doing so might cause incorrect application behavior. ### Additional limitations for RDS for Microsoft SQL Server The following additional limitations apply to RDS Proxy with RDS for Microsoft SQL Server databases: + The number of Secrets Manager secrets that you need to create for a proxy depends on the collation that your DB instance uses. For example, suppose that your DB instance uses case-sensitive collation. If your application accepts both "Admin" and "admin," then your proxy needs two separate secrets. For more information about collation in SQL Server, see the [ Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/relational-databases/collations/collation-and-unicode-support?view=sql-server-ver16) documentation. + RDS Proxy doesn't support connections that use Active Directory. + You can't use IAM authentication with clients that don't support token properties. For more information, see [Considerations for connecting to Microsoft SQL Server](rds-proxy-connecting.md#rds-proxy-connecting-sqlserver). + The results of `@@IDENTITY`, `@@ROWCOUNT`, and `SCOPE_IDENTITY` aren't always accurate. As a work-around, retrieve their values in the same session statement to ensure that they return the correct information. + If the connection uses multiple active result sets (MARS), RDS Proxy doesn't run the initialization queries. For information about MARS, see the [ Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/relational-databases/native-client/features/using-multiple-active-result-sets-mars?view=sql-server-ver16) documentation. + Currently, RDS Proxy does not support RDS for SQL Server DB instances that run on major version *SQL Server 2022*. + RDS Proxy does not support RDS for SQL Server DB instances that run on major version *SQL Server 2014*. + RDS Proxy does not support client applications that can't handle multiple response messages in one TLS record. + RDS Proxy does not support end-to-end IAM authentication for RDS for SQL Server. ### Additional limitations for RDS for MySQL The following additional limitations apply to RDS Proxy with RDS for MySQL databases: + RDS Proxy support for `caching_sha2_password` authentication requires a secure (TLS) connection. + RDS Proxy support for `caching_sha2_password` is known to have compatibility issues with certain go-sql driver versions. + When using the MySQL 8.4 C driver, the `mysql_stmt_bind_named_param` API might form malformed packets if parameter count exceeds placeholder count in a prepared statements. This results in incorrect responses. For more information, see [MySQL bug report](https://bugs.mysql.com/bug.php?id=116860&thanks=4). + Currently, all proxies listen on port 3306 for MySQL. The proxies still connect to your database using the port that you specified in the database settings. + You can't use RDS Proxy with self-managed MySQL databases in EC2 instances. + You can't use RDS Proxy with an RDS for MySQL DB instance that has the `read_only` parameter in its DB parameter group set to `1`. + RDS Proxy doesn't support MySQL compressed mode. For example, it doesn't support the compression used by the `--compress` or `-C` options of the `mysql` command. + Database connections processing a `GET DIAGNOSTIC` command might return inaccurate information when RDS Proxy reuses the same database connection to run another query. This can happen when RDS Proxy multiplexes database connections. + Some SQL statements and functions such as `SET LOCAL` can change the connection state without causing pinning. For the most current pinning behavior, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). + Using the `ROW_COUNT()` function in a multi-statement query is not supported. + RDS Proxy does not support client applications that can't handle multiple response messages in one TLS record. + RDS Proxy does not support the MySQL dual passwords. + RDS Proxy might not work as expected when you configure the `init_connect` parameter in your RDS DB parameter group to set session state variables. Instead, set the initialization query for your proxy to run session initialization statements when using proxy to connect to your database. **Important** For proxies associated with MySQL databases, don't set the configuration parameter `sql_auto_is_null` to `true` or a nonzero value in the initialization query. Doing so might cause incorrect application behavior. ### Additional limitations for RDS for PostgreSQL The following additional limitations apply to RDS Proxy with RDS for PostgreSQL databases: + RDS Proxy doesn't support session pinning filters for PostgreSQL. + Currently, all proxies listen on port 5432 for PostgreSQL. + For PostgreSQL, RDS Proxy doesn't currently support canceling a query from a client by issuing a `CancelRequest`. This is the case, for example, when you cancel a long-running query in an interactive psql session by using Ctrl\$1C. + The results of the PostgreSQL function [lastval](https://www.postgresql.org/docs/current/functions-sequence.html) aren't always accurate. As a work-around, use the [INSERT](https://www.postgresql.org/docs/current/sql-insert.html) statement with the `RETURNING` clause. + RDS Proxy currently doesn't support streaming replication mode. + With RDS for PostgreSQL 16, modifications to the `scram_iterations` value exclusively impact the authentication process between the proxy and the database. Specifically, if you configure `ClientPasswordAuthType` to `scram-sha-256`, any customizations made to the `scram_iterations` value doesn't influence client-to-proxy password authentication. Instead, the iteration value for client-to-proxy password authentication is fixed at 4096. + The default `postgres` database must exist on the RDS for PostgreSQL instance for RDS Proxy to function. Don't delete this database even if your application uses different databases. + If you use `ALTER ROLE` to change the user role with `SET ROLE`, subsequent connections as that user to the proxy might not use this role setting, if those connections encounter pinning. To prevent this, when using proxy, use `SET ROLE` in the initialization query of the proxy. For more information, see **Initialization query** in [Creating a proxy for Amazon RDS](rds-proxy-creating.md). **Important** For existing proxies with PostgreSQL databases, if you modify the database authentication to use `SCRAM` only, the proxy becomes unavailable for up to 60 seconds. To avoid the issue, do one of the following: Ensure that the database allows both `SCRAM` and `MD5` authentication. To use only `SCRAM` authentication, create a new proxy, migrate your application traffic to the new proxy, then delete the proxy previously associated with the database. # Planning where to use RDS Proxy You can determine which of your DB instances, clusters, and applications might benefit the most from using RDS Proxy. To do so, consider these factors: + Any DB instance that encounters "too many connections" errors is a good candidate for associating with a proxy. This is often characterized by a high value of the `ConnectionAttempts` CloudWatch metric. The proxy enables applications to open many client connections, while the proxy manages a smaller number of long-lived connections to the DB instance . + For DB instances that use smaller AWS instance classes, such as T2 or T3, using a proxy can help avoid out-of-memory conditions. It can also help reduce the CPU overhead for establishing connections. These conditions can occur when dealing with large numbers of connections. + You can monitor certain Amazon CloudWatch metrics to determine whether a DB instance is approaching certain types of limit. These limits are for the number of connections and the memory associated with connection management. You can also monitor certain CloudWatch metrics to determine whether a DB instance is handling many short-lived connections. Opening and closing such connections can impose performance overhead on your database. For information about the metrics to monitor, see [Monitoring RDS Proxy metrics with Amazon CloudWatchMonitoring RDS Proxy with CloudWatch](rds-proxy.monitoring.md). + AWS Lambda functions can also be good candidates for using a proxy. These functions make frequent short database connections that benefit from connection pooling offered by RDS Proxy. You can take advantage of any IAM authentication you already have for Lambda functions, instead of managing database credentials in your Lambda application code. + Applications that typically open and close large numbers of database connections and don't have built-in connection pooling mechanisms are good candidates for using a proxy. + Applications that keep a large number of connections open for long periods are typically good candidates for using a proxy. Applications in industries such as software as a service (SaaS) or ecommerce often minimize the latency for database requests by leaving connections open. With RDS Proxy, an application can keep more connections open than it can when connecting directly to the DB instance. + You might not have adopted IAM authentication and Secrets Manager due to the complexity of setting up such authentication for all DB instances . The proxy can enforce the authentication policies for client connections for particular applications. You can take advantage of any IAM authentication you already have for Lambda functions, instead of managing database credentials in your Lambda application code. + RDS Proxy can help make applications more resilient and transparent to database failures. RDS Proxy bypasses Domain Name System (DNS) caches to reduce failover times by up to 66% for Amazon RDS Multi-AZ DB instances. RDS Proxy also automatically routes traffic to a new database instance while preserving application connections. This makes failovers more transparent for applications. + When updating your databases using Blue/Green Deployments, you can use RDS Proxy to minimize switchover downtime. During switchover, RDS Proxy maintains awareness of the transition and automatically redirects connections to the Green environment once it becomes the new production environment, eliminating DNS propagation delays. # RDS Proxy concepts and terminology You can simplify connection management for your Amazon RDS DB instances by using RDS Proxy. RDS Proxy handles the network traffic between the client application and the database. It does so in an active way first by understanding the database protocol. It then adjusts its behavior based on the SQL operations from your application and the result sets from the database. RDS Proxy reduces the memory and CPU overhead for connection management on your database. The database needs less memory and CPU resources when applications open many simultaneous connections. It also doesn't require logic in your applications to close and reopen connections that stay idle for a long time. Similarly, it requires less application logic to reestablish connections in case of a database problem. The infrastructure for RDS Proxy is highly available and deployed over multiple Availability Zones (AZs). The computation, memory, and storage for RDS Proxy are independent of your RDS DB instance. This separation helps lower overhead on your database servers, so that they can devote their resources to serving database workloads. The RDS Proxy compute resources are serverless, automatically scaling based on your database workload. **Topics** + [ ## Overview of RDS Proxy concepts ](#rds-proxy-overview) + [ ## Connection pooling ](#rds-proxy-connection-pooling) + [ ## RDS Proxy security ](#rds-proxy-security) + [ ## Failover ](#rds-proxy-failover) + [ ## Transactions ](#rds-proxy-transactions) ## Overview of RDS Proxy concepts RDS Proxy handles the infrastructure to perform connection pooling and the other features described in the sections that follow. You see the proxies represented in the RDS console on the **Proxies** page. Each proxy handles connections to a single RDS DB instance. The proxy automatically determines the current writer instance for RDS Multi-AZ DB instance or cluster. The connections that a proxy keeps open and available for your database applications to use make up the *connection pool*. By default, RDS Proxy can reuse a connection after each transaction in your session. This transaction-level reuse is called *multiplexing*. When RDS Proxy temporarily removes a connection from the connection pool to reuse it, that operation is called *borrowing* the connection. When it's safe to do so, RDS Proxy returns that connection to the connection pool. In some cases, RDS Proxy can't be sure that it's safe to reuse a database connection outside of the current session. In these cases, it keeps the session on the same connection until the session ends. This fallback behavior is called *pinning*. A proxy has a default endpoint. You connect to this endpoint when you work with an Amazon RDS DB instance. You do so instead of connecting to the read/write endpoint that connects directly to the instance . For RDS DB clusters, you can also create additional read/write and read-only endpoints. For more information, see [Overview of proxy endpoints](rds-proxy-endpoints.md#rds-proxy-endpoints-overview). For example, you can still connect to the cluster endpoint for read/write connections without connection pooling. You can still connect to the reader endpoint for load-balanced read-only connections. You can still connect to the instance endpoints for diagnosis and troubleshooting of specific DB instances within a cluster. If you use other AWS services such as AWS Lambda to connect to RDS databases, change their connection settings to use the proxy endpoint. For example, you specify the proxy endpoint to allow Lambda functions to access your database while taking advantage of RDS Proxy functionality. Each proxy contains a target group. This *target group* embodies the RDS DB instance that the proxy can connect to. The RDS DB instance associated with a proxy are called the *targets* of that proxy. For convenience, when you create a proxy through the console, RDS Proxy also creates the corresponding target group and registers the associated targets automatically. An *engine family* is a related set of database engines that use the same DB protocol. You choose the engine family for each proxy that you create. ## Connection pooling Each proxy performs connection pooling separately for the writer and reader instance of its associated RDS database . *Connection pooling* is an optimization that reduces the overhead associated with opening and closing connections and with keeping many connections open simultaneously. This overhead includes memory needed to handle each new connection. It also involves CPU overhead to close each connection and open a new one. Examples include Transport Layer Security/Secure Sockets Layer (TLS/SSL) handshaking, authentication, negotiating capabilities, and so on. Connection pooling simplifies your application logic. You don't need to write application code to minimize the number of simultaneous open connections. Each proxy also performs connection multiplexing, also known as connection reuse. With *multiplexing*, RDS Proxy performs all the operations for a transaction using one underlying database connection. RDS then can use a different connection for the next transaction. You can open many simultaneous connections to the proxy, and the proxy keeps a smaller number of connections open to the DB instance or cluster. Doing so further minimizes the memory overhead for connections on the database server. This technique also reduces the chance of "too many connections" errors. ## RDS Proxy security RDS Proxy uses the existing RDS security mechanisms such as TLS/SSL and AWS Identity and Access Management (IAM). For general information about those security features, see [Security in Amazon RDS ](UsingWithRDS.md). Also, make sure to familiarize yourself with how RDS work with authentication, authorization, and other areas of security. RDS Proxy can act as an additional layer of security between client applications and the underlying database. For example, you can connect to the proxy using TLS 1.3, even if the underlying DB instance supports an older version of TLS. You can connect to the proxy using an IAM role even if the proxy connects to the database using the database user and password authentication method. By using this technique, you can enforce strong authentication requirements for database applications without a costly migration effort for the DB instances themselves. You can use the following methods of authentication with RDS Proxy: + **Database credentials** + **Standard IAM authentication** + **End-to-end IAM authentication** ### Using IAM with RDS Proxy RDS Proxy offers two methods of IAM authentication: + **Standard IAM authentication**: Enforce IAM authentication for connections to your proxy while the proxy connects to the database using credentials stored in Secrets Manager. This enforces IAM authentication for database access even if the databases use native password authentication. The proxy retrieves the database credentials from Secrets Manager and handles the authentication to the database on behalf of your application. + **End-to-end IAM authentication**: Enforces IAM authentication for connections directly from your applications to your database through the proxy. End-to-end IAM authentication simplifies your security configuration and avoids database credential management in Secrets Manager. This additional layer of security enforces IAM-based access control from the client application to the database. To use standard IAM authentication, configure your proxy to use Secrets Manager secrets for authentication and enable IAM authentication for client connections. Your applications authenticate to the proxy using IAM, while the proxy authenticates to the database using the credentials retrieved from Secrets Manager. To use end-to-end IAM authentication, configure your proxy to use IAM authentication when setting the default authentication scheme when creating or modifying your proxy. For end-to-end IAM authentication, you must update the IAM role associated with the proxy to grant the `rds-db:connect` permission. With end-to-end IAM authentication, this eliminates the need to register individual database users with the proxy through Secrets Manager secrets. ### Using TLS/SSL with RDS Proxy You can connect to RDS Proxy using the TLS/SSL protocol. **Note** RDS Proxy uses certificates from the AWS Certificate Manager (ACM). If you are using RDS Proxy, you don't need to download Amazon RDS certificates or update applications that use RDS Proxy connections. To enforce TLS for all connections between the proxy and your database, you can specify a setting **Require Transport Layer Security** when you create or modify a proxy in the AWS Management Console. RDS Proxy can also ensure that your session uses TLS/SSL between your client and the RDS Proxy endpoint. To have RDS Proxy do so, specify the requirement on the client side. SSL session variables are not set for SSL connections to a database using RDS Proxy. + For RDS for MySQL, specify the requirement on the client side with the `--ssl-mode` parameter when you run the `mysql` command. + For Amazon RDS PostgreSQL, specify `sslmode=require` as part of the `conninfo` string when you run the `psql` command. RDS Proxy supports TLS protocol version 1.0, 1.1, 1.2, and 1.3. You can connect to the proxy using a higher version of TLS than you use in the underlying database. By default, client programs establish an encrypted connection with RDS Proxy, with further control available through the `--ssl-mode` option. From the client side, RDS Proxy supports all SSL modes. For the client, the SSL modes are the following: **PREFERRED** SSL is the first choice, but it isn't required. **DISABLED** No SSL is allowed. **REQUIRED** Enforce SSL. **VERIFY\$1CA** Enforce SSL and verify the certificate authority (CA). **VERIFY\$1IDENTITY** Enforce SSL and verify the CA and CA hostname. When using a client with `--ssl-mode` `VERIFY_CA` or `VERIFY_IDENTITY`, specify the `--ssl-ca` option pointing to a CA in `.pem` format. For the `.pem` file to use, download all root CA PEMs from [Amazon Trust Services ](https://www.amazontrust.com/repository/) and place them into a single `.pem` file. RDS Proxy uses wildcard certificates, which apply to both a domain and its subdomains. If you use the `mysql` client to connect with SSL mode `VERIFY_IDENTITY`, currently you must use the MySQL 8.0-compatible `mysql` command. ## Failover *Failover* is a high-availability feature that replaces a database instance with another one when the original instance becomes unavailable. A failover might happen because of a problem with a database instance. It might also be part of normal maintenance procedures, such as during a database upgrade. Failover applies to RDS DB instances in a Multi-AZ configuration. Connecting through a proxy makes your applications more resilient to database failovers. When the original DB instance becomes unavailable, RDS Proxy connects to the standby database without dropping idle application connections. This helps speed up and simplify the failover process. This is less disruptive to your application than a typical reboot or database problem. Without RDS Proxy, a failover involves a brief outage. During the outage, you can't perform write operations on the database in failover. Any existing database connections are disrupted, and your application must reopen them. The database becomes available for new connections and write operations when a read-only DB instance is promoted in place of one that's unavailable. During DB failovers, RDS Proxy continues to accept connections at the same IP address and automatically directs connections to the new primary DB instance. Clients connecting through RDS Proxy are not susceptible to the following: + Domain Name System (DNS) propagation delays on failover. + Local DNS caching. + Connection timeouts. + Uncertainty about which DB instance is the current writer. + Waiting for a query response from a former writer that became unavailable without closing connections. For applications that maintain their own connection pool, going through RDS Proxy means that most connections stay alive during failovers or other disruptions. Only connections that are in the middle of a transaction or SQL statement are canceled. RDS Proxy immediately accepts new connections. When the database writer is unavailable, RDS Proxy queues up incoming requests. For applications that don't maintain their own connection pools, RDS Proxy offers faster connection rates and more open connections. It offloads the expensive overhead of frequent reconnects from the database. It does so by reusing database connections maintained in the RDS Proxy connection pool. This approach is particularly important for TLS connections, where setup costs are significant. ## Transactions All the statements within a single transaction always use the same underlying database connection. The connection becomes available for use by a different session when the transaction ends. Using the transaction as the unit of granularity has the following consequences: + Connection reuse can happen after each individual statement when the RDS for MySQL `autocommit` setting is turned on. + Conversely, when the `autocommit` setting is turned off, the first statement you issue in a session begins a new transaction. For example, suppose that you enter a sequence of `SELECT`, `INSERT`, `UPDATE`, and other data manipulation language (DML) statements. In this case, connection reuse doesn't happen until you issue a `COMMIT`, `ROLLBACK`, or otherwise end the transaction. + Entering a data definition language (DDL) statement causes the transaction to end after that statement completes. RDS Proxy detects when a transaction ends through the network protocol used by the database client application. Transaction detection doesn't rely on keywords such as `COMMIT` or `ROLLBACK` appearing in the text of the SQL statement. In some cases, RDS Proxy might detect a database request that makes it impractical to move your session to a different connection. In these cases, it turns off multiplexing for that connection the remainder of your session. The same rule applies if RDS Proxy can't be certain that multiplexing is practical for the session. This operation is called *pinning*. For ways to detect and minimize pinning, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). # Getting started with RDS Proxy Use the information in the following pages to set up and manage [Amazon RDS Proxy](rds-proxy.md) and set related security options. The security options control who can access each proxy and how each proxy connects to DB instances. If you're new to RDS Proxy, we recommend following the pages in the order that we present them. **Topics** + [ # Setting up network prerequisites for RDS Proxy ](rds-proxy-network-prereqs.md) + [ # Setting up database credentials for RDS Proxy ](rds-proxy-secrets-arns.md) + [ # Configuring IAM authentication for RDS Proxy ](rds-proxy-iam-setup.md) + [ # Creating a proxy for Amazon RDS ](rds-proxy-creating.md) + [ # Viewing a proxy ](rds-proxy-viewing.md) + [ # Connecting to a database through RDS Proxy ](rds-proxy-connecting.md) # Setting up network prerequisites for RDS Proxy Using RDS Proxy requires you to have a common virtual private cloud (VPC) between your RDS DB instance and RDS Proxy. This VPC should have a minimum of two subnets that are in different Availability Zones. Your account can either own these subnets or share them with other accounts. For information about VPC sharing, see [Work with shared VPCs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html). For IPv6 support, additional network configuration is required: + **IPv6 endpoint network types** – Your VPC and subnets must be configured to support IPv6. This includes having IPv6 CIDR blocks assigned to your VPC and subnets. + **Dual-stack endpoint network types** – Your VPC and subnets must support both IPv4 and IPv6 addressing. + **IPv6 target connection network types** – Your database must be configured for dual-stack mode to support IPv6 connections from the proxy. Your client application resources such as Amazon EC2, Lambda, or Amazon ECS can be in the same VPC as the proxy. Or they can be in a separate VPC from the proxy. If you successfully connected to any RDS DB instances , you already have the required network resources. **Topics** + [ ## Getting information about your subnets ](#rds-proxy-network-prereqs.subnet-info) + [ ## Planning for IP address capacity ](#rds-proxy-network-prereqs.plan-ip-address) ## Getting information about your subnets To create a proxy, you must provide the subnets and the VPC that the proxy operates within. The following Linux example shows AWS CLI commands that examine the VPCs and subnets owned by your AWS account. In particular, you pass subnet IDs as parameters when you create a proxy using the CLI. ``` aws ec2 describe-vpcs aws ec2 describe-internet-gateways aws ec2 describe-subnets --query '*[].[VpcId,SubnetId]' --output text | sort ``` The following Linux example shows AWS CLI commands to determine the subnet IDs corresponding to a specific RDS DB instance. Find the VPC ID for the DB instance. Examine the VPC to find its subnets. The following Linux example shows how. ``` $ #From the DB instance, trace through the DBSubnetGroup and Subnets to find the subnet IDs. $ aws rds describe-db-instances --db-instance-identifier my_instance_id --query '*[].[DBSubnetGroup]|[0]|[0]|[Subnets]|[0]|[*].SubnetIdentifier' --output text ``` ``` subnet_id_1 subnet_id_2 subnet_id_3 ... ``` ``` $ #From the DB instance, find the VPC. $ aws rds describe-db-instances --db-instance-identifier my_instance_id --query '*[].[DBSubnetGroup]|[0]|[0].VpcId' --output text ``` ``` my_vpc_id ``` ``` $ aws ec2 describe-subnets --filters Name=vpc-id,Values=my_vpc_id --query '*[].[SubnetId]' --output text ``` ``` subnet_id_1 subnet_id_2 subnet_id_3 subnet_id_4 subnet_id_5 subnet_id_6 ``` ## Planning for IP address capacity An RDS Proxy automatically adjusts its capacity as needed based on the size and number of DB instances registered with it. Certain operations might also require additional proxy capacity such as increasing the size of a registered database or internal RDS Proxy maintenance operations. During these operations, your proxy might need more IP addresses to provision the extra capacity. These additional addresses allow your proxy to scale without affecting your workload. A lack of free IP addresses in your subnets prevents a proxy from scaling up. This can lead to higher query latencies or client connection failures. RDS notifies you through event `RDS-EVENT-0243` when there aren't enough free IP addresses in your subnets. For information about this event, see [Working with RDS Proxy eventsWorking with RDS Proxy events](rds-proxy.events.md). **Note** RDS Proxy doesn't consume more than 215 IP addresses for each proxy in a VPC. Reserve the following minimum numbers of free IP addresses in your subnets for your proxy, based on DB instance class sizes. | DB instance class | Minimum free IP addresses | | --- | --- | | db.\$1.xlarge or smaller | 10 | | db.\$1.2xlarge | 15 | | db.\$1.4xlarge | 25 | | db.\$1.8xlarge | 45 | | db.\$1.12xlarge | 60 | | db.\$1.16xlarge | 75 | | db.\$1.24xlarge | 110 | These recommended numbers of IP addresses are estimates for a proxy with only the default endpoint. A proxy with additional endpoints or read replicas might need more free IP addresses. For each additional endpoint, we recommend that you reserve three more IP addresses. For each read replica, we recommend that you reserve additional IP addresses as specified in the table based on that read replica's size. # Setting up database credentials for RDS Proxy RDS Proxy in Amazon RDS uses AWS Secrets Manager to store and manage database credentials securely. Instead of embedding credentials in your application, you associate a proxy with a Secrets Manager secret that contains the necessary authentication details. You create a separate Secrets Manager secret for each database user account that the proxy connects to on the RDS DB instance. Alternatively, you can configure RDS Proxy to use end-to-end IAM authentication, which eliminates the need to store database credentials in Secrets Manager. RDS Proxy uses IAM authentication for both client-to-proxy and proxy-to-database connections. This provides a fully integrated IAM-based authentication solution that doesn't require managing secrets or passwords. For information about adding a new IAM DB user, see [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md). **Topics** + [ ## Creating secrets to use with RDS Proxy ](#rds-proxy-secrets-create) ## Creating secrets to use with RDS Proxy Before you create a proxy, you must first create at least one secret that stores your database credentials. ### Console **To create a secret** 1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. Choose **Store a new secret**. 1. Choose **Credentials for Amazon RDS database**. 1. Enter a user name and password. The credentials that you enter must match the credentials of a database user that exists in the associated RDS database. RDS Proxy uses these credentials to authenticate and establish connections to the database on behalf of applications. If there's a mismatch, you can update the secret to match the database password. Until you update the secret, attempts to connect through the proxy using that secret fail, but connections using other valid secrets still work. **Note** For RDS for SQL Server, RDS Proxy requires a case-sensitive secret in Secrets Manager, regardless of the DB instance collation settings. If your application allows usernames with different capitalizations, such as "Admin" and "admin," you must create separate secrets for each. RDS Proxy doesn't support case-insensitive username authentication between the client and proxy. For more information about collation in SQL Server, see the [ Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/relational-databases/collations/collation-and-unicode-support?view=sql-server-ver16) documentation. 1. For **Database**, select the Amazon RDS database that the secret will access. 1. Fill in other settings for the secret, then choose **Store**. For comprehensive instructions, see [Creating an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *AWS Secrets Manager User Guide*. ### AWS CLI When you create a proxy through the AWS CLI, you specify the Amazon Resource Names (ARNs) of the corresponding secrets. You do so for all the DB user accounts that the proxy can access. In the AWS Management Console, you choose the secrets by their descriptive names. + To create a Secrets Manager secret for use with RDS Proxy, use the [create-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html) command: ``` aws secretsmanager create-secret \ --name "secret_name" \ --description "secret_description" \ --region region_name \ --secret-string '{"username":"db_user","password":"db_user_password"}' ``` + You can also create a custom key to encrypt your Secrets Manager secret. The following command creates an example key. ``` aws kms create-key --description "test-key" --policy '{ "Id":"kms-policy", "Version": "2012-10-17", "Statement": [ { "Sid":"Enable IAM User Permissions", "Effect":"Allow", "Principal":{"AWS":"arn:aws:iam::account_id:root"}, "Action":"kms:*","Resource":"*" }, { "Sid":"Allow access for Key Administrators", "Effect":"Allow", "Principal": { "AWS": ["$USER_ARN","arn:aws:iam:account_id::role/Admin"] }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource":"*" }, { "Sid":"Allow use of the key", "Effect":"Allow", "Principal":{"AWS":"$ROLE_ARN"}, "Action":["kms:Decrypt","kms:DescribeKey"], "Resource":"*" } ] }' ``` For example, the following commands create Secrets Manager secrets for two database users: ``` aws secretsmanager create-secret \ --name secret_name_1 --description "db admin user" \ --secret-string '{"username":"admin","password":"choose_your_own_password"}' aws secretsmanager create-secret \ --name secret_name_2 --description "application user" \ --secret-string '{"username":"app-user","password":"choose_your_own_password"}' ``` To create these secrets encrypted with your custom AWS KMS key, use the following commands: ``` aws secretsmanager create-secret \ --name secret_name_1 --description "db admin user" \ --secret-string '{"username":"admin","password":"choose_your_own_password"}' \ --kms-key-id arn:aws:kms:us-east-2:account_id:key/key_id aws secretsmanager create-secret \ --name secret_name_2 --description "application user" \ --secret-string '{"username":"app-user","password":"choose_your_own_password"}' \ --kms-key-id arn:aws:kms:us-east-2:account_id:key/key_id ``` To see the secrets owned by your AWS account, use the [list-secrets](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/list-secrets.html) command: ``` aws secretsmanager list-secrets ``` When you create a proxy using the CLI, you pass the Amazon Resource Names (ARNs) of one or more secrets to the `--auth` parameter. The following example shows how to prepare a report with only the name and ARN of each secret owned by your AWS account. This example uses the `--output table` parameter that is available in AWS CLI version 2. If you are using AWS CLI version 1, use `--output text` instead. ``` aws secretsmanager list-secrets --query '*[].[Name,ARN]' --output table ``` To confirm that the secret contains the correct credentials in the proper format, use the [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) command. Replace `your_secret_name` with the secret’s short name or ARN. ``` aws secretsmanager get-secret-value --secret-id your_secret_name ``` The output contains a line with a JSON-encoded value similar to the following: ``` ... "SecretString": "{\"username\":\"your_username\",\"password\":\"your_password\"}", ... ``` # Configuring IAM authentication for RDS Proxy To set up AWS Identity and Access Management (IAM) authentication for RDS Proxy in Amazon RDS, create and configure an IAM policy that grants the necessary permissions. This topic provides the steps to configure IAM authentication for RDS Proxy, including creating the required IAM policy and attaching it to an IAM role. **Tip** This procedure is only necessary if you want to create your own IAM role. Otherwise, RDS can automatically create the required role when you set up the proxy, so you can skip these steps. ## Prerequisites Before you set up IAM authentication for RDS Proxy, make sure that you have the following: + **AWS Secrets Manager** – At least one stored secret that contains database credentials. For instructions to create secrets, see [Setting up database credentials for RDS Proxy](rds-proxy-secrets-arns.md). This is not required if you are using end-to-end IAM authentication. + **IAM permissions** – An IAM role or user with permissions to create and manage IAM policies, roles, and secrets in AWS Secrets Manager. ## Creating an IAM policy for end-to-end IAM authentication When using end-to-end IAM authentication, RDS Proxy connects to your database using IAM authentication instead of retrieving credentials from Secrets Manager. This requires configuring your IAM role with `rds-db:connect` permissions for the database accounts you want to use with the proxy. To authenticate your RDS Proxy to the database using IAM, create an IAM role with a policy that grants the necessary database connection permissions. ### Console **To create a role for end-to-end IAM authentication with your proxy** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Create a permissions policy for the role. For general steps, see [Create IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html). Paste this policy into the JSON editor and make the following changes: + Substitute your own account ID. + Substitute `us-east-2` with the where the proxy must reside. + Substitute the database resource IDs and user names with the ones you want to use. The resource ID format differs between RDS instances and Aurora clusters. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "rds-db:connect", "Resource": [ "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_1", "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_2" ] } ] } ``` 1. Create the role and attach the permissions policy to it. For general steps, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). For the **Trusted entity type**, choose **AWS service**. Under **Use case**, select **RDS** and choose **RDS - Add Role to Database** for the use case. 1. For **Permissions policies**, choose the policy that you created. 1. For **Select trusted entities**, enter the following trust policy for the role: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ### AWS CLI To create the role using the AWS CLI, send the following request: ``` aws iam create-role \ --role-name my_e2e_iam_role_name \ --assume-role-policy-document '{"Version":"2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":["rds.amazonaws.com"]},"Action":"sts:AssumeRole"}]}' ``` Then, attach the policy to the role: ``` aws iam put-role-policy \ --role-name my_e2e_iam_role_name \ --policy-name e2e_iam_db_connect_policy \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "rds-db:connect", "Resource": [ "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_1", "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_2" ] } ] }' ``` With the IAM role and permissions configured for end-to-end IAM authentication, you can now create a proxy with `DefaultAuthScheme` set to `IAM_AUTH`. This proxy directly authenticates to the database using IAM without requiring Secrets Manager secrets. For instructions, see [Creating a proxy for Amazon RDS](rds-proxy-creating.md). When using end-to-end IAM authentication, ensure that your database users are configured for IAM authentication as described in [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md). ## Creating an IAM policy for Secrets Manager access To allow RDS Proxy to retrieve database credentials from Secrets Manager, create an IAM role with a policy that grants the necessary permissions. ## Console **To create a role to access your secrets for use with your proxy** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Create a permissions policy for the role. For general steps, see [Create IAM policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html). Paste this policy into the JSON editor and make the following changes: + Substitute your own account ID. + Substitute `us-east-2` with the Region where the proxy will reside. + Substitute the secret names with the ones you created. For more information, see [ Specifying KMS keys in IAM policy statements](https://docs.aws.amazon.com/kms/latest/developerguide/cmks-in-iam-policies.html). + Substitue the KMS key ID with the one you used to encrypt the Secrets Manager secrets, either the default key or your own key. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": [ "arn:aws:secretsmanager:us-east-2:111122223333:secret:secret_name_1", "arn:aws:secretsmanager:us-east-2:111122223333:secret:secret_name_2" ] }, { "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "arn:aws:kms:us-east-2:111122223333:key/key_id", "Condition": { "StringEquals": { "kms:ViaService": "secretsmanager.us-east-2.amazonaws.com" } } } ] } ``` ------ 1. Create the role and attach the permissions policy to it. For general steps, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). For the **Trusted entity type**, choose **AWS service**. Under **Use case**, select **RDS** and choose **RDS - Add Role to Database** for the use case. 1. For **Permissions policies**, choose the policy that you created. 1. For **Select trusted entities**, enter the following trust policy for the role: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "rds.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ ## AWS CLI To create the role using the AWS CLI, send the following request: ``` aws iam create-role \ --role-name my_role_name \ --assume-role-policy-document '{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":["rds.amazonaws.com"]},"Action":"sts:AssumeRole"}]}' ``` Then, attach the policy to the role: ``` aws iam put-role-policy \ --role-name my_role_name \ --policy-name secret_reader_policy \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": [ "arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_1", "arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_2" ] }, { "Sid": "VisualEditor1", "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "arn:aws:kms:us-east-2:account_id:key/key_id", "Condition": { "StringEquals": { "kms:ViaService": "secretsmanager.us-east-2.amazonaws.com" } } } ] }' ``` With the IAM role and permissions configured, you can now create a proxy and associate it with this role. This allows the proxy to retrieve database credentials securely from AWS Secrets Manager and enable IAM authentication for your applications. For instructions, see [Creating a proxy for Amazon RDS](rds-proxy-creating.md). # Creating a proxy for Amazon RDS You can associate a proxy with an RDS for MariaDB, RDS for Microsoft SQL Server, RDS for MySQL, or RDS for PostgreSQL DB instance. ## Console **To create a proxy** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. Choose **Create proxy**. 1. Configure the following settings for your proxy. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy-creating.html) 1. Choose **Create proxy**. ## AWS CLI To create a proxy by using the AWS CLI, call the [create-db-proxy](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-proxy.html) command with the following required parameters: + `--db-proxy-name` + `--engine-family` + `--role-arn` + `--vpc-subnet-ids` The `--engine-family` value is case-sensitive. **Example** For Linux, macOS, or Unix: ``` aws rds create-db-proxy \ --db-proxy-name proxy_name \ --engine-family { MYSQL | POSTGRESQL | SQLSERVER } \ --role-arn iam_role \ --vpc-subnet-ids space_separated_list \ [--default-auth-scheme { NONE | IAM_AUTH }] \ [--auth ProxyAuthenticationConfig_JSON_string] \ [--vpc-security-group-ids space_separated_list] \ [--require-tls | --no-require-tls] \ [--idle-client-timeout value] \ [--debug-logging | --no-debug-logging] \ [--endpoint-network-type { IPV4 | IPV6 | DUAL }] \ [--target-connection-network-type { IPV4 | IPV6 }] \ [--tags comma_separated_list] ``` For Windows: ``` aws rds create-db-proxy ^ --db-proxy-name proxy_name ^ --engine-family { MYSQL | POSTGRESQL | SQLSERVER } ^ --role-arn iam_role ^ --vpc-subnet-ids space_separated_list ^ [--default-auth-scheme { NONE | IAM_AUTH }] ^ [--auth ProxyAuthenticationConfig_JSON_string] ^ [--vpc-security-group-ids space_separated_list] ^ [--require-tls | --no-require-tls] ^ [--idle-client-timeout value] ^ [--debug-logging | --no-debug-logging] ^ [--endpoint-network-type { IPV4 | IPV6 | DUAL }] ^ [--target-connection-network-type { IPV4 | IPV6 }] ^ [--tags comma_separated_list] ``` The following is an example of the JSON value for the `--auth` option. This example applies a different client authentication type to each secret. ``` [ { "Description": "proxy description 1", "AuthScheme": "SECRETS", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789123:secret/1234abcd-12ab-34cd-56ef-1234567890ab", "IAMAuth": "DISABLED", "ClientPasswordAuthType": "POSTGRES_SCRAM_SHA_256" }, { "Description": "proxy description 2", "AuthScheme": "SECRETS", "SecretArn": "arn:aws:secretsmanager:us-west-2:111122223333:secret/1234abcd-12ab-34cd-56ef-1234567890cd", "IAMAuth": "DISABLED", "ClientPasswordAuthType": "POSTGRES_MD5" }, { "Description": "proxy description 3", "AuthScheme": "SECRETS", "SecretArn": "arn:aws:secretsmanager:us-west-2:111122221111:secret/1234abcd-12ab-34cd-56ef-1234567890ef", "IAMAuth": "REQUIRED" } ] ``` The `--endpoint-network-type` parameter specifies the IP version for the proxy endpoint that clients use to connect to the proxy. Valid values are: + `IPV4` – The proxy endpoint uses IPv4 addresses only (default). + `IPV6` – The proxy endpoint uses IPv6 addresses only. + `DUAL` – The proxy endpoint supports both IPv4 and IPv6 addresses. The `--target-connection-network-type` parameter specifies the IP version that the proxy uses to connect to the target database. Valid values are: + `IPV4` – The proxy connects to the database using IPv4 addresses (default). + `IPV6` – The proxy connects to the database using IPv6 addresses. To use IPv6 or dual-stack endpoint network types, your VPC and subnets must be configured to support the selected network type. To use IPv6 target connection network type, your database must support dual-stack mode. **Tip** If you don't already know the subnet IDs to use for the `--vpc-subnet-ids` parameter, see [Setting up network prerequisites for RDS Proxy](rds-proxy-network-prereqs.md) for examples of how to find them. **Note** The security group must allow access to the database the proxy connects to. The same security group is used for ingress from your applications to the proxy, and for egress from the proxy to the database. For example, suppose that you use the same security group for your database and your proxy. In this case, make sure that you specify that resources in that security group can communicate with other resources in the same security group. When using a shared VPC, you can't use the default security group for the VPC, or one that belongs to another account. Choose a security group that belongs to your account. If one doesn't exist, create one. For more information about this limitation, see [Work with shared VPCs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html#vpc-share-limitations). To create the right associations for the proxy, you also use the [register-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/register-db-proxy-targets.html) command. Specify the target group name `default`. RDS Proxy automatically creates a target group with this name when you create each proxy. ``` aws rds register-db-proxy-targets --db-proxy-name value [--target-group-name target_group_name] [--db-instance-identifiers space_separated_list] # rds db instances, or [--db-cluster-identifiers cluster_id] # rds db cluster (all instances) ``` ## RDS API To create an RDS proxy, call the Amazon RDS API operation [CreateDBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBProxy.html). You pass a parameter with the [AuthConfig](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_AuthConfig.html) data structure. RDS Proxy automatically creates a target group named `default` when you create each proxy. You associate an RDS DB instance with the target group by calling the function [RegisterDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RegisterDBProxyTargets.html). **Important** When you select **IAM authentication** for the default authentication scheme: You must enable IAM database authentication on your target database instances or clusters before the proxy can successfully connect. If you choose **Create IAM role**, the **Database accounts for IAM authentication** field is required. If you select an existing IAM role, the console does not automatically update the role with database connection permissions. Check that the role has the necessary `rds-db:connect` permissions. # Viewing a proxy After you create one or more RDS proxies, you can view and manage them in the AWS Management Console, the AWS CLI, or the RDS API. You can review their configuration details, monitor performance, and determine which proxies to modify or delete as needed. To enable database applications to route traffic through a proxy, you must specify the proxy endpoint in the connection string. ## Console **To view a proxy in the console** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. Select the proxy name to view its details. 1. On the details page, the **Target groups** section shows how the proxy is linked to a specific RDS DB instance. You can navigate to the default target group page for a deeper view of this association, including configuration settings defined during proxy creation. These settings include the maximum connection percentage, connection borrow timeout, engine family, and session pinning filters. ## CLI To view your proxy using the CLI, use the [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) command. By default, the request returns all proxies owned by your AWS account. To see details for a single proxy, specify its name with the `--db-proxy-name` parameter. ``` aws rds describe-db-proxies [--db-proxy-name proxy_name] ``` To view other information associated with the proxy, use the following commands. ``` aws rds describe-db-proxy-target-groups --db-proxy-name proxy_name aws rds describe-db-proxy-targets --db-proxy-name proxy_name ``` Use the following sequence of commands to see more detail about the things that are associated with the proxy: 1. To get a list of proxies, run [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html). 1. To show connection parameters such as the maximum percentage of connections that the proxy can use, run [describe-db-proxy-target-groups](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-target-groups.html) `--db-proxy-name`. Use the name of the proxy as the parameter value. 1. To see the details of the RDS DB instance associated with the returned target group, run [describe-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html). ## RDS API To view your proxies using the RDS API, use the [DescribeDBProxies](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxies.html) operation. It returns values of the [DBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxy.html) data type. To see details of the connection settings for the proxy, use the proxy identifiers from this return value with the [DescribeDBProxyTargetGroups](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxyTargetGroups.html) operation. It returns values of the [DBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxyTargetGroup.html) data type. To see the RDS instance or Aurora DB cluster associated with the proxy, use the [DescribeDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxyTargets.html) operation. It returns values of the [DBProxyTarget](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxyTarget.html) data type. # Connecting to a database through RDS Proxy The way to connect to an RDS DB instance through a proxy or by connecting to the database is generally the same. For more information, see [Overview of proxy endpoints](rds-proxy-endpoints.md#rds-proxy-endpoints-overview). **Topics** + [ ## Connecting to a database using database credentials ](#rds-proxy-connecting-native) + [ ## Connecting to a database using IAM authentication ](#rds-proxy-connecting-iam) + [ ## Considerations for connecting to Microsoft SQL Server ](#rds-proxy-connecting-sqlserver) + [ ## Considerations for connecting to PostgreSQL ](#rds-proxy-connecting-postgresql) ## Connecting to a database using database credentials Use the following steps to connect to a proxy using database credentials: 1. Find the proxy endpoint. In the AWS Management Console, you can find the endpoint on the details page for the corresponding proxy. With the AWS CLI, you can use the [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) command. The following example shows how. ``` # Add --output text to get output as a simple tab-separated list. $ aws rds describe-db-proxies --query '*[*].{DBProxyName:DBProxyName,Endpoint:Endpoint}' [ [ { "Endpoint": "the-proxy.proxy-demo.us-east-1.rds.amazonaws.com", "DBProxyName": "the-proxy" }, { "Endpoint": "the-proxy-other-secret.proxy-demo.us-east-1.rds.amazonaws.com", "DBProxyName": "the-proxy-other-secret" }, { "Endpoint": "the-proxy-rds-secret.proxy-demo.us-east-1.rds.amazonaws.com", "DBProxyName": "the-proxy-rds-secret" }, { "Endpoint": "the-proxy-t3.proxy-demo.us-east-1.rds.amazonaws.com", "DBProxyName": "the-proxy-t3" } ] ] ``` 1. Specify the endpoint as the host parameter in the connection string for your client application. For example, specify the proxy endpoint as the value for the `mysql -h` option or `psql -h` option. 1. Supply the same database user name and password as you usually do. ## Connecting to a database using IAM authentication When you use IAM authentication with RDS Proxy, you have two options for authentication between your client and proxy: + Set up your database users to authenticate with regular user names and passwords. RDS Proxy retrieves the user name and password credentials from Secrets Manager. The connection from RDS Proxy to the underlying database doesn't go through IAM. + You can also use end-to-end IAM authentication, which connects to your database through the proxy using IAM without requiring database credentials. To connect to RDS Proxy using IAM authentication, use the same general connection procedure as for IAM authentication with an RDS DB instance. For general information about using IAM, see [Security in Amazon RDS ](UsingWithRDS.md). If you are using end-to-end IAM authentication, provide the IAM authentication plugin to your DB user. See [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md). The major differences in IAM usage for RDS Proxy include the following: + With standard IAM authentication, database users have regular credentials within the database. You set up Secrets Manager secrets containing these user names and passwords, and authorize RDS Proxy to retrieve the credentials from Secrets Manager. The IAM authentication applies to the connection between your client program and the proxy. The proxy then authenticates to the database using the user name and password credentials retrieved from Secrets Manager. + With end-to-end IAM authentication, you don't need to configure Secrets Manager secrets for database credentials. The IAM authentication applies to the connection between the client to the proxy and proxy to the database. + Instead of the instance, cluster, or reader endpoint, you specify the proxy endpoint. For details about the proxy endpoint, see [Connecting to your DB instance using IAM authentication](UsingWithRDS.IAMDBAuth.Connecting.md). + Make sure that you use Transport Layer Security (TLS)/Secure Sockets Layer (SSL) when connecting to a proxy using IAM authentication. You can grant a specific user access to the proxy by modifying the IAM policy. An example follows. ``` "Resource": "arn:aws:rds-db:us-east-2:1234567890:dbuser:prx-ABCDEFGHIJKL01234/db_user" ``` **Tip** When configuring IAM authentication for RDS Proxy connections, follow these important guidelines to avoid connection issues: Do not grant the `rds_iam` role while maintaining general password authentication for the same database user or role. Remember that while clients connect to RDS Proxy using IAM authentication, RDS Proxy always connects to the database using password authentication through Secrets Manager. If you experience frequent connection terminations and reconnections, remove any existing `rds_iam` grants from the user or role and use only password authentication. Ensure your password policy satisfies SCRAM-SHA-256 safe character requirements. Mixing IAM and password authentication methods for the same database user can cause connection instability. ## Considerations for connecting to Microsoft SQL Server For connecting to a proxy using IAM authentication, you don't use the password field. Instead, you provide the appropriate token property for each type of database driver in the token field. For example, use the `accessToken` property for JDBC, or the `sql_copt_ss_access_token` property for ODBC. Or use the `AccessToken` property for the .NET SqlClient driver. You can't use IAM authentication with clients that don't support token properties. Under some conditions, a proxy can't share a database connection and instead pins the connection from your client application to the proxy to a dedicated database connection. For more information about these conditions, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). ## Considerations for connecting to PostgreSQL If you create a new PostgreSQL database user for connecting to RDS Proxy, make sure that you grant the user `CONNECT` privilege on the database. Without this, the user can't establish a connection. For more information, see [Adding a new database user to a PostgreSQL database when using RDS Proxy](rds-proxy-new-db-user.md#rds-proxy-new-db-user-pg). When a client starts a connection to a PostgreSQL database, it sends a startup message. This message includes pairs of parameter name and value strings. For details, see the `StartupMessage` in [PostgreSQL message formats](https://www.postgresql.org/docs/current/protocol-message-formats.html) in the PostgreSQL documentation. When you connect through an RDS proxy, the startup message can include the following currently recognized parameters: + `user` + `database` The startup message can also include the following additional runtime parameters: + `[application\$1name](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-APPLICATION-NAME) ` + `[client\$1encoding](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-CLIENT-ENCODING) ` + `[DateStyle](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-DATESTYLE) ` + `[TimeZone](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE) ` + `[extra\$1float\$1digits](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS) ` + `[ search\$1path ](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SEARCH-PATH)` For more information about PostgreSQL messaging, see the [Frontend/Backend protocol](https://www.postgresql.org/docs/current/protocol.html) in the PostgreSQL documentation. For PostgreSQL, if you use JDBC, we recommend the following to avoid pinning: + Set the JDBC connection parameter `assumeMinServerVersion` to at least `9.0` to avoid pinning. This prevents the JDBC driver from performing an extra round trip during connection startup when it runs `SET extra_float_digits = 3`. + Set the JDBC connection parameter `ApplicationName` to `any/your-application-name` to avoid pinning. Doing this prevents the JDBC driver from performing an extra round trip during connection startup when it runs `SET application_name = "PostgreSQL JDBC Driver"`. Note the JDBC parameter is `ApplicationName` but the PostgreSQL `StartupMessage` parameter is `application_name`. For more information, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). For more information about connecting using JDBC, see [Connecting to the database](https://jdbc.postgresql.org/documentation/setup/) in the PostgreSQL documentation. # Managing an RDS Proxy This section provides information on how to manage RDS Proxy operation and configuration. These procedures help your application make the most efficient use of database connections and achieve maximum connection reuse. The more that you can take advantage of connection reuse, the more CPU and memory overhead that you can save. This in turn reduces latency for your application and enables the database to devote more of its resources to processing application requests. **Topics** + [ # Modifying an RDS Proxy ](rds-proxy-modifying-proxy.md) + [ # Adding a new database user when using RDS Proxy ](rds-proxy-new-db-user.md) + [ # Moving from standard IAM authentication to end-to-end IAM authentication for RDS Proxy ](rds-proxy-iam-migration.md) + [ # RDS Proxy connection considerations ](rds-proxy-connections.md) + [ # Avoiding pinning an RDS Proxy ](rds-proxy-pinning.md) + [ # Deleting an RDS Proxy ](rds-proxy-deleting.md) # Modifying an RDS Proxy You can change specific settings associated with a proxy after you create the proxy. You do so by modifying the proxy itself, its associated target group, or both. Each proxy has an associated target group. ## AWS Management Console **Important** The values in the **Client authentication type** and **IAM authentication** fields apply to all Secrets Manager secrets that are associated with this proxy. To specify different values for each secret, modify your proxy by using the AWS CLI or the API instead. **To modify the settings for a proxy** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. In the list of proxies, choose the proxy whose settings you want to modify or go to its details page. 1. For **Actions**, choose **Modify**. 1. Enter or choose the properties to modify. You can modify the following: + **Proxy identifier** – Rename the proxy by entering a new identifier. + **Idle client connection timeout** – Enter a time period for the idle client connection timeout. + **IAM role** – Change the IAM role used to retrieve the secrets from Secrets Manager. **Note** You can't create a new IAM role if you set **Default authentication scheme** to **IAM authentication**. + **Secrets Manager secrets** – Add or remove Secrets Manager secrets. These secrets correspond to database user names and passwords. + **Client authentication type** – Change the type of authentication for client connections to the proxy. + **IAM authentication** – Require or disallow IAM authentication for connections to the proxy. + **Default authentication scheme** – Change the default authentication scheme the proxy uses for client connections to the proxy and connections from the proxy to the underlying database. + **Require Transport Layer Security** – Turn the requirement for Transport layer Security (TLS) on or off. + **VPC security group** – Add or remove VPC security groups for the proxy to use. + **Enable enhanced logging** – Enable or disable enhanced logging. 1. Choose **Modify**. If you didn't find the settings listed that you want to change, use the following procedure to update the target group for the proxy. The *target group* associated with a proxy controls the settings related to the physical database connections. Each proxy has one associated target group named `default`, which is created automatically along with the proxy. You can't rename the default target group. You can only modify the target group from the proxy details page, not from the list on the **Proxies** page. **To modify the settings for a proxy target group** 1. On the **Proxies** page, go to the details page for a proxy. 1. For **Target groups**, choose the `default` link. Currently, all proxies have a single target group named `default`. 1. On the details page for the **default** target group, choose **Modify**. 1. Choose new settings for the properties that you can modify: + **Database** – Choose a different RDS DB instance or cluster. + **Connection pool maximum connections** – Adjust what percentage of the maximum available connections the proxy can use. + **Session pinning filters** – (Optional) Choose a session pinning filter. This circumvents the default safety measures for multiplexing database connections across client connections. Currently, the setting isn't supported for PostgreSQL. The only choice is `EXCLUDE_VARIABLE_SETS`. Enabling this setting can cause session variables of one connection to impact other connections. This can cause errors or correctness issues if your queries depend on session variable values set outside of the current transaction. Consider using this option after verifying it is safe for your applications to share database connections across client connections. The following patterns can be considered safe: + `SET` statements where there is no change to the effective session variable value, i.e., there is no change to the session variable. + You change the session variable value and execute a statement in the same transaction. For more information, see [Avoiding pinning an RDS Proxy](rds-proxy-pinning.md). + **Connection borrow timeout** – Adjust the connection borrow timeout interval. This setting applies when the maximum number of connections is already being used for the proxy. The setting determines how long the proxy waits for a connection to become available before returning a timeout error. + **Initialization query**. (Optional) Add an initialization query, or modify the current one. You can specify one or more SQL statements for the proxy to run when opening each new database connection. The setting is typically used with `SET` statements to make sure that each connection has identical settings. Make sure that the query you add is valid. To include multiple variables in a single `SET` statement, use comma separators. For example: ``` SET variable1=value1, variable2=value2 ``` For multiple statements, use semicolons as the separator. You can't change certain properties, such as the target group identifier and the database engine. 1. Choose **Modify target group**. ## AWS CLI To modify a proxy using the AWS CLI, use the commands [modify-db-proxy](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy.html), [modify-db-proxy-target-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy-target-group.html), [deregister-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/deregister-db-proxy-targets.html), and [register-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/register-db-proxy-targets.html). With the `modify-db-proxy` command, you can change properties such as the following: + The set of Secrets Manager secrets used by the proxy. + Whether TLS is required. + The idle client timeout. + Whether to log additional information from SQL statements for debugging. + The IAM role used to retrieve Secrets Manager secrets. + The security groups used by the proxy. + The default authentication scheme associated with the proxy. The following example shows how to rename an existing proxy. ``` aws rds modify-db-proxy --db-proxy-name the-proxy --new-db-proxy-name the_new_name ``` To modify connection-related settings or rename the target group, use the `modify-db-proxy-target-group` command. Currently, all proxies have a single target group named `default`. When you work with this target group, you specify the name of the proxy and `default` for the name of the target group. You can't rename the default target group. The following example shows how to first check the `MaxIdleConnectionsPercent` setting for a proxy and then change it, using the target group. ``` aws rds describe-db-proxy-target-groups --db-proxy-name the-proxy { "TargetGroups": [ { "Status": "available", "UpdatedDate": "2019-11-30T16:49:30.342Z", "ConnectionPoolConfig": { "MaxIdleConnectionsPercent": 50, "ConnectionBorrowTimeout": 120, "MaxConnectionsPercent": 100, "SessionPinningFilters": [] }, "TargetGroupName": "default", "CreatedDate": "2019-11-30T16:49:27.940Z", "DBProxyName": "the-proxy", "IsDefault": true } ] } aws rds modify-db-proxy-target-group --db-proxy-name the-proxy --target-group-name default --connection-pool-config ' { "MaxIdleConnectionsPercent": 75 }' { "DBProxyTargetGroup": { "Status": "available", "UpdatedDate": "2019-12-02T04:09:50.420Z", "ConnectionPoolConfig": { "MaxIdleConnectionsPercent": 75, "ConnectionBorrowTimeout": 120, "MaxConnectionsPercent": 100, "SessionPinningFilters": [] }, "TargetGroupName": "default", "CreatedDate": "2019-11-30T16:49:27.940Z", "DBProxyName": "the-proxy", "IsDefault": true } } ``` With the `deregister-db-proxy-targets` and `register-db-proxy-targets` commands, you change which RDS DB instances the proxy is associated with through its target group. Currently, each proxy can connect to one RDS DB instance. The target group tracks the connection details for all the RDS DB instances in a Multi-AZ configuration. The following example starts with a proxy that is associated with an Aurora MySQL cluster named `cluster-56-2020-02-25-1399`. The example shows how to change the proxy so that it can connect to a different cluster named `provisioned-cluster`. When you work with an RDS DB instance, you specify the `--db-instance-identifier` option. The following example modifies an Aurora MySQL proxy. An Aurora PostgreSQL proxy has port 5432. ``` aws rds describe-db-proxy-targets --db-proxy-name the-proxy { "Targets": [ { "Endpoint": "instance-9814.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "instance-9814" }, { "Endpoint": "instance-8898.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "instance-8898" }, { "Endpoint": "instance-1018.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "instance-1018" }, { "Type": "TRACKED_CLUSTER", "Port": 0, "RdsResourceId": "cluster-56-2020-02-25-1399" }, { "Endpoint": "instance-4330.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "instance-4330" } ] } aws rds deregister-db-proxy-targets --db-proxy-name the-proxy --db-cluster-identifier cluster-56-2020-02-25-1399 aws rds describe-db-proxy-targets --db-proxy-name the-proxy { "Targets": [] } aws rds register-db-proxy-targets --db-proxy-name the-proxy --db-cluster-identifier provisioned-cluster { "DBProxyTargets": [ { "Type": "TRACKED_CLUSTER", "Port": 0, "RdsResourceId": "provisioned-cluster" }, { "Endpoint": "gkldje.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "gkldje" }, { "Endpoint": "provisioned-1.demo.us-east-1.rds.amazonaws.com", "Type": "RDS_INSTANCE", "Port": 3306, "RdsResourceId": "provisioned-1" } ] } ``` ## RDS API To modify a proxy using the RDS API, you use the operations [ModifyDBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxy.html), [ModifyDBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxyTargetGroup.html), [DeregisterDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeregisterDBProxyTargets.html), and [RegisterDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RegisterDBProxyTargets.html) operations. With `ModifyDBProxy`, you can change properties such as the following: + The set of Secrets Manager secrets used by the proxy. + Whether TLS is required. + The idle client timeout. + Whether to log additional information from SQL statements for debugging. + The IAM role used to retrieve Secrets Manager secrets. + The security groups used by the proxy. With `ModifyDBProxyTargetGroup`, you can modify connection-related settings. Currently, all proxies have a single target group named `default`. When you work with this target group, you specify the name of the proxy and `default` for the name of the target group. You can't rename the default target group. With `DeregisterDBProxyTargets` and `RegisterDBProxyTargets`, you change which RDS DB instance the proxy is associated with through its target group. Currently, each proxy can connect to one RDS DB instance . The target group tracks the connection details for the RDS DB instances in a Multi-AZ configuration . # Adding a new database user when using RDS Proxy In some cases, you might add a new database user to an RDS DB instance or cluster that's associated with a proxy. Proceed depending on whether you're using standard authentication with Secrets Manager secrets or end-to-end IAM authentication. If you are using the standard IAM authentication, follow these instructions: 1. Create a new Secrets Manager secret, using the procedure described in [Setting up database credentials for RDS Proxy](rds-proxy-secrets-arns.md). 1. Update the IAM role to give RDS Proxy access to the new Secrets Manager secret. To do so, update the resources section of the IAM role policy. 1. Modify the RDS Proxy to add the new Secrets Manager secret under **Secrets Manager secrets**. 1. If the new user takes the place of an existing one, update the credentials stored in the proxy's Secrets Manager secret for the existing user. If you're using end-to-end IAM authentication, you need to create the database user and configure IAM permissions. To do this, run through the following steps: 1. Create a new database user in your database that matches the IAM user or role name you want to use for authentication. 1. Ensure the database user is configured with IAM authentication plugin at the database. See [Creating a database account using IAM authentication](UsingWithRDS.IAMDBAuth.DBAccounts.md). 1. Update the IAM policy to grant the `rds-db:connect` permission to the IAM user or role, as described in [Creating an IAM policy for end-to-end IAM authentication](rds-proxy-iam-setup.md#rds-proxy-iam-setup-e2e-steps). 1. Ensure your proxy is configured to use IAM authentication as the default authentication scheme. With end-to-end IAM authentication, you don't need to manage database credentials in Secrets Manager secrets, as IAM credentials are used for authentication from the client to the proxy and from the proxy to the database. ## Adding a new database user to a PostgreSQL database when using RDS Proxy When adding a new user to your PostgreSQL database, if you have run the following command: ``` REVOKE CONNECT ON DATABASE postgres FROM PUBLIC; ``` Grant the `rdsproxyadmin` user the `CONNECT` privilege so the user can monitor connections on the target database. ``` GRANT CONNECT ON DATABASE postgres TO rdsproxyadmin; ``` You can also allow other target database users to perform health checks by changing `rdsproxyadmin` to the database user in the command above. ## Changing the password for a database user when using RDS Proxy In some cases, you might change the password for a database user in an RDS DB instance that's associated with a proxy. If so, update the corresponding Secrets Manager secret with the new password. If you're using end-to-end IAM authentication, you don't need to update any passwords in Secrets Manager secrets. # Moving from standard IAM authentication to end-to-end IAM authentication for RDS Proxy If you currently use standard IAM authentication for RDS Proxy, where clients authenticate to the proxy using IAM but the proxy connects to the database using secrets, you can migrate to end-to-end IAM authentication where both client-to-proxy and proxy-to-database connections use IAM authentication. **To move to end-to-end IAM authentication** 1. **Update RDS Proxy IAM role permissions** Create an updated proxy permission policy that includes both Secrets Manager and `rds:db-connect` permissions: ``` # Create updated proxy permission policy cat > updated-proxy-policy.json ≪ EOF ``` ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "GetSecretsValue", "Action": [ "secretsmanager:GetSecretValue" ], "Effect": "Allow", "Resource": [ "arn:aws:secretsmanager:us-east-1:123456789012:secret:secretName-1234f" ] }, { "Sid": "RdsDBConnect", "Action": [ "rds-db:connect" ], "Effect": "Allow", "Resource": [ "arn:aws:rds-db:us-east-1:123456789012:dbuser:cluster-ABCDEFGHIJKL01234/jane_doe" ] } ] } ``` Update proxy your role policy: ``` aws iam put-role-policy \ --role-name RDSProxyRole \ --policy-name UpdatedProxyPermissions \ --policy-document file://updated-proxy-policy.json ``` 1. Modify your RDS Proxy to enable end-to-end IAM authentication ``` aws rds modify-db-proxy \ --db-proxy-name my-database-proxy \ --default-auth-scheme IAM_AUTH \ --region us-east-1 ``` Verify that RDS Proxy status is **Available** and `DefaultAuthScheme` is `IAM_AUTH` before proceeding to ensure zero downtime during migration. ``` aws rds describe-db-proxies --db-proxy-name my-database-proxy --region us-east-1 ``` Expected output: ``` { "DBProxies": [ { "DBProxyName": "my-database-proxy", "DBProxyArn": "arn:aws:rds:us-east-1:123456789012:db-proxy:prx-0123456789abcdef", "Status": "available", ... "DefaultAuthScheme": "IAM_AUTH" } ] } ``` 1. Enable IAM authentication on database ``` aws rds modify-db-cluster \ --db-cluster-identifier my-database-cluster \ --enable-iam-database-authentication \ --region us-east-1 ``` 1. Configure database user for IAM authentication For RDS for PostgreSQL: ``` GRANT rds_iam TO jane_doe; ``` For RDS for MySQL and RDS for MariaDB: ``` ALTER USER 'jane_doe' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS'; ALTER USER 'jane_doe'@'%' REQUIRE SSL; ``` 1. Your client application code doesn't need to change. The connection process remains the same: For RDS for PostgreSQL: ``` # Generate authentication token export PGPASSWORD=$(aws rds generate-db-auth-token \ --hostname my-database-proxy.proxy-ABCDEFGHIJKL01234.us-east-1.rds.amazonaws.com \ --port 5432 \ --username jane_doe \ --region us-east-1) # Connect to database through proxy psql "host=my-database-proxy.proxy-ABCDEFGHIJKL01234.us-east-1.rds.amazonaws.com port=5432 user=jane_doe dbname=postgres password=$PGPASSWORD sslmode=require sslrootcert=us-east-1-bundle.pem" ``` For RDS for MySQL and RDS for MariaDB: ``` # Generate authentication token export MYSQL_PWD=$(aws rds generate-db-auth-token \ --hostname my-database-proxy.proxy-ABCDEFGHIJKL01234.us-east-1.rds.amazonaws.com \ --port 3306 \ --username jane_doe \ --region us-east-1) # Connect to database through proxy mysql -h my-database-proxy.proxy-ABCDEFGHIJKL01234.us-east-1.rds.amazonaws.com \ -P 3306 \ -u jane_doe \ --ssl-ca=us-east-1-bundle.pem \ --enable-cleartext-plugin ``` # RDS Proxy connection considerations ## Configuring connection settings To adjust RDS Proxy's connection pooling, you can modify the following settings: + [IdleClientTimeout](#rds-proxy-connection-pooling-tuning.idleclienttimeout) + [MaxConnectionsPercent](#rds-proxy-connection-pooling-tuning.maxconnectionspercent) + [MaxIdleConnectionsPercent](#rds-proxy-connection-pooling-tuning.maxidleconnectionspercent) + [ConnectionBorrowTimeout](#rds-proxy-connection-pooling-tuning.connectionborrowtimeout) ### IdleClientTimeout You can specify how long a client connection can be idle before the proxy closes it. The default is 1,800 seconds (30 minutes). A client connection is considered *idle* when the application doesn't submit a new request within the specified time after the previous request completed. The underlying database connection stays open and is returned to the connection pool. Thus, it's available to be reused for new client connections. If you want the proxy to proactively remove stale connections, then lowering the idle client connection timeout. If your workload establishes frequent connections with the proxy, then raise the idle client connection timeout to save the cost of establishing connections. This setting is represented by the **Idle client connection timeout** field in the RDS console and the `IdleClientTimeout` setting in the AWS CLI and the API. To learn how to change the value of the **Idle client connection timeout** field in the RDS console, see [AWS Management Console](rds-proxy-modifying-proxy.md#rds-proxy-modifying-proxy.console). To learn how to change the value of the `IdleClientTimeout` setting, see the CLI command [modify-db-proxy](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy.html) or the API operation [ModifyDBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxy.html). ### MaxConnectionsPercent You can limit the number of connections that an RDS Proxy can establish with the target database. You specify the limit as a percentage of the maximum connections available for your database. This setting is represented by the **Connection pool maximum connections** field in the RDS console and the `MaxConnectionsPercent` setting in the AWS CLI and the API. The `MaxConnectionsPercent` value is expressed as a percentage of the `max_connections` setting for the RDS DB instance used by the target group. The proxy doesn't create all of these connections in advance. This setting allows the proxy to establish these connections as the workload needs them. For example, for a registered database target with `max_connections` set to 1000, and `MaxConnectionsPercent` set to 95, RDS Proxy sets 950 connections as the upper limit for concurrent connections to that database target. A common side-effect of your workload reaching the maximum number of allowed database connections is an increase in overall query latency, along with an increase in the `DatabaseConnectionsBorrowLatency` metric. You can monitor currently used and total allowed database connections by comparing the `DatabaseConnections` and `MaxDatabaseConnectionsAllowed` metrics. When setting this parameter, note the following best practices: + Allow sufficient connection headroom for changes in workload pattern. It is recommended to set the parameter at least 30% above your maximum recent monitored usage. As RDS Proxy redistributes database connection quotas across multiple nodes, internal capacity changes might require at least 30% headroom for additional connections to avoid increased borrow latencies. + RDS Proxy reserves a certain number of connections for active monitoring to support fast failover, traffic routing and internal operations. The `MaxDatabaseConnectionsAllowed` metric does not include these reserved connections. It represents the number of connections available to serve the workload, and can be lower than the value derived from the `MaxConnectionsPercent` setting. Minimal recommended `MaxConnectionsPercent` values + db.t3.small: 30 + db.t3.medium or above: 20 To learn how to change the value of the **Connection pool maximum connections** field in the RDS console, see [AWS Management Console](rds-proxy-modifying-proxy.md#rds-proxy-modifying-proxy.console). To learn how to change the value of the `MaxConnectionsPercent` setting, see the CLI command [modify-db-proxy-target-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy-target-group.html) or the API operation [ModifyDBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxyTargetGroup.html). For information on database connection limits, see [Maximum number of database connections](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Limits.html#RDS_Limits.MaxConnections). ### MaxIdleConnectionsPercent You can control the number of idle database connections that RDS Proxy can keep in the connection pool. By default, RDS Proxy considers a database connection in its pool to be *idle* when there's been no activity on the connection for five minutes. The `MaxIdleConnectionsPercent` value is expressed as a percentage of the `max_connections` setting for the RDS DB instance target group. The default value is 50 percent of `MaxConnectionsPercent`, and the upper limit is the value of `MaxConnectionsPercent`. For example, if `MaxConnectionsPercent`, is 80, then the default value of `MaxIdleConnectionsPercent` is 40. If the value of `MaxConnectionsPercent` isn’t specified, then for RDS for SQL Server, `MaxIdleConnectionsPercent` is 5, and for all other engines, the default is 50. With a high value, the proxy leaves a high percentage of idle database connections open. With a low value, the proxy closes a high percentage of idle database connections. If your workloads are unpredictable, consider setting a high value for `MaxIdleConnectionsPercent`. Doing so means that RDS Proxy can accommodate surges in activity without opening a lot of new database connections. This setting is represented by the `MaxIdleConnectionsPercent` setting of `DBProxyTargetGroup` in the AWS CLI and the API. To learn how to change the value of the `MaxIdleConnectionsPercent` setting, see the CLI command [modify-db-proxy-target-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy-target-group.html) or the API operation [ModifyDBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxyTargetGroup.html). For information on database connection limits, see [Maximum number of database connections](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Limits.html#RDS_Limits.MaxConnections). ### ConnectionBorrowTimeout You can choose how long RDS Proxy waits for a database connection in the connection pool to become available for use before returning a timeout error. The default is 120 seconds. This setting applies when the number of connections is at the maximum, and so no connections are available in the connection pool. It also applies when no appropriate database instance is available to handle the request, such as when a failover operation is in process. Using this setting, you can set the best wait period for your application without changing the query timeout in your application code. This setting is represented by the **Connection borrow timeout** field in the RDS console or the `ConnectionBorrowTimeout` setting of `DBProxyTargetGroup` in the AWS CLI or API. To learn how to change the value of the **Connection borrow timeout** field in the RDS console, see [AWS Management Console](rds-proxy-modifying-proxy.md#rds-proxy-modifying-proxy.console). To learn how to change the value of the `ConnectionBorrowTimeout` setting, see the CLI command [modify-db-proxy-target-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy-target-group.html) or the API operation [ModifyDBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxyTargetGroup.html). ## Client and database connections Connections from your application to RDS Proxy are known as client connections. Connections from a proxy to the database are database connections. When using RDS Proxy, client connections terminate at the proxy while database connections are managed within RDS Proxy. Application-side connection pooling can provide the benefit of reducing recurring connection establishment between your application and RDS Proxy. Consider the following configuration aspects before implementing an application-side connection pool: + Client connection max life: RDS Proxy enforces a maximum life of client connections of 24 hours. This value is not configurable. Configure your pool with a maximum connection life less than 24 hours to avoid unexpected client connection drops. + Client connection idle timeout: RDS Proxy enforces a maximum idle time for client connections. Configure your pool with an idle connection timeout of a value lower than your client connection idle timeout setting for RDS Proxy to avoid unexpected connection drops. The maximum number of client connections configured in your application-side connection pool does not have to be limited to the **max\$1connections** setting for RDS Proxy. Client connection pooling results in a longer client connection life. If your connections experience pinning, then pooling client connections might reduce multiplexing efficiency. Client connections that are pinned but idle in the application-side connection pool continue to hold on to a database connection and prevent the database connection to be reused by other client connections. Review your proxy logs to check whether your connections experience pinning. **Note** RDS Proxy closes database connections some time after 24 hours when they are no longer in use. The proxy performs this action regardless of the value of the maximum idle connections setting. # Avoiding pinning an RDS Proxy Multiplexing is more efficient when database requests don't rely on state information from previous requests. In that case, RDS Proxy can reuse a connection at the conclusion of each transaction. Examples of such state information include most variables and configuration parameters that you can change through `SET` or `SELECT` statements. SQL transactions on a client connection can multiplex between underlying database connections by default. Your connections to the proxy can enter a state known as *pinning*. When a connection is pinned, each later transaction uses the same underlying database connection until the session ends. Other client connections also can't reuse that database connection until the session ends. The session ends when the client connection is dropped. RDS Proxy automatically pins a client connection to a specific DB connection when it detects a session state change that isn't appropriate for other sessions. Pinning reduces the effectiveness of connection reuse. If all or almost all of your connections experience pinning, consider modifying your application code or workload to reduce the conditions that cause the pinning. For example, your application changes a session variable or configuration parameter. In this case, later statements can rely on the new variable or parameter to be in effect. Thus, when RDS Proxy processes requests to change session variables or configuration settings, it pins that session to the DB connection. That way, the session state remains in effect for all later transactions in the same session. For some database engines, this rule doesn't apply to all parameters that you can set. RDS Proxy tracks certain statements and variables. Thus, RDS Proxy doesn't pin the session when you modify them. In this case, RDS Proxy only reuses the connection for other sessions that have the same values for those settings. For details about what RDS Proxy tracks for a database engine, see the following: + [What RDS Proxy tracks for RDS for SQL Server databases](#rds-proxy-pinning.sql-server-tracked-vars) + [What RDS Proxy tracks for RDS for MariaDB and RDS for MySQL databases](#rds-proxy-pinning.mysql-tracked-vars) ## What RDS Proxy tracks for RDS for SQL Server databases RDS Proxy tracks the following SQL Server statements: + `USE` + `SET ANSI_NULLS` + `SET ANSI_PADDING` + `SET ANSI_WARNINGS` + `SET ARITHABORT` + `SET CONCAT_NULL_YIELDS_NULL` + `SET CURSOR_CLOSE_ON_COMMIT` + `SET DATEFIRST` + `SET DATEFORMAT` + `SET LANGUAGE` + `SET LOCK_TIMEOUT` + `SET NUMERIC_ROUNDABORT` + `SET QUOTED_IDENTIFIER` + `SET TEXTSIZE` + `SET TRANSACTION ISOLATION LEVEL` ## What RDS Proxy tracks for RDS for MariaDB and RDS for MySQL databases RDS Proxy tracks the following MariaDB and MySQL statements: + DROP DATABASE + DROP SCHEMA + USE RDS Proxy tracks the following MySQL and MariaDB variables: + `AUTOCOMMIT` + `AUTO_INCREMENT_INCREMENT` + `CHARACTER SET (or CHAR SET)` + `CHARACTER_SET_CLIENT` + `CHARACTER_SET_DATABASE` + `CHARACTER_SET_FILESYSTEM` + `CHARACTER_SET_CONNECTION` + `CHARACTER_SET_RESULTS` + `CHARACTER_SET_SERVER` + `COLLATION_CONNECTION` + `COLLATION_DATABASE` + `COLLATION_SERVER` + `INTERACTIVE_TIMEOUT` + `NAMES` + `NET_WRITE_TIMEOUT` + `QUERY_CACHE_TYPE` + `SESSION_TRACK_SCHEMA` + `SQL_MODE` + `TIME_ZONE` + `TRANSACTION_ISOLATION (or TX_ISOLATION)` + `TRANSACTION_READ_ONLY (or TX_READ_ONLY)` + `WAIT_TIMEOUT` **Note** RDS Proxy tracks changes to the `TRANSACTION_ISOLATION` and `TRANSACTION_READ_ONLY` variables when you set them at the session scope. However, if you set them at the next transaction scope, RDS Proxy pins connections. This behavior applies whether you use a `SET` statement or a `SET TRANSACTION` statement to configure these values. ## Minimizing pinning Performance tuning for RDS Proxy involves trying to maximize transaction-level connection reuse (multiplexing) by minimizing pinning. You can minimize pinning by doing the following: + Avoid unnecessary database requests that might cause pinning. + Set variables and configuration settings consistently across all connections. That way, later sessions are more likely to reuse connections that have those particular settings. However, for PostgreSQL setting a variable leads to session pinning. + For a MySQL engine family database, apply a session pinning filter to the proxy. You can exempt certain kinds of operations from pinning the session if you know that doing so doesn't affect the correct operation of your application. + See how frequently pinning occurs by monitoring the Amazon CloudWatch metric `DatabaseConnectionsCurrentlySessionPinned`. For information about this and other CloudWatch metrics, see [Monitoring RDS Proxy metrics with Amazon CloudWatchMonitoring RDS Proxy with CloudWatch](rds-proxy.monitoring.md). + If you use `SET` statements to perform identical initialization for each client connection, you can do so while preserving transaction-level multiplexing. In this case, you move the statements that set up the initial session state into the initialization query used by a proxy. This property is a string containing one or more SQL statements, separated by semicolons. For example, you can define an initialization query for a proxy that sets certain configuration parameters. Then, RDS Proxy applies those settings whenever it sets up a new connection for that proxy. You can remove the corresponding `SET` statements from your application code, so that they don't interfere with transaction-level multiplexing. For metrics about how often pinning occurs for a proxy, see [Monitoring RDS Proxy metrics with Amazon CloudWatchMonitoring RDS Proxy with CloudWatch](rds-proxy.monitoring.md). ## Conditions that cause pinning for all engine families The proxy pins the session to the current connection in the following situations where multiplexing might cause unexpected behavior: + Any statement with a text size greater than 16 KB causes the proxy to pin the session. ## Conditions that cause pinning for RDS for Microsoft SQL Server For RDS for SQL Server, the following interactions also cause pinning: + Using multiple active result sets (MARS). For information about MARS, see the [SQL Server](https://docs.microsoft.com/en-us/sql/relational-databases/native-client/features/using-multiple-active-result-sets-mars?view=sql-server-ver16) documentation. + Using distributed transaction coordinator (DTC) communication. + Creating temporary tables, transactions, cursors, or prepared statements. + Using the following `SET` statements: + `SET ANSI_DEFAULTS` + `SET ANSI_NULL_DFLT` + `SET ARITHIGNORE` + `SET DEADLOCK_PRIORITY` + `SET FIPS_FLAGGER` + `SET FMTONLY` + `SET FORCEPLAN` + `SET IDENTITY_INSERT` + `SET NOCOUNT` + `SET NOEXEC` + `SET OFFSETS` + `SET PARSEONLY` + `SET QUERY_GOVERNOR_COST_LIMIT` + `SET REMOTE_PROC_TRANSACTIONS` + `SET ROWCOUNT` + `SET SHOWPLAN_ALL`, `SHOWPLAN_TEXT`, and `SHOWPLAN_XML` + `SET STATISTICS` + `SET XACT_ABORT` ## Conditions that cause pinning for RDS for MariaDB and RDS for MySQL For MariaDB and MySQL, the following interactions also cause pinning: + Explicit table lock statements `LOCK TABLE`, `LOCK TABLES`, or `FLUSH TABLES WITH READ LOCK` cause the proxy to pin the session. + Creating named locks by using `GET_LOCK` causes the proxy to pin the session. + Setting a user or system variable (with some exceptions) pins the session to the proxy. If this significantly limits connection reuse, you can configure `SET` operations to avoid pinning. To do this, adjust the session pinning filters property. For more information, see [Creating a proxy for Amazon RDS](rds-proxy-creating.md) and [Modifying an RDS Proxy](rds-proxy-modifying-proxy.md). + Creating a temporary table causes the proxy to pin the session. That way, the contents of the temporary table are preserved throughout the session regardless of transaction boundaries. + Calling the `ROW_COUNT` and `FOUND_ROWS` functions sometimes causes pinning. + Prepared statements cause the proxy to pin the session. This rule applies whether the prepared statement uses SQL text or the binary protocol. + RDS Proxy does not pin connections when you use SET LOCAL. + Calling stored procedures and stored functions doesn't cause pinning. RDS Proxy doesn't detect any session state changes resulting from such calls. Make sure that your application doesn't change session state inside stored routines if you rely on that session state to persist across transactions. For example, RDS Proxy isn't currently compatible with a stored procedure that creates a temporary table that persists across all transactions. + Queries with executable comments for MySQL (syntax /\$1\$1 ... \$1/) or MariaDB (syntax /\$1M\$1 ... \$1/) cause pinning. RDS Proxy cannot parse SQL embedded in these comments to track session state changes. If you have expert knowledge about your application behavior, you can skip the pinning behavior for certain application statements. To do so, choose the **Session pinning filters** option when creating the proxy. Currently, you can opt out of session pinning for setting session variables and configuration settings. ## Conditions that cause pinning for RDS for PostgreSQL For PostgreSQL, the following interactions also cause pinning: + Using `SET` commands. + Using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE` commands to manage prepared statements. + Creating temporary sequences, tables, or views. + Declaring cursors. + Discarding the session state. + Listening on a notification channel. + Loading a library module such as `auto_explain`. + Manipulating sequences using functions such as `nextval` and `setval`. + Interacting with locks using functions such as `pg_advisory_lock` and `pg_try_advisory_lock`. **Note** RDS Proxy does not pin on transaction level advisory locks, specifically `pg_advisory_xact_lock`, `pg_advisory_xact_lock_shared`, `pg_try_advisory_xact_lock`, and `pg_try_advisory_xact_lock_shared`. + Setting a parameter, or resetting a parameter to its default. Specifically, using `SET` and `set_config` commands to assign default values to session variables. + Calling stored procedures and stored functions doesn't cause pinning. RDS Proxy doesn't detect any session state changes resulting from such calls. Make sure that your application doesn't change session state inside stored routines if you rely on that session state to persist across transactions. For example, RDS Proxy isn't currently compatible with a stored procedure that creates a temporary table that persists across all transactions. + Discarding session state. If you use connection pooling libraries with `DISCARD ALL` query configured as a reset query, RDS Proxy pins your client connection on release. This reduces the proxy's multiplexing efficiency and might lead to unexpected results because the `DISCARD ALL` command can interfere with session state management. # Deleting an RDS Proxy You can delete a proxy when you no longer need it. Or, you might delete a proxy if you take the DB instance or cluster associated with it out of service. ## AWS Management Console **To delete a proxy** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. Choose the proxy to delete from the list. 1. Choose **Delete Proxy**. ## AWS CLI To delete a DB proxy, use the AWS CLI command [delete-db-proxy](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-db-proxy.html). To remove related associations, also use the [deregister-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/deregister-db-proxy-targets.html) command. ``` aws rds delete-db-proxy --name proxy_name ``` ``` aws rds deregister-db-proxy-targets --db-proxy-name proxy_name [--target-group-name target_group_name] [--target-ids comma_separated_list] # or [--db-instance-identifiers instance_id] # or [--db-cluster-identifiers cluster_id] ``` ## RDS API To delete a DB proxy, call the Amazon RDS API function [DeleteDBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteDBProxy.html). To delete related items and associations, you also call the functions [DeleteDBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteDBProxyTargetGroup.html) and [DeregisterDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeregisterDBProxyTargets.html). # Working with Amazon RDS Proxy endpoints RDS Proxy endpoints provide flexible and efficient ways to manage database connections, which improves scalability, availability, and security. With proxy endpoints, you can: + **Simplify monitoring and troubleshooting** – Use multiple endpoints to track and manage connections from different applications independently. **Topics** + [ ## Overview of proxy endpoints ](#rds-proxy-endpoints-overview) + [ ## Limitations for proxy endpoints ](#rds-proxy-endpoints-limits) + [ ## Proxy endpoints for Multi-AZ DB clusters ](#rds-proxy-endpoints-overview-maz) + [ ## Accessing RDS databases across VPCs ](#rds-proxy-cross-vpc) + [ # Creating a proxy endpoint ](rds-proxy-endpoints.CreatingEndpoint.md) + [ # Viewing proxy endpoints ](rds-proxy-endpoints.DescribingEndpoint.md) + [ # Modifying a proxy endpoint ](rds-proxy-endpoints.ModifyingEndpoint.md) + [ # Deleting a proxy endpoint ](rds-proxy-endpoints.DeletingEndpoint.md) ## 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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToInstance.html) and [Connecting to a DB instance running the PostgreSQL database engine](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html). When you create a proxy endpoint, you can associate it with a different virtual private cloud (VPC) than the proxy’s VPC. This allows you to connect to the proxy from another VPC, such as one used by a different application within your organization. For information about limits associated with proxy endpoints, see [Limitations for proxy endpoints](#rds-proxy-endpoints-limits). RDS Proxy logs prefix each entry with the name of the associated proxy endpoint. This can be either the name that you specified for a user-defined endpoint, or the special name `default` for the proxy’s default read/write endpoint. Each proxy endpoint has its own set of CloudWatch metrics. Monitor metrics for all proxy endpoints, a specific endpoint, or all read/write or read-only endpoints of a proxy. For more information, see [Monitoring RDS Proxy metrics with Amazon CloudWatchMonitoring RDS Proxy with CloudWatch](rds-proxy.monitoring.md). 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. ## Limitations for proxy endpoints RDS Proxy endpoints have the following limitations: + The RDS proxy default endpoint cannot be modified. + 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. + For IPv6 or dual-stack endpoint network types, your VPC and subnets must be configured to support the selected network type. When you create a proxy, RDS automatically creates a VPC endpoint for secure communication between applications and the database. The VPC endpoint is visible and can be accessed from the Amazon VPC Console. Adding a new proxy endpoint provisions an AWS PrivateLink interface endpoint. If you add one or more endpoints to your proxy, you incure additional charges. For more information, see [RDS Proxy Pricing](https://aws.amazon.com/rds/proxy/pricing/). ## Proxy endpoints for Multi-AZ DB clusters 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](rds-proxy.howitworks.md#rds-proxy-overview). ## 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](CHAP_GettingStarted.md) 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. 1. Create a DB proxy associated with the Amazon RDS DB instance that you want to connect to. Follow the procedure in [Creating a proxy for Amazon RDS](rds-proxy-creating.md). 1. 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](rds-proxy-endpoints.CreatingEndpoint.md). 1. Choose whether to make the cross-VPC endpoint read/write or read-only. 1. 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 AWS Region as the VPC where the proxy resides. 1. 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. 1. 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. Similarly, when using IAM authentication, your IAM configuration and permissions work consistently across all proxy endpoints, even when endpoints are in different VPCs. No additional IAM configuration is required per endpoint. 1. Wait for the new endpoint to reach the **Available** state. 1. 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. 1. 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, follow these instructions: ## Console **To create a proxy endpoint** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. Click the name of the proxy that you want to create a new endpoint for. The details page for that proxy appears. 1. In the **Proxy endpoints** section, choose **Create proxy endpoint**. The **Create proxy endpoint** window appears. 1. For **Proxy endpoint name**, enter a descriptive name of your choice. 1. 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. 1. 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](rds-proxy-endpoints.md#rds-proxy-cross-vpc). 1. For **Endpoint network type**, choose the IP version for the proxy endpoint. The available options are: + **IPv4** – The proxy endpoint uses IPv4 addresses only (default). + **IPv6** – The proxy endpoint uses IPv6 addresses only. + **Dual-stack** – The proxy endpoint supports both IPv4 and IPv6 addresses. To use IPv6 or dual-stack, your VPC and subnets must be configured to support the selected network type. 1. 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. 1. 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. 1. Choose **Create proxy endpoint**. ## AWS CLI To create a proxy endpoint, use the AWS CLI [create-db-proxy-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-proxy-endpoint.html) 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](rds-proxy-endpoints.md#rds-proxy-endpoints-reader-stub). + `--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. + `--endpoint-network-type { IPV4 | IPV6 | DUAL }`. This parameter specifies the IP version for the proxy endpoint. The default is `IPV4`. To use `IPV6` or `DUAL`, your VPC and subnets must be configured to support the selected network type. **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 \ --endpoint-network-type DUAL ``` 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 ^ --endpoint-network-type DUAL ``` ## RDS API To create a proxy endpoint, use the RDS API [CreateDBProxyEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBProxyEndpoint.html) action. # Viewing proxy endpoints To view existing proxy endpoints, follow these instructions: ## Console **To view the details for a proxy endpoint** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. In the list, choose the proxy whose endpoint you want to view. Click the proxy name to view its details page. 1. In the **Proxy endpoints** section, choose the endpoint that you want to view. Click its name to view the details page. 1. 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. ## AWS CLI To view one or more proxy endpoints, use the AWS CLI [describe-db-proxy-endpoints](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-endpoints.html) 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 ``` ## RDS API To describe one or more proxy endpoints, use the RDS API [DescribeDBProxyEndpoints](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxyEndpoints.html) operation. # Modifying a proxy endpoint To modify your proxy endpoints, follow these instructions: ## Console **To modify one or more proxy endpoints** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Proxies**. 1. In the list, choose the proxy whose endpoint you want to modify. Click the proxy name to view its details page. 1. 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. 1. On the proxy details page, under the **Proxy endpoints** section, choose **Edit**. Or, on the proxy endpoint details page, for **Actions**, choose **Edit**. 1. Change the values of the parameters that you want to modify. 1. Choose **Save changes**. ## AWS CLI To modify a proxy endpoint, use the AWS CLI [modify-db-proxy-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-proxy-endpoint.html) 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 ``` ## RDS API To modify a proxy endpoint, use the RDS API [ModifyDBProxyEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBProxyEndpoint.html) operation. # Deleting a proxy endpoint To delete an endpoint for your proxy, follow these instructions: **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. ## Console **To delete a proxy endpoint using the AWS Management Console** 1. In the navigation pane, choose **Proxies**. 1. In the list, choose the proxy whose endpoint you want to endpoint. Click the proxy name to view its details page. 1. 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. 1. On the proxy details page, under the **Proxy endpoints** section, choose **Delete**. Or, on the proxy endpoint details page, for **Actions**, choose **Delete**. ## AWS CLI To delete a proxy endpoint, run the [delete-db-proxy-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-db-proxy-endpoint.html) 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 ``` ## RDS API To delete a proxy endpoint with the RDS API, run the [DeleteDBProxyEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DeleteDBProxyEndpoint.html) operation. Specify the name of the proxy endpoint for the `DBProxyEndpointName` parameter. # Monitoring RDS Proxy metrics with Amazon CloudWatch You can monitor RDS Proxy by using Amazon CloudWatch. CloudWatch collects and processes raw data from the proxies into readable, near-real-time metrics. To find these metrics in the CloudWatch console, choose **Metrics**, then choose **RDS**, and choose **Per-Proxy Metrics**. For more information, see [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) in the Amazon CloudWatch User Guide. **Note** RDS publishes these metrics for each underlying Amazon EC2 instance associated with a proxy. A single proxy might be served by more than one EC2 instance. Use CloudWatch statistics to aggregate the values for a proxy across all the associated instances. Some of these metrics might not be visible until after the first successful connection by a proxy. 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 the special name `default` for the default endpoint of a proxy that performs read/write requests. All RDS Proxy metrics are in the group `proxy`. Each proxy endpoint has its own CloudWatch metrics. You can monitor the usage of each proxy endpoint independently. For more information about proxy endpoints, see [Working with Amazon RDS Proxy endpoints](rds-proxy-endpoints.md). You can aggregate the values for each metric using one of the following dimension sets. For example, by using the `ProxyName` dimension set, you can analyze all the traffic for a particular proxy. By using the other dimension sets, you can split the metrics in different ways. You can split the metrics based on the different endpoints or target databases of each proxy, or the read/write and read-only traffic to each database. + Dimension set 1: `ProxyName` + Dimension set 2: `ProxyName`, `EndpointName` + Dimension set 3: `ProxyName`, `TargetGroup`, `Target` + Dimension set 4: `ProxyName`, `TargetGroup`, `TargetRole` | Metric | Description | Valid period | CloudWatch dimension set | | --- | --- | --- | --- | | `AvailabilityPercentage` | The percentage of time for which the target group was available in the role indicated by the dimension. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 4](#proxy-dimension-set-4) | | ClientConnections | The current number of client connections. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | ClientConnectionsClosed | The number of client connections closed. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | ClientConnectionsInSetup | The current number of client connections open but have not completed setup. This metric is reported every minute. The most useful statistic for this metric is Sum. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | `ClientConnectionsNoTLS` | The current number of client connections without Transport Layer Security (TLS). This metric is reported every minute. The most useful statistic for this metric is Sum. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | `ClientConnectionsReceived` | The number of client connection requests received. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | ClientConnectionsSetupFailedAuth | The number of client connection attempts that failed due to misconfigured authentication or TLS. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | ClientConnectionsSetupSucceeded | The number of client connections successfully established with any authentication mechanism with or without TLS. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | ClientConnectionsTLS | The current number of client connections with TLS. This metric is reported every minute. The most useful statistic for this metric is Sum. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | DatabaseConnectionRequests | The number of requests to create a database connection. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | `DatabaseConnectionRequestsWithTLS` | The number of requests to create a database connection with TLS. The most useful statistic for this metric is Sum. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | DatabaseConnections | The current number of database connections. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | `DatabaseConnectionsBorrowLatency` | The time in microseconds that it takes for the proxy being monitored to get a database connection. The most useful statistic for this metric is Sum. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | DatabaseConnectionsCurrentlyBorrowed | The current number of database connections in the borrow state. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | DatabaseConnectionsCurrentlyInTransaction | The current number of database connections in a transaction. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | DatabaseConnectionsCurrentlySessionPinned | The current number of database connections currently pinned because of operations in client requests that change session state. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | DatabaseConnectionsSetupFailed | The number of database connection requests that failed. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | DatabaseConnectionsSetupSucceeded | The number of database connections successfully established with or without TLS. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | `DatabaseConnectionsWithTLS` | The current number of database connections with TLS. This metric is reported every minute. The most useful statistic for this metric is Sum. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | MaxDatabaseConnectionsAllowed | The maximum number of database connections allowed. This metric is reported every minute. The most useful statistic for this metric is `Sum`. | 1 minute | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | `QueryDatabaseResponseLatency` | The time in microseconds that the database took to respond to the query. The most useful statistic for this metric is Average. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2), [Dimension set 3](#proxy-dimension-set-3), [Dimension set 4](#proxy-dimension-set-4) | | QueryRequests | The number of queries received. A query including multiple statements is counted as one query. The most useful statistic for this metric is `Sum`. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | QueryRequestsNoTLS | The number of queries received from non-TLS connections. A query including multiple statements is counted as one query. The most useful statistic for this metric is Sum. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | `QueryRequestsTLS` | The number of queries received from TLS connections. A query including multiple statements is counted as one query. The most useful statistic for this metric is Sum. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | | QueryResponseLatency | The time in microseconds between getting a query request and the proxy responding to it. The most useful statistic for this metric is Average. | 1 minute and above | [Dimension set 1](#proxy-dimension-set-1), [Dimension set 2](#proxy-dimension-set-2) | You can find logs of RDS Proxy activity under CloudWatch in the AWS Management Console. Each proxy has an entry in the **Log groups** page. **Important** These logs are intended for human consumption for troubleshooting purposes and not for programmatic access. The format and content of the logs is subject to change. In particular, older logs don't contain any prefixes indicating the endpoint for each request. In newer logs, each entry is prefixed with the name of the associated proxy endpoint. This name can be the name that you specified for a user-defined endpoint, or the special name `default` for requests using the default endpoint of a proxy. # Working with RDS Proxy events An *event* indicates a change in an environment such as an AWS environment or a service or application from a software as a service (SaaS) partner. Or, it can be one of your own custom applications or services. For example, Amazon RDS generates an event when you create or modify an RDS Proxy. Amazon RDS delivers events to Amazon EventBridge in near-real time. Following, you can find a list of RDS Proxy events that you can subscribe to and an example of an RDS Proxy event. For more information about working with events, see the following: + For instructions on how to view events by using the AWS Management Console, AWS CLI, or RDS API, see [Viewing Amazon RDS events](USER_ListEvents.md). + To learn how to configure Amazon RDS to send events to EventBridge, see [Creating a rule that triggers on an Amazon RDS event](rds-cloud-watch-events.md). ## RDS Proxy events The following table shows the event category and a list of events when an RDS Proxy is the source type. | Category | RDS event ID | Message | Notes | | --- | --- | --- | --- | | configuration change | RDS-EVENT-0204 | RDS modified DB proxy *name*. | None | | configuration change | RDS-EVENT-0207 | RDS modified the end point of the DB proxy *name*. | None | | configuration change | RDS-EVENT-0213 | RDS detected the addition of the DB instance and automatically added it to the target group of the DB proxy *name*. | None | | configuration change | RDS-EVENT-0214 | RDS detected deletion of DB instance *name* and automatically removed it from target group *name* of DB proxy *name*. | None | | configuration change | RDS-EVENT-0215 | RDS detected deletion of DB cluster *name* and automatically removed it from target group *name* of DB proxy *name*. | None | | creation | RDS-EVENT-0203 | RDS created DB proxy *name*. | None | | creation | RDS-EVENT-0206 | RDS created endpoint *name* for DB proxy *name*. | None | | deletion | RDS-EVENT-0205 | RDS deleted DB proxy *name*. | None | | deletion | RDS-EVENT-0208 | RDS deleted endpoint *name* for DB proxy *name*. | None | | failure | RDS-EVENT-0243 | RDS failed to provision capacity for proxy *name* because there aren't enough IP addresses available in your subnets: *name*. To fix the issue, make sure that your subnets have the minimum number of unused IP addresses as recommended in the RDS Proxy documentation. | To determine the recommended number for your instance class, see [Planning for IP address capacity](rds-proxy-network-prereqs.md#rds-proxy-network-prereqs.plan-ip-address). | | failure | RDS-EVENT-0275 | RDS throttled some connections to DB proxy *name*. The number of simultaneous connection requests from the client to the proxy has exceeded the limit. | None | The following is an example of an RDS Proxy event in JSON format. The event shows that RDS modified the endpoint named `my-endpoint` of the RDS Proxy named `my-rds-proxy`. The event ID is RDS-EVENT-0207. ``` { "version": "0", "id": "68f6e973-1a0c-d37b-f2f2-94a7f62ffd4e", "detail-type": "RDS DB Proxy Event", "source": "aws.rds", "account": "123456789012", "time": "2018-09-27T22:36:43Z", "region": "us-east-1", "resources": [ "arn:aws:rds:us-east-1:123456789012:db-proxy:my-rds-proxy" ], "detail": { "EventCategories": [ "configuration change" ], "SourceType": "DB_PROXY", "SourceArn": "arn:aws:rds:us-east-1:123456789012:db-proxy:my-rds-proxy", "Date": "2018-09-27T22:36:43.292Z", "Message": "RDS modified endpoint my-endpoint of DB Proxy my-rds-proxy.", "SourceIdentifier": "my-endpoint", "EventID": "RDS-EVENT-0207" } } ``` # Troubleshooting for RDS Proxy Following, you can find troubleshooting ideas for some common RDS Proxy issues and information on CloudWatch logs for RDS Proxy. In the RDS Proxy logs, each entry is prefixed with the name of the associated proxy endpoint. This name can be the name that 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. For more information about proxy endpoints, see [Working with Amazon RDS Proxy endpoints](rds-proxy-endpoints.md). **Topics** + [ ## Verifying connectivity for a proxy ](#rds-proxy-verifying) + [ ## Common issues and solutions ](#rds-proxy-diagnosis) + [ ## Troubleshooting RDS Proxy issues with RDS for MySQL ](#rds-proxy-MySQL-troubleshooting) + [ ## Troubleshooting RDS Proxy issues with RDS for PostgreSQL ](#rds-proxy-PostgreSQL-troubleshooting) ## Verifying connectivity for a proxy You can use the following commands to verify that all components such as the proxy, database, and compute instances in the connection can communicate with the each other. Examine the proxy itself using the [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) command. Also examine the associated target group using the [describe-db-proxy-target-groups](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-target-groups.html) command. Check that the details of the targets match the RDS DB instance that you intend to associate with the proxy. Use commands such as the following. ``` aws rds describe-db-proxies --db-proxy-name $DB_PROXY_NAME aws rds describe-db-proxy-target-groups --db-proxy-name $DB_PROXY_NAME ``` To confirm that the proxy can connect to the underlying database, examine the targets specified in the target groups using the [describe-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html) command. Use a command such as the following. ``` aws rds describe-db-proxy-targets --db-proxy-name $DB_PROXY_NAME ``` The output of the [describe-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html) command includes a `TargetHealth` field. You can examine the fields `State`, `Reason`, and `Description` inside `TargetHealth` to check if the proxy can communicate with the underlying DB instance. + A `State` value of `AVAILABLE` indicates that the proxy can connect to the DB instance. + A `State` value of `UNAVAILABLE` indicates a temporary or permanent connection problem. In this case, examine the `Reason` and `Description` fields. For example, if `Reason` has a value of `PENDING_PROXY_CAPACITY`, try connecting again after the proxy finishes its scaling operation. If `Reason` has a value of `UNREACHABLE`, `CONNECTION_FAILED`, or `AUTH_FAILURE`, use the explanation from the `Description` field to help you diagnose the issue. + The `State` field might have a value of `REGISTERING` for a brief time before changing to `AVAILABLE` or `UNAVAILABLE`. If the following Netcat command (`nc`) is successful, you can access the proxy endpoint from the EC2 instance or other system where you're logged in. This command reports failure if you're not in the same VPC as the proxy and the associated database. You might be able to log directly in to the database without being in the same VPC. However, you can't log into the proxy unless you're in the same VPC. ``` nc -zx MySQL_proxy_endpoint 3306 nc -zx PostgreSQL_proxy_endpoint 5432 ``` You can use the following commands to make sure that your EC2 instance has the required properties. In particular, the VPC for the EC2 instance must be the same as the VPC for the that the proxy connects to. ``` aws ec2 describe-instances --instance-ids your_ec2_instance_id ``` Examine the Secrets Manager secrets used for the proxy. ``` aws secretsmanager list-secrets aws secretsmanager get-secret-value --secret-id your_secret_id ``` Make sure that the `SecretString` field displayed by `get-secret-value` is encoded as a JSON string that includes the `username` and `password` fields. The following example shows the format of the `SecretString` field. ``` { "ARN": "some_arn", "Name": "some_name", "VersionId": "some_version_id", "SecretString": '{"username":"some_username","password":"some_password"}', "VersionStages": [ "some_stage" ], "CreatedDate": some_timestamp } ``` When troubleshooting IAM authentication issues, verify the following: + The database has IAM authentication enabled. + The proxy is configured with the correct authentication scheme. + The IAM policies in the IAM role provided to the proxy grant the necessary `rds-db:connect` permission to the appropriate database and its username. + For end-to-end IAM authentication, database users exist that match the IAM user or role names. + SSL/TLS is enabled for the connection. ## Common issues and solutions This section describes some common issues and potential solutions when using RDS Proxy. After running the `aws rds describe-db-proxy-targets` CLI command, if the `TargetHealth` description states `Proxy does not have any registered credentials`, verify the following: + There are credentials registered for the user to access the proxy. + The IAM role to access the Secrets Manager secret used by the proxy is valid. You might encounter the following RDS events while creating or connecting to a DB proxy. | Category | RDS event ID | Description | | --- | --- | --- | | failure | RDS-EVENT-0243 | RDS couldn't provision capacity for the proxy because there aren't enough IP addresses available in your subnets. To fix the issue, make sure that your subnets have the minimum number of unused IP addresses. To determine the recommended number for your instance class, see [Planning for IP address capacity](rds-proxy-network-prereqs.md#rds-proxy-network-prereqs.plan-ip-address). | | failure | RDS-EVENT-0275 | RDS throttled some connections to DB proxy *name*. The number of simultaneous connection requests from the client to the proxy has exceeded the limit. | You might encounter the following issues while creating a new proxy or connecting to a proxy. | Error | Causes or workarounds | | --- | --- | | `403: The security token included in the request is invalid` | Select an existing IAM role instead of choosing to create a new one. | ## Troubleshooting RDS Proxy issues with RDS for MySQL You might encounter the following issues while connecting to a MySQL proxy. | Error | Causes or workarounds | | --- | --- | | ERROR 1040 (HY000): Connections rate limit exceeded (limit\$1value) | The rate of connection requests from the client to the proxy has exceeded the limit. | | ERROR 1040 (HY000): IAM authentication rate limit exceeded | The number of simultaneous requests with IAM authentication from the client to the proxy has exceeded the limit. | | ERROR 1040 (HY000): Number simultaneous connections exceeded (limit\$1value) | The number of simultaneous connection requests from the client to the proxy exceeded the limit. | | `ERROR 1045 (28000): Access denied for user 'DB_USER'@'%' (using password: YES)` | The Secrets Manager secret used by the proxy doesn't match the user name and password of an existing database user. Either update the credentials in the Secrets Manager secret, or make sure the database user exists and has the same password as in the secret. | | ERROR 1105 (HY000): Unknown error | An unknown error occurred. | | ERROR 1231 (42000): Variable ''character\$1set\$1client'' can't be set to the value of value | The value set for the `character_set_client` parameter is not valid. For example, the value `ucs2` is not valid because it can crash the MySQL server. | | ERROR 3159 (HY000): This RDS Proxy requires TLS connections. | You enabled the setting **Require Transport Layer Security** in the proxy but your connection included the parameter `ssl-mode=DISABLED` in the MySQL client. Do either of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | | ERROR 2026 (HY000): SSL connection error: Internal Server Error | The TLS handshake to the proxy failed. Some possible reasons include the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | | ERROR 9501 (HY000): Timed-out waiting to acquire database connection | The proxy timed-out waiting to acquire a database connection. Some possible reasons include the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | ## Troubleshooting RDS Proxy issues with RDS for PostgreSQL You might encounter the following issues while connecting to a PostgreSQL proxy. | Error | Cause | Solution | | --- | --- | --- | | `ERROR 28000: IAM authentication is allowed only with SSL connections.` | The user tried to connect to the database using IAM authentication with the setting `sslmode=disable` in the PostgreSQL client. | The user needs to connect to the database using the minimum setting of `sslmode=require` in the PostgreSQL client. For more information, see the [PostgreSQL SSL support](https://www.postgresql.org/docs/current/libpq-ssl.html) documentation. | | `ERROR 28000: This RDS proxy has no credentials for the role role_name. Check the credentials for this role and try again.` | There is no Secrets Manager secret for this role. | Add a Secrets Manager secret for this role. For more information, see [Configuring IAM authentication for RDS Proxy](rds-proxy-iam-setup.md). | | `ERROR 28000: RDS supports only IAM, MD5, or SCRAM authentication.` | The database client being used to connect to the proxy is using an authentication mechanism not currently supported by the proxy. | If you're not using IAM authentication, use the MD5 or SCRAM password authentication. | | `ERROR 28000: A user name is missing from the connection startup packet. Provide a user name for this connection.` | The database client being used to connect to the proxy isn't sending a user name when trying to establish a connection. | Make sure to define a user name when setting up a connection to the proxy using the PostgreSQL client of your choice. | | `ERROR 28000: IAM is allowed only with SSL connections.` | A client tried to connect using IAM authentication, but SSL wasn't enabled. | Enable SSL in the PostgreSQL client. | | `ERROR 28000: This RDS Proxy requires TLS connections.` | The user enabled the option **Require Transport Layer Security** but tried to connect with `sslmode=disable` in the PostgreSQL client. | To fix this error, do one of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | | `ERROR 28P01: IAM authentication failed for user user_name. Check the IAM token for this user and try again.` | This error might be due to the following reasons: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | To fix this error, do the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | | `ERROR 28P01: The password that was provided for the role role_name is wrong.` | The password for this role doesn't match the Secrets Manager secret. | Check the secret for this role in Secrets Manager to see if the password is the same as what's being used in your PostgreSQL client. | | `ERROR 28P01: The IAM authentication failed for the role role_name. Check the IAM token for this role and try again.` | There is a problem with the IAM token used for IAM authentication. | Generate a new authentication token and use it in a new connection. | | `ERROR 0A000: Feature not supported: RDS Proxy supports only version 3.0 of the PostgreSQL messaging protocol.` | The PostgreSQL client used to connect to the proxy uses a protocol older than 3.0. | Use a newer PostgreSQL client that supports the 3.0 messaging protocol. If you're using the PostgreSQL `psql` CLI, use a version greater than or equal to 7.4. | | `ERROR 0A000: Feature not supported: RDS Proxy currently doesn't support streaming replication mode.` | The PostgreSQL client used to connect to the proxy is trying to use the streaming replication mode, which isn't currently supported by RDS Proxy. | Turn off the streaming replication mode in the PostgreSQL client being used to connect. | | `ERROR 0A000: Feature not supported: RDS Proxy currently doesn't support the option option_name.` | Through the startup message, the PostgreSQL client used to connect to the proxy is requesting an option that isn't currently supported by RDS Proxy. | Turn off the option being shown as not supported from the message above in the PostgreSQL client being used to connect. | | `ERROR 53300: The IAM authentication failed because of too many competing requests.` | The number of simultaneous requests with IAM authentication from the client to the proxy has exceeded the limit. | Reduce the rate in which connections using IAM authentication from a PostgreSQL client are established. | | `ERROR 53300: The maximum number of client connections to the proxy exceeded number_value.` | The number of simultaneous connection requests from the client to the proxy exceeded the limit. | Reduce the number of active connections from PostgreSQL clients to this RDS proxy. | | `ERROR 53300: Rate of connection to proxy exceeded number_value.` | The rate of connection requests from the client to the proxy has exceeded the limit. | Reduce the rate in which connections from a PostgreSQL client are established. | | `ERROR XX000: Unknown error.` | An unknown error occurred. | Reach out to AWS Support to investigate the issue. | | `ERROR 08000: Timed-out waiting to acquire database connection.` | The proxy timed-out waiting to acquire a database connection within the duration specified by the `ConnectionBorrowTimeout` setting. Some possible reasons include the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | Possible solutions are the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html) | | `ERROR XX000: Request returned an error: database_error.` | The database connection established from the proxy returned an error. | The solution depends on the specific database error. One example is: `Request returned an error: database "your-database-name" does not exist`. This means that the specified database name doesn't exist on the database server. Or it means that the user name used as a database name (if a database name isn't specified) doesn't exist on the server. | | `ERROR 53300: The IAM authentication failed because of too many competing requests.` | The number of simultaneous requests with IAM authentication from the client to the proxy has exceeded the limit. | Reduce the rate in which connections using IAM authentication from a PostgreSQL client are established. | | `ERROR 28000: Enable IAM authentication for the client connection to the proxy and try again.` | RDS Proxy can't connect to the database because IAM authentication isn't enabled for the client connection to the proxy. This occurs when the proxy's `DefaultAuthScheme` parameter is set to `IAM_AUTH` with a registered user, but the client is using password authentication instead of IAM authentication. | Enable IAM authentication for the client connection to the proxy and try again. | | `ERROR 28000: Configure IAM authentication as the DefaultAuthScheme in your proxy and try again.` | RDS Proxy can't connect to the database because the `DefaultAuthScheme` isn't set to `IAM_AUTH`. The proxy's `DefaultAuthScheme` parameter is set to `NONE`, but the client is attempting to use IAM authentication. | Set `DefaultAuthScheme` to `IAM_AUTH` for your proxy and try again. | ### Troubleshooting deleted `postgres` database If you mistakenly delete the `postgres` database from your instance, you need to restore the database to restore connectivity to your instance. Run the following commands within your DB instance: ``` CREATE DATABASE postgres; GRANT CONNECT ON DATABASE postgres TO rdsproxyadmin; ``` # Using RDS Proxy with AWS CloudFormation You can use RDS Proxy with AWS CloudFormation. This helps you to create groups of related resources. Such a group can include a proxy that can connect to a newly created Amazon RDS DB instance. RDS Proxy support in CloudFormation involves two new registry types: `DBProxy` and `DBProxyTargetGroup`. The following listing shows a sample CloudFormation template for RDS Proxy. ``` Resources: DBProxy: Type: AWS::RDS::DBProxy Properties: DBProxyName: CanaryProxy EngineFamily: MYSQL RoleArn: Fn::ImportValue: SecretReaderRoleArn Auth: - {AuthScheme: SECRETS, SecretArn: !ImportValue ProxySecret, IAMAuth: DISABLED} VpcSubnetIds: Fn::Split: [",", "Fn::ImportValue": SubnetIds] ProxyTargetGroup: Type: AWS::RDS::DBProxyTargetGroup Properties: DBProxyName: CanaryProxy TargetGroupName: default DBInstanceIdentifiers: - Fn::ImportValue: DBInstanceName DependsOn: DBProxy ``` For more information about the resources in this sample, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxy.html) and [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html). For more information about resources that you can create using CloudFormation, see [RDS resource type reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_RDS.html). # Using RDS Proxy with Blue/Green Deployments Amazon RDS Proxy can be used with Blue/Green Deployments to reduce switchover downtime. RDS Proxy eliminates DNS propagation delays that typically occur during database transitions by maintaining awareness of the switchover process and automatically redirecting connections to the Green environment once it becomes the active production environment. RDS Proxy supports Blue/Green Deployments for RDS for PostgreSQL, RDS for MySQL and RDS for MariaDB. No application code changes or custom client drivers are required. ## Switchover when using RDS Proxy When your blue instance is attached to RDS Proxy, the following process occurs during switchover: + Switchover Guardrails + Amazon RDS runs additional guardrail checks to validate that the proxy can successfully reach both blue and green environments and is ready for switchover. + Application Traffic Routing During Switchover For the list of switchover actions, see [Switchover actions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/blue-green-deployments-switching.html#blue-green-deployments-switching-actions). When the switchover happens through RDS Proxy, note the following considerations: + During switchover, the Blue database enters read-only mode before Green environment is promoted. RDS Proxy continues routing connections to the blue database during this transitional period. + Write operations on RDS for MySQL during this period may return read-only errors. For example `1290 (HY000): The MySQL server is running with the —read-only option` so it cannot execute this statement. On RDS for PostgreSQL read and write queries will return AdminShutdown terminating connection due to administrator command. + Once the switchover is detected, the proxy automatically routes traffic to the newly promoted green environment. + When the Green environment is promoted as the new writer, existing connections to the proxy are dropped. Applications must re-establish connections after the promotion is complete. + You can review CloudWatch logs for RDS Proxy to see when this transitional behavior occurred. + RDS Proxy API Behavior + Proxy APIs such as `describe-db-proxy-targets` reflect the updated targets only after the switchover is fully complete, even though traffic routing occurs earlier. ## Limitations + Your blue instance must already be a target of the proxy before you create the blue/green deployment. You cannot add a blue instance to an RDS Proxy after a blue/green deployment has been created for that instance.