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.

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.

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.

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.

{
        "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: