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

Invoking an Amazon Lambda function from an Aurora PostgreSQL DB cluster

Amazon Lambda is an event-driven compute service that lets you run code without provisioning or managing servers. It's available for use with many Amazon services, including Aurora PostgreSQL. For example, you can use Lambda functions to process event notifications from a database, or to load data from files whenever a new file is uploaded to Amazon S3. To learn more about Lambda, see What is Amazon Lambda? in the Amazon Lambda Developer Guide.

Setting up Aurora PostgreSQL to work with Lambda functions is a multi-step process involving Amazon Lambda, IAM, your VPC, and your Aurora PostgreSQL DB cluster. Following, you can find summaries of the necessary steps.

For more information about Lambda functions, see Getting started with Lambda and Amazon Lambda foundations in the Amazon Lambda Developer Guide.

Step 1: Configure your Aurora PostgreSQL DB cluster for outbound connections to Amazon Lambda

Lambda functions always run inside an Amazon VPC that's owned by the Amazon Lambda service. Lambda applies network access and security rules to this VPC and it maintains and monitors the VPC automatically. Your Aurora PostgreSQL DB cluster sends network traffic to the Lambda service's VPC. How you configure this depends on whether your Aurora DB cluster's primary DB instance is public or private.

Your VPC can now interact with the Amazon Lambda VPC at the network level. Next, you configure the permissions using IAM.

Step 2: Configure IAM for your Aurora PostgreSQL DB cluster and Amazon Lambda

Invoking Lambda functions from your Aurora PostgreSQL DB cluster requires certain privileges. To configure the necessary privileges, we recommend that you create an IAM policy that allows invoking Lambda functions, assign that policy to a role, and then apply the role to your DB cluster. This approach gives the DB cluster privileges to invoke the specified Lambda function on your behalf. The following steps show you how to do this using the Amazon CLI.

With the VPC and the IAM configurations complete, you can now install the aws_lambda extension. (Note that you can install the extension at any time, but until you set up the correct VPC support and IAM privileges, the aws_lambda extension adds nothing to your Aurora PostgreSQL DB cluster's capabilities.)

Step 3: Install the aws_lambda extension for an Aurora PostgreSQL DB cluster

To use Amazon Lambda with your Aurora PostgreSQL DB cluster, add the aws_lambda PostgreSQL extension to your Aurora PostgreSQL DB cluster. This extension provides your Aurora PostgreSQL DB cluster with the ability to call Lambda functions from PostgreSQL.

The aws_lambda extension is installed in your Aurora PostgreSQL DB cluster's primary DB instance. You can now create convenience structures for invoking your Lambda functions.

Step 4: Use Lambda helper functions with your Aurora PostgreSQL DB cluster (Optional)

You can use the helper functions in the aws_commons extension to prepare entities that you can more easily invoke from PostgreSQL. To do this, you need to have the following information about your Lambda functions:

To hold the Lambda function name information, you use the aws_commons.create_lambda_function_arn function. This helper function creates an aws_commons._lambda_function_arn_1 composite structure with the details needed by the invoke function. Following, you can find three alternative approaches to setting up this composite structure.

SELECT aws_commons.create_lambda_function_arn(
   'my-function',
   'aws-region'
) AS aws_lambda_arn_1 \gset

SELECT aws_commons.create_lambda_function_arn(
   '111122223333:function:my-function',
   'aws-region'
) AS lambda_partial_arn_1 \gset

SELECT aws_commons.create_lambda_function_arn(
   'arn:aws-cn:lambda:aws-region:111122223333:function:my-function'
) AS lambda_arn_1 \gset

Any of these values can be used in calls to the aws_lambda.invoke function. For examples, see Step 5: Invoke a Lambda function from your Aurora PostgreSQL DB cluster.

Step 5: Invoke a Lambda function from your Aurora PostgreSQL DB cluster

The aws_lambda.invoke function behaves synchronously or asynchronously, depending on the invocation_type. The two alternatives for this parameter are RequestResponse (the default) and Event, as follows.

As a simple test of your setup, you can connect to your DB instance using psql and invoke an example function from the command line. Suppose that you have one of the basic functions set up on your Lambda service, such as the simple Python function shown in the following screenshot.

If your invocation attempt doesn't succeed, see Lambda function error messages .

Step 6: Grant other users permission to invoke Lambda functions

At this point in the procedures, only you as rds_superuser can invoke your Lambda functions. To allow other users to invoke any functions that you create, you need to grant them permission.

Examples: Invoking Lambda functions from your Aurora PostgreSQL DB cluster

Following, you can find several examples of calling the aws_lambda.invoke function. Most all the examples use the composite structure aws_lambda_arn_1 that you create in Step 4: Use Lambda helper functions with your Aurora PostgreSQL DB cluster (Optional) to simplify passing the function details. For an example of asynchronous invocation, see Example: Asynchronous (Event) invocation of Lambda functions. All the other examples listed use synchronous invocation.

To learn more about Lambda invocation types, see Invoking Lambda functions in the Amazon Lambda Developer Guide. For more information about aws_lambda_arn_1, see aws_commons.create_lambda_function_arn.

Example: Synchronous (RequestResponse) invocation of Lambda functions

Following are two examples of a synchronous Lambda function invocation. The results of these aws_lambda.invoke function calls are the same.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json);

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse');

The parameters are described as follows:

Example: Asynchronous (Event) invocation of Lambda functions

Following is an example of an asynchronous Lambda function invocation. The Event invocation type schedules the Lambda function invocation with the specified input payload and returns immediately. Use the Event invocation type in certain workflows that don't depend on the results of the Lambda function.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'Event');

Example: Capturing the Lambda execution log in a function response

You can include the last 4 KB of the execution log in the function response by using the log_type parameter in your aws_lambda.invoke function call. By default, this parameter is set to None, but you can specify Tail to capture the results of the Lambda execution log in the response, as shown following.

SELECT *, select convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

Set the aws_lambda.invoke function's log_type parameter to Tail to include the execution log in the response. The default value for the log_type parameter is None.

The log_result that's returned is a base64 encoded string. You can decode the contents using a combination of the decode and convert_from PostgreSQL functions.

For more information about log_type, see aws_lambda.invoke.

Example: Including client context in a Lambda function

The aws_lambda.invoke function has a context parameter that you can use to pass information separate from the payload, as shown following.

SELECT *, convert_from(decode(log_result, 'base64'), 'utf-8') as log FROM aws_lambda.invoke(:'aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'Tail');

To include client context, use a JSON object for the aws_lambda.invoke function's context parameter.

For more information about the context parameter, see the aws_lambda.invoke reference.

Example: Invoking a specific version of a Lambda function

You can specify a particular version of a Lambda function by including the qualifier parameter with the aws_lambda.invoke call. Following, you can find an example that does this using 'custom_version' as an alias for the version.

SELECT * FROM aws_lambda.invoke('aws_lambda_arn_1', '{"body": "Hello from Postgres!"}'::json, 'RequestResponse', 'None', NULL, 'custom_version');

You can also supply a Lambda function qualifier with the function name details instead, as follows.

SELECT * FROM aws_lambda.invoke(aws_commons.create_lambda_function_arn('my-function:custom_version', 'us-west-2'),
'{"body": "Hello from Postgres!"}'::json);

For more information about qualifier and other parameters, see the aws_lambda.invoke reference.

Lambda function error messages

In the following list you can find information about error messages, with possible causes and solutions.