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

# Connectors: Broker and Database Connections in Devset

> Connectors are named, reusable configurations for Kafka, RabbitMQ, and MongoDB. Workflows and stages reference them by name to reach your infrastructure.

A connector is a named connection configuration that tells Devset how to reach a broker or database. Rather than embedding connection details directly in a workflow, you define connectors once and reference them by name from any number of workflows. This keeps sensitive credentials out of your workflow documents and lets you switch environments — for example from a local broker to a staging cluster — by updating a single connector instead of every workflow that uses it.

Devset supports three connector types: **Kafka**, **RabbitMQ**, and **MongoDB**.

<Note>
  Connector names must be unique within each connector type. A Kafka connector and a MongoDB connector can share the same name, but two Kafka connectors cannot.
</Note>

## Kafka Connector

A Kafka connector specifies the bootstrap servers Devset uses to connect to your Kafka cluster.

**Fields:**

<ParamField path="name" type="string" required>
  A unique name for this connector. This is the value you set in `producerName` on a Kafka workflow.
</ParamField>

<ParamField path="bootstrapServers" type="string" required>
  A comma-separated list of `host:port` addresses for one or more Kafka brokers. For example: `localhost:9092` or `broker1:9092,broker2:9092`.
</ParamField>

**Example:**

```json theme={null}
{
  "name": "local-kafka",
  "bootstrapServers": "localhost:9092"
}
```

**Multi-broker cluster:**

```json theme={null}
{
  "name": "staging-kafka",
  "bootstrapServers": "broker1.staging.internal:9092,broker2.staging.internal:9092"
}
```

## RabbitMQ Connector

A RabbitMQ connector provides the host, port, virtual host, and credentials needed to open an AMQP connection.

**Fields:**

<ParamField path="name" type="string" required>
  A unique name for this connector. This is the value you set in `producerName` on a RabbitMQ workflow.
</ParamField>

<ParamField path="host" type="string" required>
  The hostname or IP address of the RabbitMQ server, for example `localhost` or `rabbit.staging.internal`.
</ParamField>

<ParamField path="port" type="integer" required>
  The AMQP port. The default RabbitMQ port is `5672`; TLS connections typically use `5671`.
</ParamField>

<ParamField path="virtualHost" type="string" required>
  The RabbitMQ virtual host to connect to. Use `"/"` for the default virtual host.
</ParamField>

<ParamField path="username" type="string" required>
  The username for AMQP authentication.
</ParamField>

<ParamField path="password" type="string" required>
  The password for AMQP authentication.
</ParamField>

**Example:**

```json theme={null}
{
  "name": "local-rabbit",
  "host": "localhost",
  "port": 5672,
  "virtualHost": "/",
  "username": "guest",
  "password": "guest"
}
```

## MongoDB Connector

A MongoDB connector is used by stage `query` blocks to execute lookups during workflow execution. It is not a broker connector and is not referenced by `producerName`.

**Fields:**

<ParamField path="name" type="string" required>
  A unique name for this connector. This is the value you set in `query.connection` on a stage.
</ParamField>

<ParamField path="connectionString" type="string" required>
  A MongoDB connection URI, for example `mongodb://localhost:27017`. Supports replica set URIs and Atlas connection strings.
</ParamField>

<ParamField path="database" type="string" required>
  The default database to connect to. This can be overridden per query in the stage's `query.database` field.
</ParamField>

<ParamField path="username" type="string">
  The username for MongoDB authentication. Leave empty when authentication is handled by the connection string or when connecting without credentials.
</ParamField>

<ParamField path="password" type="string">
  The password for MongoDB authentication. Leave empty when authentication is handled by the connection string.
</ParamField>

**Example:**

```json theme={null}
{
  "name": "local-mongo",
  "connectionString": "mongodb://localhost:27017",
  "database": "shop",
  "username": "devset",
  "password": "devset"
}
```

## Referencing a Connector in a Workflow

Broker connectors (Kafka and RabbitMQ) are referenced in the workflow's top-level `producerName` field. The value must exactly match the `name` of a configured connector of the matching type:

```json theme={null}
{
  "id": "user-signup-flow",
  "messageType": "kafka",
  "contentType": "application/json",
  "producerName": "local-kafka",
  "topic": "user-events",
  "executions": 5,
  "state": {},
  "pipeline": [...]
}
```

MongoDB connectors are referenced inside individual stage `query` blocks using the `connection` field:

```json theme={null}
{
  "stage": "lookup-product",
  "query": {
    "connection": "local-mongo",
    "database": "shop",
    "collection": "products",
    "find": { "active": true },
    "select": { "productId": 1, "price": 1 }
  },
  "set": {
    "productId": { "$path": "state.query.result.productId" }
  },
  "emit": true
}
```

<Tip>
  Use consistent naming conventions for your connectors — for example `local-kafka`, `staging-kafka`, `prod-kafka` — so that switching a workflow between environments is as simple as changing the `producerName` value.
</Tip>

## Managing Connectors

Open the Settings UI at **`/settings`** in the Devset UI to create, edit, and delete connectors. You can also manage connectors programmatically using the Devset API.

**To add a connector:**

1. Navigate to `/settings`.
2. Select the connector type tab: **Kafka**, **RabbitMQ**, or **MongoDB**.
3. Click **Add Connector**.
4. Fill in the required fields and click **Save**.

**To edit a connector:**
Select the connector from the list, update the fields, and save. All workflows that reference the connector by name will use the updated configuration on their next run.

**To delete a connector:**
Select the connector and click **Delete**. Workflows that reference a deleted connector name will fail at runtime. Update or remove the `producerName` reference in any affected workflows before deleting.

<Warning>
  Deleting a connector does not update the workflows that reference it. Audit your workflows before removing a connector to avoid runtime failures.
</Warning>