Database Triggers¶

Overview¶

Database Triggers allow you to execute server-side logic whenever a document is added, updated, or removed in a linked MongoDB Atlas cluster. You can use database Triggers to implement complex data interactions, including updating information in one document when a related document changes or interacting with a service upon the insertion of a new document.

Database Triggers use MongoDB change streams to listen for changes to documents in a collection and pass database events to their associated Trigger function.

Example¶

An online store wants to notify its customers whenever one of their orders changes location. They record each order in the store.orders collection as a document that resembles the following:

{
  _id: ObjectId("59cf1860a95168b8f685e378"),
  customerId: ObjectId("59cf17e1a95168b8f685e377"),
  orderDate: ISODate("2018-06-26T16:20:42.313Z"),
  shipDate: ISODate("2018-06-27T08:20:23.311Z"),
  orderContents: [
    { qty: 1, name: "Earl Grey Tea Bags - 100ct", price: NumberDecimal("10.99") }
  ],
  shippingLocation: [
    { location: "Memphis", time: ISODate("2018-06-27T18:22:33.243Z") },
  ]
}

To automate this process, the store creates a database Trigger that listens for UPDATE change events in the store.orders collection. When the trigger observes an UPDATE event, it passes the change event object to its associated Function, textShippingUpdate. The Function checks the change event for any changes to the shippingLocation field and, if it was updated, sends a text message to the customer with the new location of the order.

exports = async function (changeEvent) {
  // Destructure out fields from the change stream event object
  const { updateDescription, fullDocument } = changeEvent;
  // Check if the shippingLocation field was updated
  const updatedFields = Object.keys(updateDescription.updatedFields);
  const isNewLocation = updatedFields.some(field =>
    field.match(/shippingLocation/)
  );
  // If the location changed, text the customer the updated location.
  if (isNewLocation) {
    const { customerId, shippingLocation } = fullDocument;
    const twilio = context.services.get("myTwilioService");
    const mongodb = context.services.get("mongodb-atlas");
    const customers = mongodb.db("store").collection("customers");
    const { location } = shippingLocation.pop();
    const customer = await customers.findOne({ _id: customer_id })
    twilio.send({
      to: customer.phoneNumber,
      from: context.values.get("ourPhoneNumber"),
      body: `Your order has moved! The new location is ${location}.`
    });
  }
};

Configuration¶

Database Triggers have the following configuration options:

{
  "updateDescription.updatedFields.status": {
    "$exists": true
  }
}

{
  "_id": 0,
  "operationType": 1,
  "updateDescription.updatedFields.status": 1
}

{
  "operationType": "update",
  "updateDescription": {
    "updatedFields": {
      "status": "InProgress"
    }
  }
}

Database Change Events¶

Database change events represent individual changes in a specific collection of your linked MongoDB Atlas cluster.

Every database event has the same operation type and structure as the change event object that was emitted by the underlying change stream. Change events have the following operation types:

Database change event objects have the following general form:

{
   _id : <ObjectId>,
   "operationType": <string>,
   "fullDocument": <document>,
   "fullDocumentBeforeChange": <document>,
   "ns": {
      "db" : <string>,
      "coll" : <string>
   },
   "documentKey": {
     "_id": <ObjectId>
   },
   "updateDescription": <document>,
   "clusterTime": <Timestamp>
}

Suspended Triggers¶

Database Triggers may enter a suspended state in response to an event that prevents the Trigger's change stream from continuing. Events that can suspend a Trigger include:

• invalidate events such as dropDatabase, renameCollection, or those caused by a network disruption
• the token required to resume the change stream is no longer in the cluster oplog
• importing a Realm app with the replace strategy instead of the merge strategy and consequently removing the database user that created the Trigger's change stream

When resuming the suspended Trigger, Realm attempts to resume the Trigger at the next change stream event after the change stream stopped. However, if the resume token is no longer in the cluster oplog, the Trigger begins listening to new events but does not process any missed past events. You can adjust your oplog size to keep the resume token around for more time after a suspension.