docs/historical_model.rst
Historical Model Customizations
===============================
Custom ``history_id``
---------------------
By default, the historical table of a model will use an ``AutoField`` for the table's
``history_id`` (the history table's primary key). However, you can specify a different
type of field for ``history_id`` by passing a different field to ``history_id_field``
parameter.
The example below uses a ``UUIDField`` instead of an ``AutoField``:
.. code-block:: python
import uuid
from django.db import models
from simple_history.models import HistoricalRecords
class Poll(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
history = HistoricalRecords(
history_id_field=models.UUIDField(default=uuid.uuid4)
)
Since using a ``UUIDField`` for the ``history_id`` is a common use case, there is a
``SIMPLE_HISTORY_HISTORY_ID_USE_UUID`` setting that will set all instances of ``history_id`` to UUIDs.
Set this with the following line in your ``settings.py`` file:
.. code-block:: python
SIMPLE_HISTORY_HISTORY_ID_USE_UUID = True
This setting can still be overridden using the ``history_id_field`` parameter on a per model basis.
You can use the ``history_id_field`` parameter with both ``HistoricalRecords()`` or
``register()`` to change this behavior.
Note: regardless of what field type you specify as your history_id field, that field will
automatically set ``primary_key=True`` and ``editable=False``.
Custom ``history_date``
-----------------------
You're able to set a custom ``history_date`` attribute for the historical
record, by defining the property ``_history_date`` in your model. That's
helpful if you want to add versions to your model, which happened before the
current model version, e.g. when batch importing historical data. The content
of the property ``_history_date`` has to be a ``datetime``-object, but setting the
value of the property to a ``DateTimeField``, which is already defined in the
model, will work too.
.. code-block:: python
from django.db import models
from simple_history.models import HistoricalRecords
class Poll(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
changed_by = models.ForeignKey('auth.User')
history = HistoricalRecords()
__history_date = None
@property
def _history_date(self):
return self.__history_date
@_history_date.setter
def _history_date(self, value):
self.__history_date = value
.. code-block:: python
from datetime import datetime
from models import Poll
my_poll = Poll(question="what's up?")
my_poll._history_date = datetime.now()
my_poll.save()
Indexed ``history_date``
------------------------
Many queries use ``history_date`` as a filter. The as_of queries combine this with the
original model's primary key to extract point-in-time snapshots of history. By default
the ``history_date`` field is indexed. You can control this behavior using settings.py.
.. code-block:: python
# disable indexing on history_date
SIMPLE_HISTORY_DATE_INDEX = False
# enable indexing on history_date (default setting)
SIMPLE_HISTORY_DATE_INDEX = True
# enable composite indexing on history_date and model pk (to improve as_of queries)
# the string is case-insensitive
SIMPLE_HISTORY_DATE_INDEX = "Composite"
Custom history table name
-------------------------
By default, the table name for historical models follow the Django convention
and just add ``historical`` before model name. For instance, if your application
name is ``polls`` and your model name ``Question``, then the table name will be
``polls_historicalquestion``.
You can use the ``table_name`` parameter with both ``HistoricalRecords()`` or
``register()`` to change this behavior.
.. code-block:: python
class Question(models.Model):
question_text = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
history = HistoricalRecords(table_name='polls_question_history')
.. code-block:: python
class Question(models.Model):
question_text = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
register(Question, table_name='polls_question_history')
Custom model name
-----------------
By default, historical model is named as 'Historical' + model name. For
example, historical records for ``Choice`` is called ``HistoricalChoice``.
Users can specify a custom model name via the constructor on
``HistoricalRecords``. The common use case for this is avoiding naming conflict
if the user already defined a model named as 'Historical' + model name.
This feature provides the ability to override the default model name used for the generated history model.
To configure history models to use a different name for the history model class, use an option named ``custom_model_name``.
The value for this option can be a `string` or a `callable`.
A simple string replaces the default name of `'Historical' + model name` with the defined string.
The most simple use case is illustrated below using a simple string:
.. code-block:: python
class ModelNameExample(models.Model):
history = HistoricalRecords(
custom_model_name='SimpleHistoricalModelNameExample'
)
If you are using a base class for your models and want to apply a name change for the historical model
for all models using the base class then a callable can be used.
The callable is passed the name of the model for which the history model will be created.
As an example using the callable mechanism, the below changes the default prefix `Historical` to `Audit`:
.. code-block:: python
class Poll(models.Model):
question = models.CharField(max_length=200)
history = HistoricalRecords(custom_model_name=lambda x:f'Audit{x}')
class Opinion(models.Model):
opinion = models.CharField(max_length=2000)
register(Opinion, custom_model_name=lambda x:f'Audit{x}')
The resulting history class names would be `AuditPoll` and `AuditOpinion`.
If the app the models are defined in is `yoda` then the corresponding history table names would be `yoda_auditpoll` and `yoda_auditopinion`
IMPORTANT: Setting `custom_model_name` to `lambda x:f'{x}'` is not permitted.
An error will be generated and no history model created if they are the same.
Custom History Manager and Historical QuerySets
-----------------------------------------------
To manipulate the history ``Manager`` or the historical ``QuerySet`` of
``HistoricalRecords``, you can specify the ``history_manager`` and
``historical_queryset`` options. The values must be subclasses
of ``simple_history.manager.HistoryManager`` and
``simple_history.manager.HistoricalQuerySet``, respectively.
Keep in mind, you can use either or both of these options. To understand the
difference between a ``Manager`` and a ``QuerySet``,
see `Django's Manager documentation`_.
.. code-block:: python
from datetime import timedelta
from django.db import models
from django.utils import timezone
from simple_history.manager import HistoryManager, HistoricalQuerySet
from simple_history.models import HistoricalRecords
class HistoryQuestionManager(HistoryManager):
def published(self):
return self.filter(pub_date__lte=timezone.now())
class HistoryQuestionQuerySet(HistoricalQuerySet):
def question_prefixed(self):
return self.filter(question__startswith="Question: ")
class Question(models.Model):
pub_date = models.DateTimeField("date published")
history = HistoricalRecords(
history_manager=HistoryQuestionManager,
historical_queryset=HistoryQuestionQuerySet,
)
# This is now possible:
queryset = Question.history.published().question_prefixed()
To reuse a ``QuerySet`` from the model, see the following code example:
.. code-block:: python
from datetime import timedelta
from django.db import models
from django.utils import timezone
from simple_history.models import HistoricalRecords
from simple_history.manager import HistoryManager, HistoricalQuerySet
class QuestionQuerySet(models.QuerySet):
def question_prefixed(self):
return self.filter(question__startswith="Question: ")
class HistoryQuestionQuerySet(QuestionQuerySet, HistoricalQuerySet):
"""Redefine ``QuerySet`` with base class ``HistoricalQuerySet``."""
class Question(models.Model):
pub_date = models.DateTimeField("date published")
history = HistoricalRecords(historical_queryset=HistoryQuestionQuerySet)
manager = QuestionQuerySet.as_manager()
.. _Django's Manager documentation: https://docs.djangoproject.com/en/stable/topics/db/managers/
TextField as `history_change_reason`
------------------------------------
The ``HistoricalRecords`` object can be customized to accept a
``TextField`` model field for saving the
`history_change_reason` either through settings or via the constructor on the
model. The common use case for this is for supporting larger model change
histories to support changelog-like features.
.. code-block:: python
SIMPLE_HISTORY_HISTORY_CHANGE_REASON_USE_TEXT_FIELD=True
or
.. code-block:: python
class TextFieldExample(models.Model):
greeting = models.CharField(max_length=100)
history = HistoricalRecords(
history_change_reason_field=models.TextField(null=True)
)
Change Base Class of HistoricalRecord Models
--------------------------------------------
To change the auto-generated HistoricalRecord models base class from
``models.Model``, pass in the abstract class in a list to ``bases``.
.. code-block:: python
class RoutableModel(models.Model):
class Meta:
abstract = True
class Poll(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
changed_by = models.ForeignKey('auth.User')
history = HistoricalRecords(bases=[RoutableModel])
Excluded Fields
--------------------------------
It is possible to use the parameter ``excluded_fields`` to choose which fields
will be stored on every create/update/delete.
For example, if you have the model:
.. code-block:: python
class PollWithExcludeFields(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
And you don't want to store the changes for the field ``pub_date``, it is necessary to update the model to:
.. code-block:: python
class PollWithExcludeFields(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
history = HistoricalRecords(excluded_fields=['pub_date'])
By default, django-simple-history stores the changes for all fields in the model.
Adding additional fields to historical models
---------------------------------------------
Sometimes it is useful to be able to add additional fields to historical models that do not exist on the
source model. This is possible by combining the ``bases`` functionality with the ``pre_create_historical_record`` signal.
.. code-block:: python
# in models.py
class IPAddressHistoricalModel(models.Model):
"""
Abstract model for history models tracking the IP address.
"""
ip_address = models.GenericIPAddressField(_('IP address'))
class Meta:
abstract = True
class PollWithExtraFields(models.Model):
question = models.CharField(max_length=200)
pub_date = models.DateTimeField('date published')
history = HistoricalRecords(bases=[IPAddressHistoricalModel,])
.. code-block:: python
# define your signal handler/callback anywhere outside of models.py
def add_history_ip_address(sender, **kwargs):
history_instance = kwargs['history_instance']
# context.request for use only when the simple_history middleware is on and enabled
history_instance.ip_address = HistoricalRecords.context.request.META['REMOTE_ADDR']
.. code-block:: python
# in apps.py
class TestsConfig(AppConfig):
def ready(self):
from simple_history.tests.models \
import HistoricalPollWithExtraFields
pre_create_historical_record.connect(
add_history_ip_address,
sender=HistoricalPollWithExtraFields
)
More information on signals in ``django-simple-history`` is available in :doc:`/signals`.
Change Reason
-------------
Change reason is a message to explain why the change was made in the instance. It is stored in the
field ``history_change_reason`` and its default value is ``None``.
By default, the django-simple-history gets the change reason in the field ``_change_reason`` of the instance. Also, it is possible to pass
the ``_change_reason`` explicitly. For this, after a save or delete in an instance, it is necessary to call the
function ``utils.update_change_reason``. The first argument of this function is the instance and the second
is the message that represents the change reason.
For instance, for the model:
.. code-block:: python
from django.db import models
from simple_history.models import HistoricalRecords
class Poll(models.Model):
question = models.CharField(max_length=200)
history = HistoricalRecords()
You can create an instance with an implicit change reason.
.. code-block:: python
poll = Poll(question='Question 1')
poll._change_reason = 'Add a question'
poll.save()
Or you can pass the change reason explicitly:
.. code-block:: python
from simple_history.utils import update_change_reason
poll = Poll(question='Question 1')
poll.save()
update_change_reason(poll, 'Add a question')
Deleting historical record
--------------------------
In some circumstances you may want to delete all the historical records when the master record is deleted. This can
be accomplished by setting ``cascade_delete_history=True``.
.. code-block:: python
class Poll(models.Model):
question = models.CharField(max_length=200)
history = HistoricalRecords(cascade_delete_history=True)
Allow tracking to be inherited
---------------------------------
By default history tracking is only added for the model that is passed
to ``register()`` or has the ``HistoricalRecords`` descriptor. By
passing ``inherit=True`` to either way of registering, you can change
that behavior so that any child model inheriting from it will have
historical tracking as well. Be careful though, in cases where a model
can be tracked more than once, ``MultipleRegistrationsError`` will be
raised.
.. code-block:: python
from django.contrib.auth.models import User
from django.db import models
from simple_history import register
from simple_history.models import HistoricalRecords
# register() example
register(User, inherit=True)
# HistoricalRecords example
class Poll(models.Model):
history = HistoricalRecords(inherit=True)
Both ``User`` and ``Poll`` in the example above will cause any model
inheriting from them to have historical tracking as well.
**Note:** For parent models having a ``HistoricalRecords`` field with ``inherit=True``
*and* a ``table_name``, the latter option will not be inherited by child models.
History Model In Different App
------------------------------
By default the app_label for the history model is the same as the base model.
In some circumstances you may want to have the history models belong in a different app.
This will support creating history models in a different database to the base model using
database routing functionality based on app_label.
To configure history models in a different app, add this to the HistoricalRecords instantiation
or the record invocation: ``app="SomeAppName"``.
.. code-block:: python
class Poll(models.Model):
question = models.CharField(max_length=200)
history = HistoricalRecords(app="SomeAppName")
class Opinion(models.Model):
opinion = models.CharField(max_length=2000)
register(Opinion, app="SomeAppName")
`FileField` as a `CharField`
----------------------------
By default a ``FileField`` in the base model becomes a ``TextField`` in the history model.
This is a historical choice that django-simple-history preserves for backwards
compatibility; it is more correct for a ``FileField`` to be converted to a
``CharField`` instead. To opt into the new behavior, set the following line in your
``settings.py`` file:
.. code-block:: python
SIMPLE_HISTORY_FILEFIELD_TO_CHARFIELD = True
Drop Database Indices
--------------------------------
It is possible to use the parameter ``no_db_index`` to choose which fields
that will not create a database index.
For example, if you have the model:
.. code-block:: python
class PollWithExcludeFields(models.Model):
question = models.CharField(max_length=200, db_index=True)
And you don't want to create database index for ``question``, it is necessary to update the model to:
.. code-block:: python
class PollWithExcludeFields(models.Model):
question = models.CharField(max_length=200, db_index=True)
history = HistoricalRecords(no_db_index=['question'])
By default, django-simple-history keeps all indices. and even forces them on unique fields and relations.
WARNING: This will drop performance on historical lookups
Tracking many to many relationships
-----------------------------------
By default, many to many fields are ignored when tracking changes.
If you want to track many to many relationships, you need to define them explicitly:
.. code-block:: python
class Category(models.Model):
name = models.CharField(max_length=200)
class Poll(models.Model):
question = models.CharField(max_length=200)
categories = models.ManyToManyField(Category)
history = HistoricalRecords(m2m_fields=[categories])
This will create a historical intermediate model that tracks each relational change
between `Poll` and `Category`.
You may use either the name of the field or the field instance itself.
You may also define these fields in a class attribute (by default on `_history_m2m_fields`).
This is mainly used by inherited models not declaring their own `HistoricalRecord`.
You can override the attribute name by setting your own `m2m_fields_model_field_name`
argument on the `HistoricalRecord` instance.
You will see the many to many changes when diffing between two historical records:
.. code-block:: python
informal = Category.objects.create(name="informal questions")
official = Category.objects.create(name="official questions")
p = Poll.objects.create(question="what's up?")
p.categories.add(informal, official)
p.categories.remove(informal)
last_record = p.history.latest()
previous_record = last_record.prev_record
delta = last_record.diff_against(previous_record)
for change in delta.changes:
print("{} changed from {} to {}".format(change.field, change.old, change.new))
# Output:
# categories changed from [{'poll': 1, 'category': 1}, { 'poll': 1, 'category': 2}] to [{'poll': 1, 'category': 2}]