> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and Deploy an AWS Lambda Function Built on CockroachDB

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This tutorial shows you how to create an [AWS Lambda](https://aws.amazon.com/lambda) function that communicates with a CockroachDB Standard cluster.

## Before you begin

Before starting the tutorial, do the following:

1. Create an [AWS](https://aws.amazon.com/) account and log in, then:
   1. Create an [AWS user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users) with administrator permissions.
   2. Install the [AWS CLI](https://aws.amazon.com/cli) and log in locally.

## Step 1. Create a CockroachDB Standard cluster

1. <InternalLink version="cockroachcloud" path="create-an-account">Create a CockroachDB Cloud account</InternalLink>. If this is your first CockroachDB Cloud organization, it will be credited with \$400 in <InternalLink version="cockroachcloud" path="free-trial">free trial credits</InternalLink> 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 <InternalLink version="cockroachcloud" path="regions">CockroachDB Cloud Regions</InternalLink> 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 <InternalLink version="cockroachcloud" path="plan-your-cluster">**Provisioned capacity**</InternalLink> 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 <InternalLink version="cockroachcloud" path="free-trial#add-payment-methods">end of the trial</InternalLink> 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](https://github.com/cockroachlabs/examples-aws-lambda):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
git clone https://github.com/cockroachlabs/examples-aws-lambda
```

This repo includes samples for Node.js and Python [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes). Select either node.js or Python to continue.

<Tabs>
  <Tab title="node.js">
    The Node.js function code is located in the `examples-aws-lambda/node` directory and has the following structure:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    ├── 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](https://node-postgres.com/) modules 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.

    1. In the `node` directory, install the code dependencies:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       cd node; npm install
       ```
    2. Compress the project files to a ZIP file in the parent directory for deployment:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       zip -r ../my-deployment-package.zip .
       ```

    ## Step 4. Configure AWS

    1. Configure the AWS CLI to authenticate with your AWS account:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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. The Lambda function needs this role to run.

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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"}]}'
       ```

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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

    1. In the deployment package directory, use the AWS CLI to create a Lambda function:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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](#connection-string).
    2. Invoke the function:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       aws lambda invoke \
         --function-name init-crdb out \
         --log-type Tail \
         --query 'LogResult' \
         --output text | base64 -d
       ```

       ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       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
       ```
  </Tab>

  <Tab title="Python">
    The Python function code is located in the `examples-aws-lambda/python` directory and has the following structure:

    ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    ├── 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](https://www.psycopg.org/) PostgreSQL adapter to connect to your cluster.
  </Tab>
</Tabs>

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

1. In the `python` directory, download and install the `psycopg2-binary` Python library:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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.
</Note>

2. Compress the project files to a ZIP file in the parent directory for deployment:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   zip -r ../my-deployment-package.zip my-deployment-package ./init_db.py ./root.crt
   ```

## Step 4. Configure AWS

1. Configure the AWS CLI to authenticate with your AWS account:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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. The Lambda function needs this role to run.

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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"}]}'
   ```

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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

1. In the deployment package directory, use the AWS CLI to create a Lambda function:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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](#connection-string).

<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`.
</Note>

2. Invoke the function:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   aws lambda invoke \
     --function-name init-crdb out \
     --log-type Tail \
     --query 'LogResult' \
     --output text | base64 -d
   ```

   ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   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

* <InternalLink path="build-a-python-app-with-cockroachdb-django">Build a Simple Django App with CockroachDB</InternalLink>

You might also be interested in the following pages:

* <InternalLink path="connection-parameters">Client Connection Parameters</InternalLink>
* <InternalLink path="connection-pooling">Connection Pooling</InternalLink>
* <InternalLink path="demo-replication-and-rebalancing">Data Replication</InternalLink>
* <InternalLink path="demo-cockroachdb-resilience">CockroachDB Resilience</InternalLink>
* <InternalLink path="demo-replication-and-rebalancing">Replication & Rebalancing</InternalLink>