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

# Serverless Function Best Practices

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 page provides best practices for optimizing the performance of serverless functions (e.g., [AWS Lambda functions](https://aws.amazon.com/lambda) and [Google Cloud Functions](https://cloud.google.com/functions)) that connect to CockroachDB.

## Use connection pools

Use connection pools to manage the lifecycle of database connections established by serverless functions. Connection pools health-check connections and re-establish broken connections in the event of a communication error.

When creating connection pools in serverless functions:

* Set the maximum connection pool size to 1, unless your function is multi-threaded and establishes multiple concurrent requests to your database within a single function instance.
* Do not set a minimum idle connection count. The connection pool should be free to open connections as needed.
* If supported by your pooling library, set the maximum lifetime on the connection pool to 30 minutes.

## Persist connection pools across function invocations

If you plan to invoke a serverless function at a high frequency, you should configure the function to persist connection pools across function invocations, to limit the number of new connection attempts to the database. This is typically done by initializing the connection pool variable outside the scope of the serverless function definition.

For example, suppose you are writing an AWS Lambda function that <InternalLink path="insert">`INSERT`</InternalLink>s data into a table on a CockroachDB cluster, and you plan to run this query every few seconds. To persist a connection pool across invocations, initialize the connection pool variable outside of the [handler function](https://docs.aws.amazon.com/lambda/latest/dg/foundation-progmodel) definition and then define the connection pool in the handler only if the pool does not already exist.

<Tabs>
  <Tab title="node.JS">
    A node.JS function that implements this pattern could look similar to the following:

    ```js theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    const { Pool } = require('pg')

    let pool

    const insertRows = async (p) => {
      const client = await p.connect()
      try {
        await client.query('INSERT INTO table (col1, col2) VALUES (val1, val2)')
      } catch (err) {
        console.log(err.stack)
      } finally {
        client.release()
      }
    }

    exports.handler = async (context) => {
      if (!pool) {
        const connectionString = process.env.DATABASE_URL
        pool = new Pool({
          connectionString,
          max: 1
        })
      }

      await insertRows(pool)
    }
    ```
  </Tab>

  <Tab title="Python">
    A Python function that implements this pattern could look similar to the following:

    ```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
    from psycopg2.pool import SimpleConnectionPool

    pool = None

    def query(p):
      conn = p.getconn()
      with conn.cursor() as cur:
          cur.execute("INSERT INTO table (col1, col2) VALUES (val1, val2)")
          conn.commit()

    def lambda_handler(context):
        global pool

        if not pool:
            pool = SimpleConnectionPool(0, 1, dsn=os.environ['DATABASE_URL'])

        query(pool)

        return
    ```
  </Tab>
</Tabs>

## Use CockroachDB Standard

As a database-as-a-service, CockroachDB Standard abstracts away the complexity of deploying, scaling, and load-balancing your database. Additionally, idle database connections to CockroachDB use very little memory (\~20-30 KiB) when compared to PostgreSQL (\~2-10 MiB).

To create a free 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.

## Deploy serverless functions in the same region as your database

To minimize network latency, you should deploy your serverless functions in the same region as your database deployment. If your serverless function provider does not offer deployments in the same region as your database deployment, choose the region closest to the region where your database is deployed.

## See also

* <InternalLink path="deploy-lambda-function">Create and Deploy an AWS Lambda Function Built on CockroachDB</InternalLink>
* <InternalLink path="connect-to-the-database">Connect to your Cluster</InternalLink>