Create and Deploy an AWS Lambda Function Built on CockroachDB

On this page

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:

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

Create a CockroachDB Cloud account. If this is your first CockroachDB Cloud organization, it will be credited with $400 in free trial credits to get you started.
On the Get Started page, click Create cluster.
On the Select a plan page, select Standard.
On the Cloud & Regions page, select a cloud provider (GCP or AWS).
In the Regions section, select a region for the cluster. Refer to CockroachDB Cloud Regions for the regions where CockroachDB Standard clusters can be deployed. To create a multi-region cluster, click Add region and select additional regions.
Click Next: Capacity.
On the Capacity page, keep the Provisioned capacity at the default value of 2 vCPUs.

Click Next: Finalize.
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 end of the trial 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.

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.

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.

In the node directory, install the code dependencies:
```
cd node; npm install
```
Compress the project files to a ZIP file in the parent directory for deployment:
```
zip -r ../my-deployment-package.zip .
```

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
```
Note:

To run on Amazon Linux distributions, pscyopg2 dependencies must be compiled for Linux.
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

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.

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

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.

Note:

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.

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

Cockroach
University

Docs Hub

Create and Deploy an AWS Lambda Function Built on CockroachDB

Before you begin

Step 1. Create a CockroachDB Standard cluster

Step 2. Get the code

Step 3. (Optional) Create the deployment package

Step 4. Configure AWS

Step 5. Deploy the function to AWS Lambda

See also

Cockroach University

Docs Hub

Cockroach University

Docs Hub

Create and Deploy an AWS Lambda Function Built on CockroachDB

Before you begin

Step 1. Create a CockroachDB Standard cluster

Step 2. Get the code

Step 3. (Optional) Create the deployment package

Step 4. Configure AWS

Step 5. Deploy the function to AWS Lambda

See also

Cockroach
University

Cockroach
University