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

The example function used for this tutorial is written in Python. The function uses the Psycopg PostgreSQL adapter to connect to CockroachDB.

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

    Note:

    This cluster will be free forever.

  5. Click Create your free cluster.

Your cluster will be created in approximately 20-30 seconds.

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 copy the sample code's GitHub repo:

icon/buttons/copy
$ git clone https://github.com/cockroachlabs/examples-aws-lambda

The 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

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 a deployment package that is ready to deploy.

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

  2. 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 us-east-1  \
        --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>'}
    

    Where <account-id> is your AWS account ID, and <connection-string> is the connection string to the CockroachDB cluster.

  2. Invoke the function:

    icon/buttons/copy
    $ aws lambda invoke --function-name init-crdb out --region us-east-1 --log-type Tail \
        --query 'LogResult' --output text |  base64 -d
    
    START RequestId: 93866b3e-d3f0-477d-a28a-37d602effcda Version: $LATEST
    [INFO]  2021-11-17T17:42:54.563Z    93866b3e-d3f0-477d-a28a-37d602effcda    Hey! You successfully connected to your CockroachDB cluster.
    [INFO]  2021-11-17T17:42:54.659Z    93866b3e-d3f0-477d-a28a-37d602effcda    Created new account with id 0dd39de7-abea-4241-b7fa-09133b3bcaff and balance 866851.
    [INFO]  2021-11-17T17:42:54.691Z    93866b3e-d3f0-477d-a28a-37d602effcda    Created new account with id 3698ffe6-a72a-427c-b9ef-fba1d723dc5e and balance 513474.
    [INFO]  2021-11-17T17:42:54.722Z    93866b3e-d3f0-477d-a28a-37d602effcda    Created new account with id 63d7e9c0-e155-4be9-b770-487e486b0c1c and balance 916934.
    [INFO]  2021-11-17T17:42:54.754Z    93866b3e-d3f0-477d-a28a-37d602effcda    Created new account with id dd5ee7e2-c86d-4b9e-801f-7abbe8abb99a and balance 108706.
    [INFO]  2021-11-17T17:42:54.786Z    93866b3e-d3f0-477d-a28a-37d602effcda    Created new account with id 16056406-9b5f-4754-8cb7-b1f37fc64dad and balance 549873.
    [INFO]  2021-11-17T17:42:54.820Z    93866b3e-d3f0-477d-a28a-37d602effcda    Database initialized.
    END RequestId: 93866b3e-d3f0-477d-a28a-37d602effcda
    REPORT RequestId: 93866b3e-d3f0-477d-a28a-37d602effcda  Duration: 722.63 ms Billed Duration: 1117 ms    Memory Size: 128 MB Max Memory Used: 47 MB  Init Duration: 393.51 ms
    

See also

You might also be interested in the following pages:

YesYes NoNo