Database Triggers

import { Aside } from ‘@astrojs/starlight/components’;

Database triggers are the core of Entrig. They define what database events should send push notifications and to whom.

---

How triggers work

A trigger in Entrig is a rule that says:

“When a row is inserted/updated/deleted in this table, and these conditions match, send this notification to these users.”

Triggers run automatically. You don’t call them from your code — they fire whenever the database event happens.

---

Trigger anatomy

Every trigger has:

1. Table — which table to monitor
2. Event type — INSERT, UPDATE, or DELETE
3. Conditions (optional) — filter which rows trigger notifications
4. Notification content — title and body, with column interpolation
5. Target users — who receives the notification

---

Event types

INSERT

Fires when a new row is created in the table.

Example use case: Notify a user when someone assigns them a task.

-- In your app code
INSERT INTO tasks (title, assigned_to) VALUES ('Review PR', 'user_123');

This INSERT event can trigger a notification to user_123.

UPDATE

Fires when an existing row is modified.

Example use case: Notify a user when their order status changes.

-- In your app code
UPDATE orders SET status = 'shipped' WHERE id = 456;

This UPDATE event can trigger a notification to the customer who owns order 456.

Entrig provides both the old row values (`OLD`) and new row values (`NEW`) for UPDATE events, so you can compare what changed.

DELETE

Fires when a row is removed from the table.

Example use case: Notify admins when a user deletes their account.

-- In your app code
DELETE FROM users WHERE id = 'user_789';

This DELETE event can trigger a notification to admin users.

---

Conditional triggers

You can add conditions to filter which rows fire notifications. For example:

“Only send a notification if the order total is over $100”

Condition: amount > 100

“Only send a notification if the status changed to ‘approved’”

Condition: NEW.status = 'approved' AND OLD.status != 'approved'

Conditions use SQL syntax and have access to column values from the triggering row.

Available variables

Variable	Event types	Description
NEW.*	INSERT, UPDATE	The new row values
OLD.*	UPDATE, DELETE	The previous row values
Column names	All	Shorthand for NEW.column

Examples:

-- INSERT or UPDATE: notify if priority is high
priority = 'high'

-- UPDATE only: notify if status changed from pending to approved
OLD.status = 'pending' AND NEW.status = 'approved'

-- DELETE: always notify (no condition needed)
(no condition)

-- INSERT: notify if created_by is not null
created_by IS NOT NULL

Conditions are evaluated as SQL `WHERE` clauses. Syntax errors will prevent the trigger from firing. Test your conditions before deploying.

---

Notification content

Notification title and body support column interpolation using double-brace syntax: {{column_name}}.

Example:

Title: New order from {{customer_name}} Body: Order #{{id}} for ${{amount}} has been placed.

If the triggering row has:

id: 123
customer_name: "Alice"
amount: 49.99

The notification will be:

Title: New order from Alice Body: Order #123 for $49.99 has been placed.

Interpolation rules

• Use {{column}} for INSERT and UPDATE events (defaults to NEW.column)
• For UPDATE events, you can use {{OLD.column}} to reference the old value
• If a column is NULL, it renders as an empty string
• Column values are automatically escaped to prevent injection

Example with OLD values:

Title: Order status changed Body: Order #{{id}} changed from {{OLD.status}} to {{NEW.status}}

Rendered:

Order #123 changed from pending to shipped

---

Targeting users

Entrig needs to know which users should receive the notification. You specify this by referencing a column that contains the user’s device token or user ID.

Option 1: Direct device token

If your table has a column with FCM tokens, APNs tokens, or Web Push subscriptions, you can use it directly.

Example:

Table: users Column: fcm_token

Target: fcm_token

When the trigger fires, Entrig sends the notification to the device identified by that token.

Option 2: User ID lookup

If your table has a user ID, Entrig can look up the user’s device token from another table.

Example:

Table: orders Column: customer_id

Target: customer_id (Entrig looks up the token in the users table)

You need to configure the token mapping in Entrig’s settings for this to work.

Option 3: Multiple recipients

If a single event should notify multiple users (e.g., all admins), you can use a JOIN or subquery in the trigger condition.

Multi-user notifications are a premium feature. Contact [support@entrig.com](mailto:support@entrig.com) to enable it.

---

Testing triggers

Before deploying a trigger to production, test it:

1. Create the trigger in Entrig
2. Click “Test Trigger”
3. Insert/update/delete a row in your Supabase table (via SQL Editor or your app)
4. Check the Entrig logs to see if the trigger fired and the notification was sent

Entrig’s test mode logs all trigger executions, including failed conditions and delivery errors.

---

Performance considerations

Trigger volume

Every INSERT/UPDATE/DELETE on the monitored table fires the trigger. If you have high-volume tables (e.g., logs, analytics events), avoid setting triggers on them.

Good: Triggering on orders (100s per day) Bad: Triggering on page_views (1000s per second)

If you need high-volume triggers, contact Entrig support for rate limit increases.

Condition complexity

Complex conditions (with JOINs or subqueries) can slow down trigger evaluation. Keep conditions simple:

Good:

status = 'approved'

Avoid:

id IN (SELECT order_id FROM order_items WHERE price > 100)

If you need complex logic, consider using a Postgres function instead and calling it from the trigger.

---

Trigger limits

Limit	Free tier	Pro tier
Triggers per project	5	Unlimited
Trigger fires per day	10,000	1,000,000
Notification delivery	1,000/day	100,000/day

---

Advanced: Using Postgres triggers with Entrig

If you’re comfortable with SQL, you can create a Postgres trigger that calls Entrig’s webhook API instead of using the Entrig UI.

Example:

CREATE OR REPLACE FUNCTION notify_entrig()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM http_post(
    'https://api.entrig.com/webhook/your-project-id',
    json_build_object(
      'table', TG_TABLE_NAME,
      'event', TG_OP,
      'new', row_to_json(NEW),
      'old', row_to_json(OLD)
    )::text
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER custom_entrig_trigger
AFTER INSERT OR UPDATE OR DELETE ON orders
FOR EACH ROW
EXECUTE FUNCTION notify_entrig();

This gives you full control over when and how Entrig is notified, at the cost of more setup complexity.

---

Examples

Example 1: E-commerce order notifications

Trigger:

• Table: orders
• Event: INSERT
• Condition: status = 'confirmed'
• Title: Order confirmed!
• Body: Your order #{{id}} for ${{total}} has been confirmed.
• Target: customer_id

Example 2: Task assignment

Trigger:

• Table: tasks
• Event: INSERT
• Condition: assigned_to IS NOT NULL
• Title: New task assigned
• Body: {{assigned_by}} assigned you: {{title}}
• Target: assigned_to

Example 3: Status change notifications

Trigger:

• Table: support_tickets
• Event: UPDATE
• Condition: OLD.status = 'open' AND NEW.status = 'closed'
• Title: Ticket closed
• Body: Your support ticket #{{id}} has been closed.
• Target: user_id

---

Next steps

• Web Push setup — configure browser notifications
• FCM setup — configure Android notifications
• APNs setup — configure iOS notifications