Skip to main content
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:
  1. Prepared a MongoDB database (see MongoDB Connector prerequisites)
  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 and have a Big Peer and App deployed. To create a MongoDB Connector, you can create your connector using the BigPeerDataBridge CRD.

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