Create and Deploy an AWS Lambda Function Built on CockroachDB

On this page

Warning:

As of June 5, 2024, CockroachDB v22.2 is no longer supported. For more details, refer to the Release Support Policy.

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

Before you begin

Before starting the tutorial, do the following:

Create a CockroachDB Cloud account.
Create an AWS account.
Create an AWS user with administrator permissions.
Install the AWS CLI.

Step 1. Create a CockroachDB Serverless cluster

Note:

Organizations without billing information on file can only create one CockroachDB Serverless cluster.

If you haven't already, sign up for a CockroachDB Cloud account.
Log in to your CockroachDB Cloud account.
On the Clusters page, click Create Cluster.
On the Select a plan page, select Serverless.
On the Cloud & Regions page, select a cloud provider (GCP or AWS) in the Cloud provider section.
In the Regions section, select a region for the cluster. Refer to CockroachDB Cloud Regions for the regions where CockroachDB Serverless clusters can be deployed. To create a multi-region cluster, click Add region and select additional regions. A cluster can have at most six regions.
Click Next: Capacity.
On the Capacity page, select Start for free. Click Next: Finalize.
On the Finalize page, 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.

Note:

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.

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.

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

Note:

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.

Navigate to the Node.js function directory:
```
cd node
```
Install the code dependencies:
```
npm install
```
Compress the project files to a ZIP file for deployment:
```
zip -r deployment-package.zip .
```

Navigate to the Python function directory:
```
cd python
```
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
```
Note:

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

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:

$ 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

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

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 Serverless cluster

Step 2. Get the sample 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 Serverless cluster

Step 2. Get the sample 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