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

# Operator-managed MongoDB Connector

<Info>
  Operator-managed MongoDB Connector is available starting with Operator version 0.10.0.
</Info>

The MongoDB Connector provides seamless bidirectional synchronization between Ditto apps and MongoDB databases.

To learn more about how the MongoDB Connector works and its use cases, see [MongoDB Connector](/cloud/mongodb-connector).

## Prerequisites

Before setting up the MongoDB Connector, ensure you have:

1. Prepared a MongoDB database (see [MongoDB Connector prerequisites](/cloud/mongodb-connector#pre-requisites))
2. Deployed a Big Peer using the Ditto Operator (version 0.10.0 or above)
3. Created a Big Peer App

## Creating a MongoDB Connector

The examples in this guide assume you have followed the [quickstart guide](../operator-quickstart) and have a Big Peer and App deployed.

To create a MongoDB Connector, you can create your connector using the `BigPeerDataBridge` CRD.

<Note>
  `BigPeerDataBridge` resources must include both the `ditto.live/app: <big-peer-app-name>` and `ditto.live/big-peer: <big-peer-name>` labels.
</Note>

### Connection String Options

You can provide the MongoDB connection string in two ways:

#### Option 1: Using a Kubernetes Secret

```bash theme={null}
cat <<'EOF' | kubectl apply -f -
---
# Create a Kubernetes Secret containing the MongoDB connection string.
apiVersion: v1
kind: Secret
metadata:
  name: example-mongo-connector
  namespace: ditto
stringData:
  connectionString: mongodb://username:password@mongodb-host:27017/test-db?authSource=admin
---
# Create a Mongo Connector using Kubernetes Secret reference.
apiVersion: ditto.live/v1alpha1
kind: BigPeerDataBridge
metadata:
  labels:
    ditto.live/app: example-app
    ditto.live/big-peer: example
  name: example-mongo-connector
  namespace: ditto
spec:
  bridge:
    mongoConnector:
      connectionSecret:
        kubernetesSecret:
          name: example-mongo-connector
      database: test-db
      collections:
        tasks:
          fields:
          - _id
          initialSync: true
          mode: ejson
          dqlStrictMode: false
  description: MongoDB Connector for syncing tasks collection.
EOF
```

#### Option 2: Using AWS Secrets Manager

For cloud deployments, you can reference a secret stored in AWS Secrets Manager:

```bash theme={null}
cat <<'EOF' | kubectl apply -f -
---
# Create a Mongo Connector using AWS Secrets Manager reference.
apiVersion: ditto.live/v1alpha1
kind: BigPeerDataBridge
metadata:
  labels:
    ditto.live/app: example-app
    ditto.live/big-peer: example
  name: example-mongo-connector
  namespace: ditto
spec:
  bridge:
    mongoConnector:
      connectionSecret:
        awsSecretsManager:
          secretId: dittocluster/app-id/mongo-connector
          roleArn: arn:aws:iam::123456789012:role/dittocluster/mongo-connector-app-id
          region: us-east-1
      database: test-db
      collections:
        tasks:
          fields:
          - _id
          initialSync: true
          mode: ejson
          dqlStrictMode: false
  description: MongoDB Connector for syncing tasks collection.
EOF
```

## Configuration Options

### Collection Mappings

The `collections` section specifies how MongoDB collections are synchronized with Ditto:

```yaml theme={null}
collections:
  tasks:
    fields:
    - _id
    initialSync: true
    mode: ejson
    dqlStrictMode: false
```

#### Required Fields

* **`fields`**: List of MongoDB fields to use for creating the Ditto document ID
  * Can be a single field: `fields: [_id]`
  * Or multiple fields: `fields: [id, locationId]`
  * These fields must be immutable and always present in MongoDB documents
  * See [ID Mapping Between Systems](/cloud/mongodb-connector#id-mapping-between-systems) for details

#### Optional Fields

* **`initialSync`**: (boolean, default: `false`)
  * When `true`, syncs pre-existing MongoDB documents to Ditto on first connection
  * When `false`, only syncs new documents created after the connector starts

* **`mode`**: (string, default: `"json"`)
  * `"json"`: Standard JSON representation
  * `"ejson"`: MongoDB Extended JSON format for better type fidelity
  * See [EJSON Mode](/cloud/mongodb-connector#ejson-mode) for details

* **`dqlStrictMode`**: (boolean, default: `true`)
  * Controls DQL strict mode for this collection
  * Must be `false` when using EJSON mode
  * See [DQL Strict Mode](/dql/strict-mode) for details

### Settable Counters

Settable counters allow numeric fields to be incremented or decremented from Ditto while also being directly settable from MongoDB. This is useful for applications where backend systems set absolute values while mobile clients increment/decrement.

See [Settable Counters](/dql/types-and-definitions.mdx) to learn how and when to use Settable Counters in your applications.

To configure settable counters, add the `dittoTypes.settableCounters` array to your collection configuration:

```yaml theme={null}
collections:
  inventory:
    fields: [_id]
    dqlStrictMode: false
    dittoTypes:
      settableCounters:
        - quantity
        - order.qty
```

<Warning>
  Settable counters require `dqlStrictMode: false`.
</Warning>

#### How It Works

**Bidirectional sync behavior:**

* **MongoDB → Ditto**: When you update a number field in MongoDB that's configured as a settable counter, it syncs to Ditto as a settable counter type
* **Ditto → MongoDB**: Settable counter values materialize as regular numbers in MongoDB

**DQL operations** you can use with settable counters:

```sql theme={null}
-- Increment or decrement
UPDATE inventory APPLY quantity INCREMENT BY -5

-- Set to specific value
UPDATE inventory APPLY quantity RESTART WITH 25

-- Reset to 0
UPDATE inventory APPLY quantity RESTART
```

#### Behavior Notes

* All writes from MongoDB are treated as "reset" operations
* "Reset" wins over increment/decrement in conflict resolution
* You can specify nested paths like `order.qty` for counters in nested objects

### Multiple Collections

You can configure multiple collections in a single connector:

```yaml theme={null}
collections:
  tasks:
    fields: [_id]
    initialSync: true
    mode: ejson
    dqlStrictMode: false
  users:
    fields: [userId]
    initialSync: false
    mode: json
    dqlStrictMode: true
  orders:
    fields: [orderId, storeId]
    initialSync: true
    mode: ejson
    dqlStrictMode: false
```

## Verifying Your Setup

After creating the MongoDB Connector, verify it's running correctly:

### Check Pod Status

```bash theme={null}
kubectl get pods -n ditto -l ditto.live/app=example-app
```

You should see the MongoDB Connector pod in a `Running` state.

### Test Bidirectional Sync

#### Ditto → MongoDB

Insert a document via the [HTTP API](../operator-quickstart#using-the-big-peer-http-api):

```bash theme={null}
curl -X POST http://localhost/2164bef3-37c0-489c-9ac6-c94b034525d7/api/v4/store/execute \
  --header "Authorization: bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "statement": "INSERT INTO tasks DOCUMENTS (:doc1)",
    "args": {
      "doc1": {
        "_id": "task-001",
        "title": "Complete documentation",
        "status": "active"
      }
    }
  }'
```

Verify it appears in MongoDB:

```bash theme={null}
mongosh "mongodb://username:password@hostname:port/test-db"
> db.tasks.findOne({_id: "task-001"})
```

#### MongoDB → Ditto

Insert a document directly in MongoDB:

```javascript theme={null}
db.tasks.insertOne({
  _id: "task-002",
  title: "Review PR",
  status: "pending"
})
```

Verify it syncs to Ditto via a DQL query through the HTTP API:

```bash theme={null}
curl -X POST http://localhost/2164bef3-37c0-489c-9ac6-c94b034525d7/api/v4/store/execute \
  --header "Authorization: bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "statement": "SELECT * FROM tasks WHERE _id = '\''task-002'\''"
  }'
```

## Troubleshooting

### Check Connector Logs

```bash theme={null}
kubectl logs -n ditto -l ditto.live/app=example-app
```

Look for connection errors or synchronization issues.

### Common Issues

**Connection failures**: Verify your MongoDB connection string is correct and that network policies allow traffic from your Kubernetes cluster to MongoDB.

**Document not syncing**: Ensure the document includes all fields specified in the `fields` configuration.

**EJSON errors**: When using EJSON mode, ensure `dqlStrictMode` is set to `false`.

For more troubleshooting guidance, see [MongoDB Connector Troubleshooting](/cloud/mongodb-connector#troubleshooting-connectivity).

## Deleting a MongoDB Connector

To delete a MongoDB Connector:

```bash theme={null}
kubectl delete bigpeerdatabridge example-mongo-connector
```

This will stop synchronization and remove the connector pod.

## Legacy Helm-based Deployment

If you're using an older version of the Operator or need to use the Helm-based MongoDB Connector deployment, see [Legacy Helm-based MongoDB Connector](/ditto-server/operator/connectors/mongodb-legacy-helm).