IntegrationsDatabasesMongoDB

MongoDB

Datafly Signal inserts first-party events as documents into a MongoDB collection — ideal for schema-agnostic NoSQL storage with rich querying, aggregation, and indexing.

Prerequisites

Before configuring MongoDB in Signal, you need a MongoDB instance (self-hosted or Atlas), a database and collection, and a connection URI.

Set Up a MongoDB Instance

You have two options:

Option A: MongoDB Atlas (Managed)

  1. Sign up at mongodb.com/cloud/atlas.
  2. Create a new project and click Build a Cluster.
  3. Choose a tier:
    • M0 (Free) — suitable for development and testing.
    • M10+ — production-ready with dedicated resources.
  4. Select a cloud provider and region.
  5. Click Create Cluster.

Option B: Self-Hosted MongoDB

  1. Install MongoDB using the official guide.
  2. Start the mongod process.
  3. Ensure the server is accessible from your Signal infrastructure.

Configure Network Access (Atlas)

  1. In Atlas, go to Network Access > Add IP Address.
  2. Add the IP addresses of your Signal deployment.
  3. Click Confirm.
⚠️

Never whitelist 0.0.0.0/0 (allow from anywhere) in production. Restrict access to only your Signal infrastructure IP addresses.

Create a Database User

For Atlas:

  1. Go to Database Access > Add New Database User.
  2. Choose Password authentication.
  3. Enter a Username (e.g. datafly_signal) and Password.
  4. Under Database User Privileges, select Read and write to any database or restrict to a specific database with readWrite role.
  5. Click Add User.

For Self-Hosted:

use admin
db.createUser({
  user: "datafly_signal",
  pwd: "your_secure_password",
  roles: [
    { role: "readWrite", db: "datafly_events" }
  ]
})

Get the Connection URI

For Atlas:

  1. In your cluster, click Connect > Connect your application.
  2. Select Driver: Node.js (or any driver — the URI format is the same).
  3. Copy the Connection string (e.g. mongodb+srv://datafly_signal:password@cluster0.abc123.mongodb.net/datafly_events).
  4. Replace <password> with the actual password.

For Self-Hosted:

The URI format is: mongodb://datafly_signal:password@hostname:27017/datafly_events

Create a Database and Collection

MongoDB creates databases and collections automatically on first write. However, you can create them explicitly:

use datafly_events
db.createCollection("events")
db.events.createIndex({ "timestamp": -1 })
db.events.createIndex({ "type": 1, "event": 1 })

Creating indexes in advance improves query performance. The timestamp descending index is useful for retrieving recent events, and the compound index on type and event optimises filtered queries.

Configuration

FieldTypeRequiredDescription
urisecretYesThe MongoDB connection string (e.g. mongodb+srv://user:pass@cluster.mongodb.net/dbname). Also accepts connection_uri.
databasestringYesThe target database name.
collectionstringYesThe target collection name to insert documents into.

Signal Setup

Quick Setup

  1. Navigate to Integrations in the sidebar.
  2. Open the Integration Library tab.
  3. Find MongoDB or filter by Database.
  4. Click Install, select a variant if available, and fill in the required fields.
  5. Click Install Integration to create the integration with a ready-to-use default blueprint.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/mongodb/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MongoDB",
    "variant": "default",
    "config": {
      "uri": "mongodb+srv://datafly_signal:your_password@cluster0.abc123.mongodb.net/datafly_events",
      "database": "datafly_events",
      "collection": "events"
    },
    "delivery_mode": "server_side"
  }'

Schema

Each event becomes one BSON document with the canonical envelope as top-level fields:

{
  "_id": ObjectId("..."),
  "event_id": "...",
  "type": "track",
  "event": "order_completed",
  "anonymous_id": "...",
  "user_id": "...",
  "timestamp": ISODate("..."),
  "received_at": ISODate("..."),
  "sent_at": ISODate("..."),
  "context":    { ... },
  "properties": { ... },
  "traits":     { ... },
  "source_id": "...",
  "integration_id": "..."
}

Add indexes on event_id (unique, for dedupe), timestamp (descending, for recent-event queries), and (type, event) (compound, for filtered queries).

Consent

MongoDB is a first-party destination under your control. The default blueprint forwards all events. Apply consent filtering via pipeline transforms or via aggregation $match stages on context.consent if your governance requires it.

Testing

  1. Enable the integration in Signal and trigger a test event on your website.
  2. Connect to your MongoDB instance and query the collection:
use datafly_events
db.events.find().sort({ timestamp: -1 }).limit(10)
  1. Or in Atlas, use the Browse Collections interface to view documents.
  2. In Signal, check the Live Events view to confirm delivery status shows as successful.

Troubleshooting

ProblemSolution
Events not appearing in the collectionVerify the connection URI, database, and collection name are correct.
Authentication failedThe username or password in the connection URI is incorrect. Verify the database user credentials.
Connection timeoutCheck that Signal’s IP addresses are whitelisted in Atlas Network Access (or firewall rules for self-hosted). Verify DNS resolution.
not authorized on databaseThe database user lacks readWrite permission on the database. Update the user’s roles in Database Access.
MongoServerSelectionErrorThe connection string may be incorrect or the cluster is unreachable. Check the URI format and network connectivity.
Document too largeMongoDB documents cannot exceed 16 MB. Check the event payload size.
Write concern errorsIf using replica sets, verify the write concern configuration. Default write concern (w:1) is sufficient for most use cases.

Visit MongoDB documentation for full query reference, aggregation pipeline guides, and Atlas management.

See also

Google SpannerMySQL