Create and Deploy an AWS Lambda Function Built on CockroachDB

This tutorial shows you how to create an AWS Lambda function that communicates with a CockroachDB Standard cluster.

Before you begin

Before starting the tutorial, do the following:

1. Create an AWS account and log in, then:
   1. Create an AWS user with administrator permissions.
   2. Install the AWS CLI and log in locally.

Step 1. Create a CockroachDB Standard cluster

1. . If this is your first CockroachDB Cloud organization, it will be credited with $400 in to get you started.

2. On the Get Started page, click Create cluster.

3. On the Select a plan page, select Standard.

4. On the Cloud & Regions page, select a cloud provider (GCP or AWS).

5. In the Regions section, select a region for the cluster. Refer to for the regions where CockroachDB Standard clusters can be deployed. To create a multi-region cluster, click Add region and select additional regions.

6. Click Next: Capacity.

7. On the Capacity page, keep the at the default value of 2 vCPUs.

   Click Next: Finalize.

8. On the Finalize page, name your cluster. If an active free trial is listed in the right pane, you will not need to add a payment method, though you will need to do this by the to maintain your organization’s clusters.

   Click Create cluster.

   Your cluster will be created in a few seconds and the Create SQL user dialog will display.

After the cluster is created, the Connection info window appears. Click the Connection string tab and copy the connection string to a secure location. You will use this connection string to connect to CockroachDB later in the tutorial.

The connection string is pre-populated with your SQL username and password, the cluster name, and other details. Save the password in a secure place such a password manager. You can find the connection string at any time from the CockroachDB Cloud Console. You can reset your SQL password for this cluster from the cluster’s SQL Users page.

Step 2. Get the code

In a terminal, clone the sample code’s GitHub repo:

git clone https://github.com/cockroachlabs/examples-aws-lambda

This repo includes samples for Node.js and Python Lambda runtimes. Select either node.js or Python to continue.

node.js

The Node.js function code is located in the examples-aws-lambda/node directory and has the following structure:

├── README.md
├── deployment-package.zip  ## Lambda deployment package
├── index.js                ## Lambda function source code
├── package-lock.json       ## Dependencies
└── package.json            ## Dependencies

The Lambda function uses the node-postgres modules to connect to your cluster.

Python

The Python function code is located in the examples-aws-lambda/python directory and has the following structure:

├── README.md
├── deployment-package.zip  ## Lambda deployment package
├── init_db.py              ## Lambda function source code
├── package                 ## Psycopg dependencies
├── requirements.txt        ## List of Python requirements
└── root.crt                ## CA cert

The Lambda function uses the Psycopg2 PostgreSQL adapter to connect to your cluster.

Step 3. (Optional) Create the deployment package

Creating a deployment package to deploy the sample function is optional. The examples-aws-lambda repo includes deployment packages that are ready to deploy.

1. In the node directory, install the code dependencies:

   cd node; npm install
   

2. Compress the project files to a ZIP file in the parent directory for deployment:

   zip -r ../my-deployment-package.zip .
   

3. In the python directory, download and install the psycopg2-binary Python library:

   cd python; python3 -m pip install \
     --only-binary :all: \
     --platform manylinux1_x86_64 \
     --target ./my-package \
     -r requirements.txt
   

To run on Amazon Linux distributions, pscyopg2 dependencies must be compiled for Linux.

1. Compress the project files to a ZIP file in the parent directory for deployment:

   zip -r ../my-deployment-package.zip my-deployment-package ./init_db.py ./root.crt
   

Step 4. Configure AWS

1. Configure the AWS CLI to authenticate with your AWS account:

   aws configure
   

   Follow the prompts to authenticate as a user with administrator privileges. We do not recommend using the root user.

2. Create an execution role for the Lambda function and attach the AWSLambdaBasicExecutionRole policy to the role. The Lambda function needs this role to run.

   aws iam create-role \
     --role-name lambda-ex \
     --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
   
   aws iam attach-role-policy \
     --role-name lambda-ex \
     --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
   

Step 5. Deploy the function to AWS Lambda

1. In the deployment package directory, use the AWS CLI to create a Lambda function:

   aws lambda create-function \
     --function-name init-crdb \
     --region <region>  \
     --zip-file fileb://deployment-package.zip \
     --handler index.handler \
     --runtime nodejs14.x \
     --role arn:aws:iam::<account-id:role/lambda-ex \
     --environment "Variables={DATABASE_URL=<connection-string}"
   
   aws lambda create-function \
     --function-name init-crdb \
     --region <region>  \
     --zip-file fileb://deployment-package.zip \
     --handler init_db.lambda_handler \
     --runtime python3.9 \
     --role arn:aws:iam::<account-id:role/lambda-ex \
     --environment "Variables={DATABASE_URL=<connection-string,PGSSLROOTCERT=./root.crt}"
   

   Where:

   • <region is the region closest to your CockroachDB deployment.
   • <account-id is your AWS account ID.
   • <connection-string is the connection string to the CockroachDB cluster.

To connect to a CockroachDB Standard cluster with Psycopg2, you must provide the client with a valid CA certificate. By default, Pscyopg2 searches for the certificate at ~/.postgresql/root.crt and in the location point to by the environment variable PGSSLROOTCERT.

1. Invoke the function:

   aws lambda invoke \
     --function-name init-crdb out \
     --log-type Tail \
     --query 'LogResult' \
     --output text | base64 -d
   
   START RequestId: 12232b98-daac-4a1e-80e9-f2ecaa6497aa Version: $LATEST
   2022-02-16T19:24:49.569Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Initializing table...
   2022-02-16T19:24:49.596Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Hey! You successfully connected to your CockroachDB cluster.
   2022-02-16T19:24:49.635Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Created new account with balance 320.
   2022-02-16T19:24:49.655Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Created new account with balance 593.
   2022-02-16T19:24:49.660Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Created new account with balance 277.
   2022-02-16T19:24:49.675Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Created new account with balance 844.
   2022-02-16T19:24:49.680Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Created new account with balance 257.
   2022-02-16T19:24:49.680Z        12232b98-daac-4a1e-80e9-f2ecaa6497aa    INFO    Database initialized.
   END RequestId: 12232b98-daac-4a1e-80e9-f2ecaa6497aa
   REPORT RequestId: 12232b98-daac-4a1e-80e9-f2ecaa6497aa  Duration: 644.49 ms     Billed Duration: 645 ms Memory Size: 128 MB     Max Memory Used: 63 MB  Init Duration: 198.77 ms
   

See also

You might also be interested in the following pages: