> ## 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 a [CockroachDB Cloud](https://cockroachlabs.cloud/signup?referralId=docs_lambda) account.
2. Create an [AWS](https://aws.amazon.com/) account.
3. Create an [AWS user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users) with administrator permissions.
4. Install the [AWS CLI](https://aws.amazon.com/cli).

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

<a id="connection-string" />

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

## Step 2. Get the sample code

Open a terminal window and 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).

<Tabs>
  <Tab title="node.js">
    The Node.js function code is available under the `examples-aws-lambda/node` directory:

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

    This function uses the [node-postgres](https://node-postgres.com/) modules 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.
    </Note>

    1. Navigate to the Node.js function directory:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       cd node
       ```
    2. Install the code dependencies:

       ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
       npm install
       ```
    3. Compress the project files to a ZIP file for deployment:

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

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

       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:

       ```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's code is available under the `examples-aws-lambda/python` directory:

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

    This function uses the [Psycopg2](https://www.psycopg.org/) PostgreSQL adapter to connect to CockroachDB.
  </Tab>
</Tabs>

## Step 3. (Optional) Create the deployment package

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 Python function directory:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cd python
   ```
2. Download and install the `psycopg2-binary` Python library to a new directory:

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

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

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ cd my-package
   ```

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

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ cd ..
   ```

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

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

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

   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:

   ```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`, or in 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>
* <InternalLink path="movr-flask-deployment">Deploy a Global, Serverless Application</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-fault-tolerance-and-recovery">Fault Tolerance & Recovery</InternalLink>
* <InternalLink path="demo-replication-and-rebalancing">Replication & Rebalancing</InternalLink>
* <InternalLink path="demo-automatic-cloud-migration">Cross-Cloud Migration</InternalLink>
* <InternalLink path="orchestrate-a-local-cluster-with-kubernetes-insecure">Automated Operations</InternalLink>