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.
Topics
Connecting to a proxy using native authentication
Use the following steps to connect to a proxy using native authentication:
-
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 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" } ] ]
-
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 orpsql -h
option. -
Supply the same database user name and password as you usually do.
Connecting to a proxy using IAM authentication
When you use IAM authentication with RDS Proxy, set up your database users to authenticate with regular user names and passwords. The IAM authentication applies to RDS Proxy retrieving the user name and password credentials from Secrets Manager. The connection from RDS Proxy to the underlying database doesn't go through IAM.
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.
The major differences in IAM usage for RDS Proxy include the following:
-
You don't configure each individual database user with an authorization plugin. The database users still have regular user names and passwords 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.
-
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.
-
In the direct database IAM authentication case, you selectively choose database users and configure them to be identified with a special authentication plugin. You can then connect to those users using IAM authentication.
In the proxy use case, you provide the proxy with Secrets that contain some user's user name and password (native authentication). You then connect to the proxy using IAM authentication. Here, you do this by generating an authentication token with the proxy endpoint, not the database endpoint. You also use a user name that matches one of the user names for the secrets that you provided.
-
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"
Considerations for connecting to a proxy with 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.
Considerations for connecting to a proxy with PostgreSQL
For PostgreSQL, 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
When connecting 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:
For more information about PostgreSQL messaging, see the Frontend/Backend
protocol
For PostgreSQL, if you use JDBC, we recommend the following to avoid pinning:
-
Set the JDBC connection parameter
assumeMinServerVersion
to at least9.0
to avoid pinning. This prevents the JDBC driver from performing an extra round trip during connection startup when it runsSET extra_float_digits = 3
. -
Set the JDBC connection parameter
ApplicationName
to
to avoid pinning. Doing this prevents the JDBC driver from performing an extra round trip during connection startup when it runsany/your-application-name
SET application_name = "PostgreSQL JDBC Driver"
. Note the JDBC parameter isApplicationName
but the PostgreSQLStartupMessage
parameter isapplication_name
.
For more information, see Avoiding pinning an RDS Proxy. For more information about connecting using JDBC, see
Connecting to the
database