Management command and middleware for Django history triggers.
Project description
django-history-triggers
django-history-triggers
is a Django application for installing database triggers
that automatically record inserts, updates, and deletes to model tables.
Requirements
- Django 3.2+
- PostgreSQL or SQLite database
Installation
pip install django-history-triggers
Quick Start
- Add
history
to your INSTALLED_APPS setting and migrate your database. - Add
history.middleware.HistoryMiddleware
to the end of yourMIDDLEWARE
setting. - Run
manage.py triggers enable
to install the trigger functions, ormanage.py triggers disable
to uninstall them. Neither will clear existing history data -- add a--clear
option to do that.
Settings
HISTORY_MODEL
(default:"history.ObjectHistory"
)HISTORY_IGNORE_APPS
(default:["admin", "contenttypes", "sessions"]
)HISTORY_IGNORE_MODELS
(default[]
- should be lowercaseapp_label.model_name
)HISTORY_MIDDLEWARE_IGNORE
(default:[]
)HISTORY_FILTER
(default:"history.utils.default_filter"
)HISTORY_REQUEST_CONTEXT
(default:"history.utils.get_request_context"
)HISTORY_ADMIN_ENABLED
(default:True
)HISTORY_INCLUDE_UNMANAGED
(default:True
)
History Sessions
History is recorded within "sessions" that you can manage manually, either outside of a web request context, or in place of or in addition to the included middleware. The easiest way to manage a history session is via a context manager:
from history import get_backend
def api_view(request):
# You can pass extra fields to be stored for all history within a session.
with get_backend().session(user=request.user, path=request.path):
# All history inside here will have the same session_id and session_date.
...
Starting in 3.4.2, you can also "pause" history recording within a session:
with get_backend().session() as session:
Model.objects.create(name="This history is recorded")
with session.paused():
Model.objects.create(name="This history is NOT recorded")
Model.objects.create(name="This history is also recorded")
Custom History Model
The default history.ObjectHistory
model is swappable by changing the HISTORY_MODEL
setting. If you need to define your own object history model (usually for tracking
custom fields or non-standard user info), be sure to inherit from
history.models.AbstractObjectHistory
. If at all possible, do this early on to avoid
problems with migrations when changing HISTORY_MODEL
after the initial migration.
Filtering History
The HISTORY_FILTER
setting allows you to fully customize which fields (or even whole
models) should be included in or excluded from history. It is implemented as a callable
that takes three parameters:
- The
django.db.models.Model
class being filtered - The
django.db.models.fields.Field
instance in question - The
history.models.TriggerType
being created
The filter should return True
if the field should be included, and False
if it
should be excluded. The default implementation (history.utils.default_filter
) simply
includes any field except BinaryField
s:
def default_filter(model, field, trigger_type):
return not isinstance(field, models.BinaryField)
Returning False
for all fields of any given model has the effect of not tracking
history for that model:
def filter_sensitive(model, field, trigger_type):
return not issubclass(model, SensitiveDataModel)
Similarly, if you (for example) only wanted to record history for UPDATE statements:
def updates_only(model, field, trigger_type):
return trigger_type == TriggerType.UPDATE
Management Commands
By default django-history-triggers
does not override any of Django's management
commands that may perform database operations, such as loaddata
or migrate
. If you
need to run these commands with history triggers enabled, you can include the following
apps in your INSTALLED_APPS
setting:
history.contrib.loaddata
history.contrib.migrate
The HISTORY_LOADDATA_CONTEXT
and HISTORY_MIGRATE_CONTEXT
settings control the
history session context for the respective command, for example:
HISTORY_MIGRATE_CONTEXT = {"user": "system"}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django-history-triggers-3.5.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2121a5dbe4bb925aa5d3c71b5a46a1741360f6a45b926198816b22be4cf7cdab |
|
MD5 | d78ccf721ce551d5a734a16b281cc760 |
|
BLAKE2b-256 | 83e9cbc2ad52565777f2066dc2f2b92f10ad24501907b84c5494fa84e495b675 |
Hashes for django_history_triggers-3.5.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14067928d6f6b97b5f09a38d65dc749c5407e818ee098bba39c3558a4833e028 |
|
MD5 | 3f06a2d1d2a6126440a2285e874b403d |
|
BLAKE2b-256 | 9eadf415485397eee216b0fab53e9a7d0c01e4bdc2f464cf717a77c32e4629be |