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 dateOUTDATED
: 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
Referencing clause¶
Conditions¶
- class pgtrigger.Condition(sql=None)[source]¶
For specifying free-form SQL in the condition of a trigger.
- class pgtrigger.Q(*args, _connector=None, _negated=False, **kwargs)[source]¶
Similar to Django’s
Q
object, allows referencing the old and new rows in a trigger condition.
- class pgtrigger.F(*args, **kwargs)[source]¶
Similar to Django’s
F
object, allows referencing the old and new rows in a trigger condition.
Triggers¶
- class pgtrigger.Trigger(*, name=None, level=None, when=None, operation=None, condition=None, referencing=None, func=None, declare=None)[source]¶
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)[source]¶
A trigger that raises an exception.
- class pgtrigger.SoftDelete(*, name=None, condition=None, field=None, value=<object object>)[source]¶
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
, andIntField
fields.
- class pgtrigger.FSM(*, name=None, condition=None, field=None, transitions=None)[source]¶
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)[source]¶
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)[source]¶
Get registered trigger objects.
- Parameters
- Returns
Matching trigger objects.
- Return type
List[
pgtrigger.Trigger
]
- pgtrigger.register(*triggers)[source]¶
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)