Operator-managed MongoDB Connector

Operator-managed MongoDB Connector is available starting with Operator version 0.10.0.

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.

Prerequisites

Before setting up the MongoDB Connector, ensure you have:

Prepared a MongoDB database (see MongoDB Connector prerequisites)
Deployed a Big Peer using the Ditto Operator (version 0.10.0 or above)
Created a Big Peer App

Creating a MongoDB Connector

The examples in this guide assume you have followed the quickstart guide and have a Big Peer and App deployed. To create a MongoDB Connector, you can create your connector using the BigPeerDataBridge CRD.

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

Connection String Options

You can provide the MongoDB connection string in two ways:

Option 1: Using a Kubernetes Secret

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:

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:

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 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 for details
dqlStrictMode: (boolean, default: true)
- Controls DQL strict mode for this collection
- Must be false when using EJSON mode
- See 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 applications where backend systems set absolute values while mobile clients increment/decrement. See Settable Counters 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:

collections:
  inventory:
    fields: [_id]
    dqlStrictMode: false
    dittoTypes:
      settableCounters:
        - quantity
        - order.qty

Settable counters require dqlStrictMode: false.

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:

-- 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:

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

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:

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:

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

MongoDB → Ditto

Insert a document directly in MongoDB:

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

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

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

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.

Deleting a MongoDB Connector

To delete a MongoDB Connector:

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.

Documentation Index

​Prerequisites

​Creating a MongoDB Connector

​Connection String Options

​Option 1: Using a Kubernetes Secret

​Option 2: Using AWS Secrets Manager

​Configuration Options

​Collection Mappings

​Required Fields

​Optional Fields

​Settable Counters

​How It Works

​Behavior Notes

​Multiple Collections

​Verifying Your Setup

​Check Pod Status

​Test Bidirectional Sync

​Ditto → MongoDB

​MongoDB → Ditto

​Troubleshooting

​Check Connector Logs

​Common Issues

​Deleting a MongoDB Connector

​Legacy Helm-based Deployment

Prerequisites

Creating a MongoDB Connector

Connection String Options

Option 1: Using a Kubernetes Secret

Option 2: Using AWS Secrets Manager

Configuration Options

Collection Mappings

Required Fields

Optional Fields

Settable Counters

How It Works

Behavior Notes

Multiple Collections

Verifying Your Setup

Check Pod Status

Test Bidirectional Sync

Ditto → MongoDB

MongoDB → Ditto

Troubleshooting

Check Connector Logs

Common Issues

Deleting a MongoDB Connector

Legacy Helm-based Deployment