How do I configure a Lambda function to connect to an RDS instance?

Short description

Note: The following resolution refers to Amazon RDS instances. However, this resolution also applies to any endpoint or database that's located in a virtual private cloud (VPC).

To connect a Lambda function to an RDS instance, set the network configurations to allow the connection.

There are different configuration settings for a Lambda function and RDS instance depending on whether they're in the same VPC or in different VPCs.

For security reasons, it's a best practice to keep your RDS instance in a VPC. For public databases, use a NoSQL database service such as Amazon DynamoDB.

Note: A Lambda function that's outside of a VPC can't access an RDS instance that's inside a VPC.

For information about how to configure network settings for Lambda functions, see Giving Lambda functions access to resources in an Amazon VPC.

Note: If the network settings are incorrect, then the Lambda function times out and displays a Task timed out error message.

To connect a Lambda function to an Amazon Aurora DB cluster, use the Data API for Aurora Serverless.

Resolution

Important: Make sure that you change each Port Range, Source, and Destination setting that's provided in the following examples to match your own network configurations. Transmission Control Protocol (TCP) is the required protocol for each type of network configuration.

A Lambda function and RDS instance in the same VPC

To connect a Lambda function to an RDS instance in the same VPC, use the following network configurations:

Note: By default, all subnets within a VPC contain a local route. The destination is the Classless Inter-Domain Routing (CIDR) for the VPC and the target is local. For more information, see Route table concepts.

1. For Security Groups, use one of the following network settings:
   For instances attached to the same security group, make the security group the source for the inbound rule. Make the security group the destination for the outbound rule.
   For example, if the Lambda function and RDS instance are both in security group sg-abcd1234, then each instance has the following inbound and outbound rules.
   Example inbound rule for instances attached to the same security group

   Type	Protocol	Port Range	Source
   Custom TCP	TCP	3306	sg-abcd1234

   Example outbound rule for instances attached to the same security group

   Type	Protocol	Port Range	Destination
   Custom TCP	TCP	3306	sg-abcd1234

   -or-
   For instances in different security groups, make sure that both security groups allow access to each other.
   For example, if the Lambda function is in security group sg-1234 and the RDS instance is in sg-abcd, then each group has the following rules:
   Example outbound rule for a Lambda function in a different security group than the RDS instance that you want to connect it to

   Type	Protocol	Port Range	Destination
   Custom TCP	TCP	3306	sg-abcd

2. Example inbound rule for an RDS instance in a different security group than the Lambda function that you want to connect it to

   Type	Protocol	Port Range	Source
   Custom TCP	TCP	3306	sg-1234

   Important: Make sure that the rules allow a TCP connection over the databases port.

3. For the network access control lists (NACLs), make sure that the inbound and outbound rules allow communication between the Lambda function and RDS instance.

   Note: By default, NACLs allow all inbound and outbound traffic. However, you can change these default settings.

   For each subnet that's associated with the RDS instance and function, configure the NACLs to allow outbound TCP connection to the other instances subnets CIDRs.

   Note: The following example uses four example subnets with labeled CIDRs:

   For the Lambda functions subnets, 172.31.1.0/24 and 172.31.0.0/28

   For the RDS instances subnets, 172.31.10.0/24 and 172.31.64.0/20

   Example outbound rules for a Lambda functions subnets NACLs

   Type	Protocol	Port Range	Destination	Allow/Deny
   Custom TCP	TCP	3306	172.31.10.0/24	Allow
   Custom TCP	TCP	3306	172.31.64.0/20	Allow

   Important: Apply the same Outbound rules to the NACLs of the RDS instances subnets, but with the destination set as the Lambda subnets' CIDRs.

   Make sure that the NACLs for each subnet have an inbound rule on the ephemeral ports over the CIDR range of the other instance's subnets.

   Example inbound rules for a Lambda functions subnets NACLs

   Type	Protocol	Port Range	Source	Allow/Deny
   Custom TCP	TCP	1024-65535	172.31.10.0/24	Allow
   Custom TCP	TCP	1024-65535	172.31.64.0/20	Allow

   Important: Apply the same inbound rules to the NACLs of the RDS instances subnets, but with the source set as the Lambda subnets' CIDRs.

A Lambda function and RDS instance in different VPCs

First, use VPC peering to connect the two VPCs. Then, use the following network configurations to connect the Lambda function in one VPC to the RDS instance in the other:

Important: Be sure to turn on Domain Name System (DNS) for the VPC peering connection.

1. For the Route Table, confirm that the VPC peering connection is successful:
   For the Destination, check for the CIDR of the peered VPC.
   For the Target, check for the peering connection.

   Note: The following example includes two example VPCs:

   CIDR of source VPC (Lambda function): 10.0.0.0/16

   CIDR of peered VPC (RDS instance): 172.31.0.0/16

   Peering connection: pcx-01234abcd

   Example route table for a source VPC that's associated with the Lambda function

   Destination	Target
   172.31.0.0/16	pcx-01234abcd
   10.0.0.0/16	local

   Example route table for a peered VPC with an RDS instance

   Destination	Target
   10.0.0.0/16	pcx-01234abcd
   172.31.0.0/16	local

   For more information, see Update your route tables for a VPC peering connection.

2. For Security Groups, use the following network settings:
   For the Lambda function security group, make sure that traffic is allowed to go in and out of the CIDR of the VPC with the RDS instance. 
   Note: The following example includes two example subnets labeled by their CIDRs:
   For the RDS instance, 172.31.0.0/16
   For the Lambda function, 10.0.0.0/16
   Example outbound rule for a Lambda function in a different VPC than the RDS instance

   Type	Protocol	Port Range	Destination
   Custom TCP	TCP	3306	172.31.0.0/16

   For the RDS instances security group, allow traffic to go in and out of the CIDR of the Lambda function's security group.

   Example inbound rule for an RDS instance in a different VPC than the Lambda function

   Type	Protocol	Port Range	Source
   Custom TCP	TCP	3306	10.0.0.0/16

3. For the NACLs, follow the previous procedures in step 3 of the A Lambda function and RDS instance in the same VPC section. The origin of the Lambda functions subnet CIDR is in a different VPC.
   Note: As an alternative to VPC peering, you can use AWS PrivateLink to access Amazon RDS across VPCs. This solution works across AWS accounts and VPCs in the same AWS Region.