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 a CockroachDB Cloud account.
2. Create an AWS account.
3. Create an AWS user with administrator permissions.
4. Install the AWS CLI.

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 username, cluster name, and other details, including your password. Your password, in particular, will be provided only once. Save it in a secure place (we recommend a password manager) to connect to your cluster in the future. If you forget your password, you can reset it by going to the SQL Users page for the cluster, found at https://cockroachlabs.cloud/cluster/<CLUSTER ID>/users.

Step 2. Get the sample code

Open a terminal window and 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.

node.js

The Node.js function code is available under the examples-aws-lambda/node directory:

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

This function uses the node-postgres modules to connect to CockroachDB.

Step 3. (Optional) Create the deployment package

This step is optional, as you do not need to create a new deployment package to deploy the sample function. The examples-aws-lambda repo includes deployment packages that are ready to deploy.

1. Navigate to the Node.js function directory:

   cd node
   

2. Install the code dependencies:

   npm install
   

3. Compress the project files to a ZIP file for deployment:

   zip -r deployment-package.zip .
   

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:

   $ 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
   

   The Lambda function needs this role to run.

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}"
   

   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.

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

Python

The Python function’s code is available under the examples-aws-lambda/python directory:

.
├── 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

This function uses the Psycopg2 PostgreSQL adapter to connect to CockroachDB.

Step 3. (Optional) Create the deployment package

This step is optional, as you do not need to create a new deployment package to deploy the sample function. The examples-aws-lambda repo includes deployment packages that are ready to deploy.

1. Navigate to the Python function directory:

   cd python
   

2. Download and install the psycopg2-binary Python library to a new directory:

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

3. Compress the project files to a ZIP file for deployment:

   $ cd my-package
   
   $ zip -r ../my-deployment-package.zip .
   
   $ cd ..
   
   $ zip -g my-deployment-package.zip 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:

   $ 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
   

   The Lambda function needs this role to run.

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 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, or in the environment variable PGSSLROOTCERT.

2. 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: