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

# Configure and Use MongoDB Database Connectors in Devset

> Create named MongoDB connections in Devset and use them inside workflow stage query blocks to fetch and map data during test runs.

Database connectors let Devset connect to your MongoDB instances so that workflow stages can query live data as part of a test run. Rather than hardcoding a connection string inside every workflow, you register a named connector once and then reference it by name in any query block. This makes it straightforward to reuse the same workflow against different databases — local, shared, or CI — by changing only the connector name.

## Add a Database Connector via the Settings UI

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings** in the Devset UI ([http://localhost:8082](http://localhost:8082)).
  </Step>

  <Step title="Select the Databases tab">
    Click the **Databases** tab. Any connectors you have already created are listed here.
  </Step>

  <Step title="Fill in the connector form">
    Click **Add Connector** and complete the fields for a MongoDB connection. See the field reference below.
  </Step>

  <Step title="Save">
    Click **Save**. The connector is stored in Devset's local SQLite database and is immediately available to workflow definitions.
  </Step>
</Steps>

## MongoDB Connector Field Reference

<ParamField body="type" type="string" required>
  Must be `"mongodb"`. This tells Devset which driver to use when establishing the connection.
</ParamField>

<ParamField body="name" type="string" required>
  A unique identifier for this connector. Workflow query blocks reference this connector by setting `connection` to this value. Use a descriptive slug such as `local-mongo` or `prod-users-db`.
</ParamField>

<ParamField body="connectionString" type="string" required>
  The MongoDB connection URI, for example `mongodb://localhost:27017`. For Atlas or authenticated clusters, include credentials in the URI or use the `username` and `password` fields below.
</ParamField>

<ParamField body="database" type="string">
  The default database to use when a query block does not specify one explicitly. If omitted, the query block must include a `database` field.
</ParamField>

<ParamField body="username" type="string">
  The username for authenticating with MongoDB. Leave blank if authentication is handled through the connection string or if the instance requires no credentials.
</ParamField>

<ParamField body="password" type="string">
  The password for the specified username. Leave blank when authentication is not required.
</ParamField>

## Use a Database Connector in a Workflow Query Block

After saving a connector, reference it inside a workflow stage's `query` block by setting `connection` to the connector's `name`. The query block fetches documents from MongoDB and maps fields into the workflow's state, making the data available to subsequent stages.

```json theme={null}
"query": {
  "connection": "local-mongo",
  "database": "mydb",
  "collection": "users",
  "find": { "id": { "$path": "state.entity.id" } },
  "select": { "entity.name": "name" }
}
```

### Query Block Field Reference

<ParamField body="connection" type="string" required>
  The `name` of the database connector to use for this query.
</ParamField>

<ParamField body="database" type="string">
  The MongoDB database to query. Overrides the default database set on the connector. Required if no default database was configured on the connector.
</ParamField>

<ParamField body="collection" type="string" required>
  The name of the MongoDB collection to query.
</ParamField>

<ParamField body="find" type="object" required>
  A MongoDB filter document. You can use the `$path` operator to resolve values dynamically from the current workflow state. For example, `{ "$path": "state.entity.id" }` substitutes the value of `state.entity.id` at query time.
</ParamField>

<ParamField body="select" type="object">
  A mapping from source document field paths to state keys. Each key is a dot-notated path in the returned document; each value is the key under which that field is stored in the workflow state. For example, `{ "entity.name": "name" }` reads `entity.name` from the document and stores it as `name` in the workflow state.
</ParamField>

<Note>
  The `find` filter uses standard MongoDB query operators. The `$path` operator is a Devset-specific extension that lets you inject runtime state values into the filter before the query is sent to MongoDB.
</Note>

## API Reference

You can manage database connectors programmatically using the Devset REST API.

### Create a Database Connector

```bash theme={null}
curl -X POST http://localhost:8082/db/connectors/configurations \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mongodb",
    "name": "local-mongo",
    "connectionString": "mongodb://localhost:27017",
    "database": "mydb"
  }'
```

### List All Database Connectors

```bash theme={null}
curl http://localhost:8082/db/connectors/configurations
```

### Delete a Database Connector

Replace `{type}` with `mongodb` and `{name}` with the connector's name.

```bash theme={null}
curl -X DELETE http://localhost:8082/db/connectors/configurations/mongodb/local-mongo
```

<Warning>
  Deleting a connector does not update workflow definitions that reference it. Workflows with a `query` block pointing to a deleted connector will fail at runtime. Remove or update those references before deleting the connector.
</Warning>