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