By using Postgres triggers. In other words, historical event records are created in the database alongside the database operation, providing a reliable way to track events regardless of where it happens in your code.
Triggers are not supported by Django directly, but django-pghistory
uses django-pgtrigger to seamlessly integrate them with your Django models.
For those that are new to triggers and want additional confidence in their behavior, try the following:
- Always write tests. Perform updates on your tracked models in automated tests and verify that the event models are created.
- Run
python manage.py pgtrigger ls
to verify that all triggers are installed. - Run
python manage.py check
to ensure that there are no missing migrations for triggers.
Although triggers will be issuing additional SQL statements to write events, keep in mind that this happens within the database instance itself. In other words, writing events does not incur additional expensive round-trip database calls. This results in a reduced performance impact when compared to other history tracking methods implemented in software.
See the performance
section for tips and tricks on large history tables.
Check out the reversion
section.
Add a condition to your tracker. See the conditional_tracking
subsection.
Currently concrete inheritance isn't well supported since django-pghistory
simply snapshots the fields on the underlying table. Since concrete inheritance uses foreign keys to other tables, you'll need to set up trackers on all tables.
We plan to add a guide on this in the future.
By default, event models use unconstrained foreign keys and instruct Django to do nothing when tracked models are deleted. This applies not only to the pgh_obj
field that maintains a reference to the tracked model, but every foreign key that's tracked.
You can configure the pgh_obj
key globally by setting the settings.PGHISTORY_OBJ_FIELD
with the proper configuration or by setting it on a per-event-model basis with the obj_field
option to pghistory.track.
See the event_models
section for details on how to set configuration options for event models.
Yes, one of the strengths of django-pghistory
is that it uses structured event models that can be tailored to fit your application use case.
The short answer is that you can't. django-pghistory
is designed to create event models that mirror the models they track, meaning the removal of a field in a tracked model will also be removed in the event model.
If you need data for fields that have been dropped, we recommend two approaches:
- Make the field nullable instead of removing it.
- Use django-pgtrigger to create a custom trigger that dumps a JSON record of the row at that point in time.
The primary author, Wes Kendall, loves to talk to users. Message him at wesleykendall@protonmail.com for any feedback. Any questions, feature requests, or bugs should be reported as issues here.
Wes and other Opus 10 engineers do contracting work, so keep them in mind if your company uses Django.