API Reference

Commands

django-pgtrigger comes with the python manage.py pgtrigger command, which has several subcommands that are described below.

Warning

Commands are primarily intended for advanced usage, such as manually installing triggers or making migrations for third-party apps. Running commands such as disable or uninstall will globally turn off triggers for your entire application.

ls

Use python manage.py pgtrigger ls to list all triggers managed by django-pgtrigger. The trigger URI, database, and installation status will be shown.

The following are valid installation status markers:

• INSTALLED: The trigger is installed and up to date

• OUTDATED: The trigger is installed, but it has not been migrated to the current version.

• UNINSTALLED: The trigger is not installed.

• PRUNE: A trigger is no longer in the codebase and still installed.

Note that every installed trigger, including ones that will be pruned, will show whether they are enabled or disabled. Disabled triggers are installed but do not run.

Note

You can provide trigger URIs as arguments to python manage.py pgtrigger ls to only list specific triggers. The URI is the first column returned by python manage.py pgtrigger ls. You can also only list triggers on a single database with the --database option.

install

Use python manage.py pgtrigger install to install triggers. If no arguments are provided, all triggers are installed and any orphaned ones will be pruned.

You can provide trigger URIs as arguments to install specific triggers or filter triggers on a database with the --database argument.

uninstall

Uninstall has the same behavior as python manage.py pgtrigger install except triggers will be uninstalled.

enable

python manage.py pgtrigger enable enables triggers. Similar to other commands, one can provide trigger URIs or the database.

disable

Disable has the same behavior as python manage.py pgtrigger enable except triggers will be disabled.

prune

python manage.py pgtrigger prune will uninstall any triggers managed by django-pgtrigger that are no longer in the codebase.

Note

Pruning happens automatically when doing python manage.py pgtrigger install or python manage.py pgtrigger uninstall.

Python Package

Below are the core classes and functions of the pgtrigger module.

Level clause

pgtrigger.Row = <pgtrigger.core.Level object>

For specifying row-level triggers (the default)

pgtrigger.Statement = <pgtrigger.core.Level object>

For specifying statement-level triggers

When clause

pgtrigger.After = <pgtrigger.core.When object>

For specifying AFTER in the when clause of a trigger

pgtrigger.Before = <pgtrigger.core.When object>

For specifying BEFORE in the when clause of a trigger

pgtrigger.InsteadOf = <pgtrigger.core.When object>

For specifying INSTEAD OF in the when clause of a trigger

Operation clause

pgtrigger.Truncate = <pgtrigger.core.Operation object>

For specifying TRUNCATE as the trigger operation

pgtrigger.Delete = <pgtrigger.core.Operation object>

For specifying DELETE as the trigger operation

pgtrigger.Insert = <pgtrigger.core.Operation object>

For specifying INSERT as the trigger operation

pgtrigger.Update = <pgtrigger.core.Operation object>

For specifying UPDATE as the trigger operation

class pgtrigger.UpdateOf(*columns)

For specifying UPDATE OF as the trigger operation.

Referencing clause

class pgtrigger.Referencing(*, old=None, new=None)

For specifying the REFERENCING clause of a statement-level trigger

Conditions

class pgtrigger.Condition(sql=None)

For specifying free-form SQL in the condition of a trigger.

class pgtrigger.Q(*args, _connector=None, _negated=False, **kwargs)

Similar to Django’s Q object, allows referencing the old and new rows in a trigger condition.

class pgtrigger.F(*args, **kwargs)

Similar to Django’s F object, allows referencing the old and new rows in a trigger condition.

class pgtrigger.IsDistinctFrom(lhs, rhs)

A custom IS DISTINCT FROM field lookup for common trigger conditions. For example, pgtrigger.Q(old__field__df=pgtrigger.F("new__field")).

class pgtrigger.IsNotDistinctFrom(lhs, rhs)

A custom IS NOT DISTINCT FROM field lookup for common trigger conditions. For example, pgtrigger.Q(old__field__ndf=pgtrigger.F("new__field")).

Triggers

class pgtrigger.Trigger(*, name=None, level=None, when=None, operation=None, condition=None, referencing=None, func=None, declare=None)

For specifying a free-form PL/pgSQL trigger function or for creating derived trigger classes.

class pgtrigger.Protect(*, name=None, level=None, when=None, operation=None, condition=None, referencing=None, func=None, declare=None)

A trigger that raises an exception.

class pgtrigger.SoftDelete(*, name=None, condition=None, field=None, value=<object object>)

Sets a field to a value when a delete happens.

Supply the trigger with the “field” that will be set upon deletion and the “value” to which it should be set. The “value” defaults to False.

Note

This trigger currently only supports nullable BooleanField, CharField, and IntField fields.

class pgtrigger.FSM(*, name=None, condition=None, field=None, transitions=None)

Enforces a finite state machine on a field.

Supply the trigger with the “field” that transitions and then a list of tuples of valid transitions to the “transitions” argument.

Note

Only non-null CharField fields are currently supported.

Runtime execution

pgtrigger.ignore(*uris)

Dynamically ignore registered triggers matching URIs from executing in an individual thread. If no URIs are provided, ignore all pgtriggers from executing in an individual thread.

Examples

Ingore triggers in a context manager:

with pgtrigger.ignore("my_app.Model:trigger_name"):
    # Do stuff while ignoring trigger

Ignore multiple triggers as a decorator:

@pgtrigger.ignore("my_app.Model:trigger_name", "my_app.Model:other_trigger")
def my_func():
    # Do stuff while ignoring trigger

Registry

pgtrigger.get(*uris, database=None)

Get registered trigger objects.

Parameters

• *uris (str) – URIs of triggers to get. If none are provided, all triggers are returned. URIs are in the format of {app_label}.{model_name}:{trigger_name}.

• database (str, default=None) – Only get triggers from this database.

Returns

Matching trigger objects.

Return type

List[pgtrigger.Trigger]

pgtrigger.register(*triggers)

Register the given triggers with wrapped Model class.

Parameters

*triggers (pgtrigger.Trigger) – Trigger classes to register.

Examples

Register by decorating a model:

@pgtrigger.register(
    pgtrigger.Protect(
        name="append_only",
        operation=(pgtrigger.Update | pgtrigger.Delete)
    )
)
class MyModel(models.Model):
    pass

Register by calling functionally:

pgtrigger.register(trigger_object)(MyModel)

Installation

pgtrigger.install(*uris, database=None)

Install triggers.

Parameters

• *uris (str) – URIs of triggers to install. If none are provided, all triggers are installed and orphaned triggers are pruned.

• database (str, default=None) – Only install triggers from this database.

pgtrigger.uninstall(*uris, database=None)

Uninstalls triggers.

Parameters

• *uris (str) – URIs of triggers to uninstall. If none are provided, all triggers are uninstalled and orphaned triggers are pruned.

• database (str, default=None) – Only uninstall triggers from this database.

pgtrigger.enable(*uris, database=None)

Enables registered triggers.

Parameters

• *uris (str) – URIs of triggers to enable. If none are provided, all triggers are enabled.

• database (str, default=None) – Only enable triggers from this database.

pgtrigger.disable(*uris, database=None)

Disables triggers.

Parameters

• *uris (str) – URIs of triggers to disable. If none are provided, all triggers are disabled.

• database (str, default=None) – Only disable triggers from this database.

pgtrigger.prune(database=None)

Remove any pgtrigger triggers in the database that are not used by models. I.e. if a model or trigger definition is deleted from a model, ensure it is removed from the database

Parameters

database (str, default=None) – Only prune triggers from this database.