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_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.4.4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 228463e8113c0e4d2c041684028197e89e5891c76c2e9c9de5a3defb20814983 |
|
MD5 | b0d49645d79e7cc1959c0c739a0eb8ac |
|
BLAKE2b-256 | bf977eb42ac001732dfb18c636927f19b00abd286ceb4d3bb6b3bc8164c6bdbd |
Hashes for django_history_triggers-3.4.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 54ee72f92c0f05910ee8ffc84df78daf523b38584c8dbc46adb508c0f7049e89 |
|
MD5 | 040c520b0cc07b2804e6748ce6f26cac |
|
BLAKE2b-256 | 3fba16d18c0415eb404f9c0c22b7cb502a069c6588dcd96359cb2f420dc37505 |