# Connection pools

## Introduction

Many APIs enforce *rate limits* for the number of requests that can be made in a given period - typically per minute. Others (e.g. NetSuite) set *concurrency limits* to determine the number of requests that can be made simultaneously. As with rate limiting, exceeding a concurrency limit can result in delays, throttling, or errors (depending on the system).

In this scenario, we need a way to ensure that requests are only activated when we know that the concurrency limit won't be exceeded. For example, if our concurrency limit is `5` and 5 requests are active, we want to ensure that request number 6 is not made until there's a free 'slot'. 

To achieve this, we use *connection pools*. 

## How it works

Connection pools are created with required concurrency limits and then assigned to [connector instances](/product-documentation/connectors-and-instances/working-with-instances.md). When one of these instances is configured in a process flow connector step, any requests are handled by the associated connection pool. 

When a request is made, the connection pool limit is checked. If there's a free slot  (i.e. the concurrency limit has NOT been reached), a slot is held and the request is sent. Once that request is complete, the slot is released. The illustration below shows how this works:

<figure><img src="/files/7JwY4QOSNW5qDEC33xR8" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
A single connection pool can be associated with a single instance; multiple instances of the same connector, or even multiple instances across different connectors.&#x20;
{% endhint %}

{% hint style="info" %}
Connection pools are not used for [database connectors](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/configuring-a-database-connection.md).
{% endhint %}

## Connection pools & rate limits

*Connection pools* and *rate limits* work together. *Rate limiting* controls the number of API calls or requests that can be made within a set time frame (e.g. per minute), whereas *connection pools* manage the number of simultaneous connections allowed at any given time.&#x20;

#### Example

Suppose the `rate limit` for a connector instance allows up to `60` API calls per minute, but there's a *concurrency limit* of *10*.&#x20;

If you associate this connector instance with a *connection pool* configured with a `limit` of `10`, only 10 connections can be active at once - even though the `rate limit` allows more requests per minute.&#x20;

So, if all 10 connections are in use, additional calls will wait until a connection slot becomes available - even if you’re still under the rate limit. However, if the 10 concurrent connections are fast enough, you may hit your `rate limit` (60 calls per minute).

## Accessing connection pools

To access existing connection pools for your company profile, select the **connection pools** option from the left-hand navigation menu:

<div align="left"><figure><img src="/files/T6tEcjVVFsBnksbdvOpm" alt="" width="192"><figcaption></figcaption></figure></div>

## Creating a connection pool

To create a new connection pool, follow the steps below:

**Step 1**\
[Access the connection pools page](#accessing-connection-pools):

<figure><img src="/files/PDCmCjCx0iKAxrdR8wak" alt=""><figcaption></figcaption></figure>

**Step 2**\
Click the **create** button:

<figure><img src="/files/ZtOvbIHPrpEB2ggDYz1i" alt=""><figcaption></figcaption></figure>

**Step 3**\
Enter details for this connection pool:

<div align="left"><figure><img src="/files/iZdYcWukWbeDE3ohPdOr" alt=""><figcaption></figcaption></figure></div>

Available settings are summarised below:

<table><thead><tr><th width="250">Field</th><th>Summary</th></tr></thead><tbody><tr><td>Name</td><td>Enter a name for this connection pool. This name is displayed wherever this pool is used in the system.</td></tr><tr><td>Limit</td><td>Enter the number of concurrent requests that can be made when this pool is used. </td></tr><tr><td>Timeout </td><td>If appropriate, enter the number of seconds that requests should wait for a connection pool slot to become available before timing out. The default timeout is <code>30 seconds</code> - this is applied if nothing is defined here. The maximum timeout allowed is <code>300 seconds</code>.</td></tr></tbody></table>

**Step 4**\
Click the **create** button.

## Updating an existing connection pool

If you change the settings for an existing connection pool (for example, increase or decrease the **limit**), those changes are automatically picked up in any process flow connection steps that use this pool.

&#x20;To update an existing connection pool, follow the steps below:

**Step 1**\
[Access the connection pools page](#accessing-connection-pools):

<figure><img src="/files/PDCmCjCx0iKAxrdR8wak" alt=""><figcaption></figcaption></figure>

**Step 2**\
Click the name of the connection pool that you want to update:

<figure><img src="/files/saGkAjfAMTPcgeglkWKW" alt=""><figcaption></figcaption></figure>

**Step 3**\
Update details as required, then click the **update** button:

<div align="left"><figure><img src="/files/w3Pp0agtG5ueoscYZq7G" alt=""><figcaption></figcaption></figure></div>

## Clearing a connection pool

There may be times when you need to clear requests from a connection pool - for example, if you're testing a process flow and want to start again.&#x20;

{% hint style="danger" %}
If your connection pool is associated with live, production instances, use this option carefully. Clearing a connection pool clears all pending requests.&#x20;
{% endhint %}

To clear a connection pool, follow the steps below:

**Step 1**\
[Access the connection pools page](#accessing-connection-pools):

<figure><img src="/files/PDCmCjCx0iKAxrdR8wak" alt=""><figcaption></figcaption></figure>

**Step 2**\
Click the 'clear' icon associated with the connection pool you want to update:

<figure><img src="/files/ODlppzRoR9kEMqv13sj2" alt=""><figcaption></figcaption></figure>

**Step 3**\
When prompted, confirm that you would like to clear all existing requests from this connection pool:

<div align="left"><figure><img src="/files/32VJNTxuGJIdUpsheR9z" alt="" width="291"><figcaption></figcaption></figure></div>

## Removing a connection pool

If necessary, you can delete an existing connection pool at any time. If you remove a connection pool that's associated with connector instances, it is removed from those automatically (so you would need to [reconfigure your instances with alternative connection pools](#associating-connection-pools-with-connector-instances), if required).

## Associating connection pools with connector instances

Existing connection pools can be associated with connector instances when you [add a new instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) or [update an existing instance](/product-documentation/connectors-and-instances/working-with-instances/updating-an-instance.md). For example:

<div align="left"><figure><img src="/files/JDWz4jdNff02Q8ErKWu9" alt="" width="563"><figcaption></figcaption></figure></div>

## Removing a connection pool association with connector instances

To remove a connection pool association from an instance, you should [edit the instance](/product-documentation/connectors-and-instances/working-with-instances/updating-an-instance.md) and click the 'cross' icon for the existing connection pool. For example:

<div align="left"><figure><img src="/files/NVRNGPob5UYtAknGBNcq" alt="" width="563"><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/connection-pools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.