Create and Deploy an AWS Lambda Function Built on CockroachDB

Warning:
Cockroach Labs will stop providing Assistance Support for this version on November 18, 2022. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, see the Release Support Policy.

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

Prerequisites

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 Serverless (beta) cluster

  1. If you haven't already, sign up for a CockroachDB Cloud account.
  2. Log in to your CockroachDB Cloud account.
  3. On the Clusters page, click Create Cluster.
  4. On the Create your cluster page, select Serverless.

    Unless you change your monthly budget, this cluster will be free forever.

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

Step 2. Get the sample code

Open a terminal window and clone the sample code's GitHub repo:

icon/buttons/copy
$ 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.

  1. Navigate to the Node.js function directory:

    icon/buttons/copy
    cd node
    
  2. Install the code dependencies:

    icon/buttons/copy
    npm install
    
  3. Compress the project files to a ZIP file for deployment:

    icon/buttons/copy
    zip -r deployment-package.zip .
    
  1. Navigate to the Python function directory:

    icon/buttons/copy
    cd python
    
  2. Download and install the psycopg2-binary Python library to a new directory:

    icon/buttons/copy
    $ 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.

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

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

    icon/buttons/copy
    $ aws configure
    

    Follow the prompts to authenticate as a user with administrator priviliges. 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:

    icon/buttons/copy
    $ 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"}]}'
    
    icon/buttons/copy
    $ 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:

    icon/buttons/copy
    $ 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>}"
    
    icon/buttons/copy
    $ 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:

    Note:

    To connect to a CockroachDB Serverless (beta) 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:

    icon/buttons/copy
    $ 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:

YesYes NoNo