Using Amazon Lambda with Amazon RDS - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon Lambda with Amazon RDS

You can connect to an Amazon RDS database through Amazon RDS Proxy. A database proxy manages a pool of shared database connections which enables your function to reach high concurrency levels without exhausting database connections.

We recommend using Amazon RDS Proxy for Lambda functions that make frequent short database connections or open and close large numbers of database connections and do not have built-in connection pooling mechanisms.

Configuring your function

You can create and configure a database proxy from the Amazon RDS console or from your Lambda function configuration.

  • You can use the Lambda console to create an Amazon RDS proxy to an Amazon RDS database in the function Configuration.

  • To connect to a database, you must first connect your function to the same Amazon VPC where your database runs.

  • You can use Amazon RDS databases with MySQL, MariaDB, PostgreSQL, or Microsoft SQL Server engines. You can also use Aurora DB clusters with MySQL or PostgreSQL engines.

  • You need to provide a Secrets Manager secret with the database user name and password.

  • An IAM role must provide permission to use the secret, and a trust policy that allows Amazon RDS to assume the role.

  • You can connect your function to the proxy with a username and password secret, or your function can get credentials from the execution role. To generate a connection token with the role's credentials, use the Amazon RDS signer from the Amazon SDK (described in the following section).

Proxy creation takes a few minutes. When the proxy is available, configure your function to connect to the proxy endpoint instead of the database endpoint.

For more information on connections, see Using Amazon RDS Proxy in the Amazon RDS User Guide.

If too many function instances run concurrently, one or more instances may fail to obtain a database connection.

You can use reserved concurrency to limit the maximum concurrency of the function. Set the reserved concurrency to be less than the number of database connections. Reserved concurrency also reserves those instances for this function, which may not be ideal. If you are invoking the Lambda functions from your application, we recommend you write code that limits the number of concurrent instances.

For concurrency settings, see Managing concurrency for a Lambda function.

Pricing

Amazon RDS charges a hourly price for proxies that is determined by the instance size of your database. For details, see RDS Proxy pricing.

Using the function's permissions for authentication

By default, your function can connect to a proxy with the same username and password for the database. The only difference in your function code is the database endpoint. The drawback of this method is that you must expose the password to your function code, either by configuring it in a secure environment variable or by retrieving it from Secrets Manager.

Alternatively, a database proxy can use the function's IAM credentials for authentication and authorization instead of a password. To use the function's permissions to connect to the proxy, set Authentication to Execution role.

The Lambda console adds the required permission (rds-db:connect) to the execution role. You can then use the Amazon SDK to generate a token that allows it to connect to the proxy. The following example shows how to configure a database connection with the mysql2 library in Node.js.

Example dbadmin/index-iam.js – Amazon SDK signer
const signer = new AWS.RDS.Signer({ region: region, hostname: host, port: sqlport, username: username }) exports.handler = async (event) => { let connectionConfig = { host : host, user : username, database : database, ssl: 'Amazon RDS', authPlugins: { mysql_clear_password: () => () => signer.getAuthToken() } } var connection = mysql.createConnection(connectionConfig) var query = event.query var result connection.connect() }

For more information, see IAM database authentication in the Amazon RDS User Guide.

Process event notifications from Amazon RDS

You can use Lambda to process event notifications from an Amazon Relational Database Service (Amazon RDS) database. Amazon RDS sends notifications to an Amazon Simple Notification Service (Amazon SNS) topic, which you can configure to invoke a Lambda function. Amazon SNS wraps the message from Amazon RDS in its own event document and sends it to your function.

Example Amazon RDS message in an Amazon SNS event
{ "Records": [ { "EventVersion": "1.0", "EventSubscriptionArn": "arn:aws-cn:sns:us-east-2:123456789012:rds-lambda:21be56ed-a058-49f5-8c98-aedd2564c486", "EventSource": "aws:sns", "Sns": { "SignatureVersion": "1", "Timestamp": "2019-01-02T12:45:07.000Z", "Signature": "tcc6faL2yUC6dgZdmrwh1Y4cGa/ebXEkAi6RibDsvpi+tE/1+82j...65r==", "SigningCertUrl": "https://sns.us-east-2.amazonaws.com/SimpleNotificationService-ac565b8b1a6c5d002d285f9598aa1d9b.pem", "MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e", "Message": "{\"Event Source\":\"db-instance\",\"Event Time\":\"2019-01-02 12:45:06.000\",\"Identifier Link\":\"https://console.amazonaws.cn/rds/home?region=eu-west-1#dbinstance:id=dbinstanceid\",\"Source ID\":\"dbinstanceid\",\"Event ID\":\"http://docs.amazonwebservices.com/AmazonRDS/latest/UserGuide/USER_Events.html#RDS-EVENT-0002\",\"Event Message\":\"Finished DB Instance backup\"}", "MessageAttributes": {}, "Type": "Notification", "UnsubscribeUrl": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws-cn:sns:us-east-2:123456789012:test-lambda:21be56ed-a058-49f5-8c98-aedd2564c486", "TopicArn":"arn:aws-cn:sns:us-east-2:123456789012:sns-lambda", "Subject": "RDS Notification Message" } } ] }

For more information about configuring an Amazon RDS database to send notifications, see Using Amazon RDS event notifications.

Tutorial and sample applications

The tutorial in the Amazon RDS guide shows in detail how to automatically configure and connect Lambda via Amazon VPC to an Amazon RDS instance. Also listed are two older sample applications from this guide's GitHub repository which use Lambda with an Amazon RDS database:

  • Tutorial: Using a Lambda function to access Amazon RDS in an Amazon VPC – Use a Lambda function to write data to an Amazon RDS database through an Amazon RDS Proxy. Your Lambda function reads records from an Amazon SQS queue and writes a new item to a table in your database whenever a message is added.

  • RDS MySQL – Sets up a MySQL database in a private VPC with a Lambda function that proxies queries to it. The function and database templates both use Secrets Manager to access database credentials.

  • List Manager – Creates a processor function that reads events from a Kinesis stream, uses data from the events to update DynamoDB tables, and stores a copy of the event in a MySQL database.