Triggers, Effects, And Schedules

Three constructs for work that follows data changes or runs on a clock. Each has distinct execution and failure semantics.

Triggers

A trigger runs synchronously within the mutation transaction. If the trigger function throws, the entire mutation rolls back.

entity Order {
  status: string,
  total:  int,

  @on(insert)        trigger validateOrder
  @on(update, status) trigger onStatusChange    // fires only when status changes
  @on(delete)        trigger onOrderDelete
}

Use triggers for derived data, invariants, and cache invalidation that must be transactionally consistent. Do not use triggers for slow or fallible external I/O.

Trigger Syntax

@on(<action>[, <field>]) trigger <functionName>

action: insert, update, or delete
field (optional, update only): fires only when that field changes

Effects

An effect runs asynchronously via a transactional outbox. The platform guarantees at-least-once delivery with configurable retry.

entity Order {
  status: string,

  @on(insert) effect sendOrderConfirmation {
    retries: 5,
    backoff: exponential(1s),
    timeout: 30s,
  }

  @on(update, status) effect sendStatusUpdate {
    retries: 3,
    backoff: linear(2s),
    timeout: 15s,
  }
}

Use effects for emails, notifications, webhooks, external API calls, and any retryable work.

Effect Syntax

@on(<action>[, <field>]) effect <functionName> {
  retries:  <int>,
  backoff:  exponential(<duration>) | linear(<duration>) | fixed(<duration>),
  timeout:  <duration>,
}

Field	Description
`retries`	Retry attempts after the first failure
`backoff`	Delay strategy between retries
`timeout`	Maximum execution time per attempt

Backoff strategies:

Strategy	Behavior
`exponential(1s)`	Doubles each attempt: 1s, 2s, 4s, 8s...
`linear(2s)`	Increases by one step: 2s, 4s, 6s...
`fixed(5s)`	Constant delay between attempts

Duration format: 30d, 24h, 5m, 30s.

Schedules

A schedule runs a server function on a cron schedule.

schedule dailyCleanup {
  cron:     "0 2 * * *",
  function: cleanupExpiredTokens,
  system:   "token_cleanup",
  timeout:  5m,
}

schedule weeklyDigest {
  cron:     "0 9 * * 1",
  function: sendWeeklyDigest,
  timeout:  10m,
}

Schedule Fields

Field	Required	Description
`cron`	Yes	Standard five-field cron expression (UTC)
`function`	Yes	Handler function name
`system`	No	System role for elevated access
`timeout`	No	Maximum execution time

The platform uses FOR UPDATE SKIP LOCKED for at-most-once execution across instances.

How To Choose

Need	Tool
Work must succeed with the write or roll back	trigger
Work can happen after the write, can be retried	effect
Work runs on a clock	schedule

Related guide: Background Work