Triggers​

Consider using mutation rewrites​

Triggers cannot be used to modify the object that set off the trigger, although they can be used with assert() to do validation on that object. If you need to modify the object, you can use mutation rewrites.

Unified trigger query execution​

All queries within triggers, along with the initial triggering query, are compiled into a single combined SQL query under the hood. Keep this in mind when designing triggers that modify existing records. If multiple update queries within your triggers target the same object, only one of these queries will ultimately be executed. To ensure all desired updates on an object are applied, consolidate them into a single update query within one trigger, instead of distributing them across multiple updates.

Multi-stage trigger execution​

In some cases, a trigger can cause another trigger to fire. When this happens, Gel completes all the triggers fired by the initial query before kicking off a new "stage" of triggers. In the second stage, any triggers fired by the initial stage of triggers will fire. Gel will continue adding trigger stages until all triggers are complete.

The exception to this is when triggers would cause a loop or would cause the same trigger to be run in two different stages. These triggers will generate an error.

Data visibility​

Any query in your trigger will return the state of the database after the triggering query. If this query's results include the object that flipped the trigger, the results will contain that object in the same state as __new__.

Syntax​

type type-name "{"
  trigger name
  after
    {insert | update | delete} [, ...]
    for {each | all}
    [ when (condition) ]
    do expr
"}"

Description​

This declaration defines a new trigger with the following options:

type-name

The name (optionally module-qualified) of the type to be triggered on.

name

The name of the trigger.

insert | update | delete [, ...]

The query type (or types) to trigger on. Separate multiple values with commas to invoke the same trigger for multiple types of queries.

each

The expression will be evaluated once per modified object. __new__ and __old__ in this context within the expression will refer to a single object.

all

The expression will be evaluted once for the entire query, even if multiple objects were modified. __new__ and __old__ in this context within the expression refer to sets of the modified objects.

expr

The expression to be evaluated when the trigger is invoked.

The trigger name must be distinct from that of any existing trigger on the same type.

Create trigger​

Define a new trigger.

{create | alter} type type-name "{"
  create trigger name
    after
    {insert | update | delete} [, ...]
    for {each | all}
    [ when (condition) ]
    do expr
"}"

alter type User {
  create trigger log_insert after insert for each do (
    insert Log {
      action := 'insert',
      target_name := __new__.name
    }
  );
};

alter type User {
  create trigger log_update after update for each
  when (<json>__old__ {**} != <json>__new__ {**})
  do (
    insert Log {
      action := 'update',
      target_name := __new__.name,
      change := __old__.name ++ '->' ++ __new__.name
    }
  );
}

Drop trigger​

Remove a trigger.

alter type type-name "{"
  drop trigger name;
"}"

alter type User {
  drop trigger log_insert;
};