> For the complete documentation index, see [llms.txt](https://manual.bubble.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.bubble.io/help-guides/logic/workflows/events/backend-events/database-trigger-events.md).

# Database trigger events

Database trigger events run a workflow when data in your database changes. Learn how to set one up, compare a thing before and after a change, and avoid common pitfalls.

Database trigger events are a type of [backend event](#user-content-fn-1)[^1] that watches your database. Whenever a thing of the type you choose is created, changed, or deleted, Bubble takes notice, and a [dynamic expression](#user-content-fn-2)[^2] lets you decide exactly what *kind* of change should run the workflow.

Since they react to the data itself, they run no matter where the change came from: a workflow, an API call, or a manual edit in the **Data** tab.

***

## Creating a database trigger event

Let's walk through an example. We want to run a workflow whenever a user changes their email address.

Database trigger events are part of your app's backend, so you set them up in the **Backend workflows** tab. If you can't see the tab, you may need to [enable backend workflows](https://manual.bubble.io/help-guides/logic/the-frontend-and-backend.md#enabling-backend-workflows) first.

{% stepper %}
{% step %}

#### Create the event

In the **Backend workflows** tab, add a new workflow and select the *A thing is modified* event.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FtkPXwJGCq0MNE2rE3pDh%2Fa-thing-is-modified.png?alt=media&amp;token=fc559e33-f607-49d4-84d8-5e7b4b30e311" alt="The event menu with the General category expanded, listing API workflow, Recurring event, and A thing is modified."><figcaption><p>Database trigger events are listed as <em>A thing is modified</em>.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Pick the data type

Bubble displays the properties of the new event. In the *Type* field, pick the data type you want the event to watch. Since we're looking for users who change their email, we'll set it to *User*.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FeKeJizHBwXQXvtRizj8H%2Fa-user-is-changed.png?alt=media&amp;token=ef795738-a855-45f1-b0ac-f904988a7734" alt="A database trigger event called A User is modified, with its properties open, the Type set to User, and an empty Only when field."><figcaption><p>The <em>Type</em> field tells Bubble what to watch.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Build the expression

In the *Only when* field, build the expression that tells Bubble what kind of change to respond to. We'll look at that next.
{% endstep %}
{% endstepper %}

### Building the expression

Expressions in database trigger events look much like expressions elsewhere in Bubble, but the *Only when* field on the event only gives you two [data sources](#user-content-fn-3)[^3]. The full list is available in the actions the event runs.

<table><thead><tr><th width="200.10546875">Data source</th><th>What it returns</th></tr></thead><tbody><tr><td><code>Thing before change</code></td><td>The thing as it looked <strong>before</strong> the change</td></tr><tr><td><code>Thing now</code></td><td>The thing as it looks <strong>after</strong> the change</td></tr></tbody></table>

"Thing" changes to match your data type, so in our example you'll see `User before change` and `User now`.

This is the clever part: The event gives you the same user at two moments in time, in the same workflow. That means you can compare[^4] the two. If the email from before the change isn't the same as the email now, the user has changed it:

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2Fz19FEhud2r2mYcT76vcw%2Fuser-changed-email-expression.png?alt=media&amp;token=e8c105f0-fd6b-49e2-8679-f7ec8a86caf1" alt="A database trigger event with the condition User before change&#x27;s email is not User now&#x27;s email in its Only when field."><figcaption><p>The workflow only runs if the email has changed.</p></figcaption></figure>

In this expression, `User before change` and `User now` are data sources, `email` is an operator, and `is not` is the comparison.

{% hint style="info" %}
Comparing the *before* and *now* values helps you catch the exact moment something changes. Let's say you want to send an email when an order is completed. If you only check `Order now's Completed purchase is yes`, the workflow may run again every time any other field on a completed order is updated. `Order before change's Completed purchase is no and Order now's Completed purchase is yes` only runs once.
{% endhint %}

### Checking whether a thing was created or deleted

Database trigger events also fire when a thing is created or deleted. You can use the two data sources to tell which one happened:

<table><thead><tr><th width="122.19140625">Change</th><th width="336.12890625">What happens</th><th>Condition to use</th></tr></thead><tbody><tr><td>Created</td><td>There's no earlier version, so <code>Thing before change</code> returns an empty value.</td><td><code>Thing before change is empty</code></td></tr><tr><td>Deleted</td><td>The thing is gone, so <code>Thing now</code> returns an empty value.</td><td><code>Thing now is empty</code></td></tr></tbody></table>

***

## Understanding database trigger events

### The event checks every change

A database trigger event looks at *any* change to its data type. Bubble then checks the *Only when* expression and stops the rest of the workflow from running if it returns *no*.

That's useful to know for two reasons:

* A database trigger event without an *Only when* expression runs on every single change to that data type.
* Workflows started by triggers use server capacity like any other workflow, so a lot of triggers without conditions can use more [workload](https://manual.bubble.io/help-guides/workload.md) than you intended. Strict *Only when* expressions help you avoid that.

### Limitations of database trigger events

Database trigger events come with some built-in limitations:

<table><thead><tr><th width="258.7265625">Limitation</th><th>What it means</th></tr></thead><tbody><tr><td>They run with full administrative privileges</td><td>You can use <code>Current User</code> to see which user, if any, started the change. But <a href="https://manual.bubble.io/help-guides/data/the-database/protecting-data-with-privacy-rules.md">privacy rules</a> aren't applied while the trigger runs, so searches return all results, not just what the current user is allowed to see.</td></tr><tr><td>One trigger won't start another</td><td>If a database trigger event makes changes to a thing, those changes don't trigger a second event, or the same one again. Otherwise, you could end up in an eternal loop.</td></tr><tr><td>Several changes only trigger once</td><td>If a workflow changes the same thing several times, the event only fires once. <code>Thing before change</code> shows the thing before any of the changes, and <code>Thing now</code> shows it after the last one.</td></tr><tr><td>Only 20 run at once</td><td>If more than 20 database triggers kick off at once, the rest are scheduled, to protect your app's infrastructure.</td></tr></tbody></table>

{% hint style="warning" %}
To make a trigger start a second event, you can move the actions into an [API workflow](#user-content-fn-5)[^5] or a custom event, and schedule that from the trigger. Any change made by that workflow triggers as expected. Be careful, though: This uses more workload, and it can set up a loop of workflows that spends a lot of resources.
{% endhint %}

***

## Plan database trigger events with Bubble AI

Database trigger events aren't on the list of things the [Bubble AI Agent](https://manual.bubble.io/help-guides/ai/bubble-ai-agent.md) can [build in backend workflows](https://manual.bubble.io/help-guides/ai/bubble-ai-agent/edit-apps-with-ai.md#generate-and-modify-backend-workflows). You can still ask it to explain how to set one up, and to help you think through the condition.

Here are a few prompts to try:

{% code overflow="wrap" %}

```
Explain how to set up a database trigger event that runs when an order is completed.
```

{% endcode %}

{% code overflow="wrap" %}

```
Which condition should I use to run a database trigger event only when a user's email changes?
```

{% endcode %}

{% code overflow="wrap" %}

```
Explain what this database trigger event does.
```

{% endcode %}

**Article:** [Edit apps with AI](https://manual.bubble.io/help-guides/ai/bubble-ai-agent/edit-apps-with-ai.md)

***

## FAQ: Database trigger events

<details>

<summary>Do database trigger events run when I change data in the Data tab?</summary>

Yes. They run regardless of how the change was made, including a manual edit in the **Data** tab.

</details>

<details>

<summary>How do I check whether a thing was created or deleted?</summary>

A created thing has an empty `Thing before change`, and a deleted thing has an empty `Thing now`. See [Checking whether a thing was created or deleted](#checking-whether-a-thing-was-created-or-deleted).

</details>

<details>

<summary>Why isn't my database trigger event starting another one?</summary>

Changes made by a database trigger event don't start other trigger events. You can get around this by scheduling a separate custom event or API workflow from the trigger. See [Limitations of database trigger events](#limitations-of-database-trigger-events).

</details>

<details>

<summary>Do privacy rules apply to database trigger events?</summary>

No. They run with full administrative privileges, so privacy rules aren't applied to the actions and expressions in the workflow. Searches return all results, so take care with what the workflow does with them.

</details>

<details>

<summary>Do database trigger events use workload?</summary>

Yes. Workflows started by triggers use server capacity like any other workflow. Strict *Only when* expressions help keep the workflow from running more often than it needs to.

**Reference:** [Database trigger event](https://manual.bubble.io/core-resources/events/trigger-event.md)

</details>

[^1]: *Backend events* are the triggers that happen on Bubble's server, as opposed to events that trigger on a page in your app.\
    **Article series:** [Backend events](https://manual.bubble.io/help-guides/logic/workflows/events/backend-events.md)

[^2]: Dynamic expressions are like live formulas that update based on user input, database changes, and other things happening in your app.\
    **Article:** [Dynamic expressions](https://manual.bubble.io/help-guides/logic/dynamic-expressions.md)

[^3]: A *data source* is any place from which Bubble can retrieve data, such as the current user or a database search.\
    **Article:** [Dynamic expressions](https://manual.bubble.io/help-guides/logic/dynamic-expressions.md)

[^4]: A *comparison* is the part of an expression, along with the data source and operator, that lets us compare two different values.\
    **Article:** [Dynamic expressions](https://manual.bubble.io/help-guides/logic/dynamic-expressions.md)\
    **Reference:** [Operators and comparisons](https://manual.bubble.io/core-resources/data/operations-and-comparisons.md)

[^5]: API workflows are server-side workflows that you can schedule from within your app, or expose so that an external app or system can trigger them through an API request. API workflows are part of the Workflow API.\
    **Article:** [API workflows](https://manual.bubble.io/help-guides/integrations/api/the-bubble-api/the-workflow-api/api-workflows.md)
