1Quick Start 2=========== 3 4Install 5------- 6 7Install from `PyPI`_ with ``pip``: 8 9.. code-block:: bash 10 11 $ pip install django-simple-history 12 13.. _pypi: https://pypi.python.org/pypi/django-simple-history/ 14 15 16Configure 17--------- 18 19Settings 20~~~~~~~~ 21 22Add ``simple_history`` to your ``INSTALLED_APPS`` 23 24.. code-block:: python 25 26 INSTALLED_APPS = [ 27 # ... 28 'simple_history', 29 ] 30 31The historical models can track who made each change. To populate the 32history user automatically you can add ``HistoryRequestMiddleware`` to your Django 33settings: 34 35.. code-block:: python 36 37 MIDDLEWARE = [ 38 # ... 39 'simple_history.middleware.HistoryRequestMiddleware', 40 ] 41 42If you do not want to use the middleware, you can explicitly indicate 43the user making the change as documented in :doc:`/user_tracking`. 44 45 46Track History 47~~~~~~~~~~~~~ 48 49To track history for a model, create an instance of 50``simple_history.models.HistoricalRecords`` on the model. 51 52An example for tracking changes on the ``Poll`` and ``Choice`` models in the 53Django tutorial: 54 55.. code-block:: python 56 57 from django.db import models 58 from simple_history.models import HistoricalRecords 59 60 class Poll(models.Model): 61 question = models.CharField(max_length=200) 62 pub_date = models.DateTimeField('date published') 63 history = HistoricalRecords() 64 65 class Choice(models.Model): 66 poll = models.ForeignKey(Poll) 67 choice_text = models.CharField(max_length=200) 68 votes = models.IntegerField(default=0) 69 history = HistoricalRecords() 70 71Now all changes to ``Poll`` and ``Choice`` model instances will be tracked in 72the database. 73 74Track History for a Third-Party Model 75~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 76 77To track history for a model you didn't create, use the 78``simple_history.register`` function. You can use this to track models from 79third-party apps you don't have control over. Here's an example of using 80``simple_history.register`` to history-track the ``User`` model from the 81``django.contrib.auth`` app: 82 83.. code-block:: python 84 85 from simple_history import register 86 from django.contrib.auth.models import User 87 88 register(User) 89 90If you want to separate the migrations of the historical model into an app other than 91the third-party model's app, you can set the ``app`` parameter in 92``register``. For instance, if you want the migrations to live in the migrations 93folder of the package you register the model in, you could do: 94 95.. code-block:: python 96 97 register(User, app=__package__) 98 99 100Run Migrations 101-------------- 102 103With your model changes in place, create and apply the database migrations: 104 105.. code-block:: bash 106 107 $ python manage.py makemigrations 108 $ python manage.py migrate 109 110Existing Projects 111~~~~~~~~~~~~~~~~~ 112 113For existing projects, you can call the populate command to generate an 114initial change for preexisting model instances: 115 116.. code-block:: bash 117 118 $ python manage.py populate_history --auto 119 120By default, history rows are inserted in batches of 200. This can be changed if needed for large tables 121by using the ``--batchsize`` option, for example ``--batchsize 500``. 122 123What Now? 124--------- 125 126By adding ``HistoricalRecords`` to a model or registering a model using ``register``, 127you automatically start tracking any create, update, or delete that occurs on that model. 128Now you can :doc:`query the history programmatically </querying_history>` 129and :doc:`view the history in Django admin </admin>`. 130 131What is ``django-simple-history`` Doing Behind the Scenes? 132---------------------------------------------------------- 133 134If you tried the code `above`_ and ran the migrations on it, you'll see the following 135tables in your database: 136 137- ``app_choice`` 138- ``app_historicalchoice`` 139- ``app_historicalpoll`` 140- ``app_poll`` 141 142.. _above: `Track History`_ 143 144The two extra tables with ``historical`` prepended to their names are tables created 145by ``django-simple-history``. These tables store every change that you make to their 146respective base tables. Every time a create, update, or delete occurs on ``Choice`` or 147``Poll`` a new row is created in the historical table for that model including all of 148the fields in the instance of the base model, as well as other metadata: 149 150- ``history_user``: the user that made the create/update/delete 151- ``history_date``: the datetime at which the create/update/delete occurred 152- ``history_change_reason``: the reason the create/update/delete occurred (null by default) 153- ``history_id``: the primary key for the historical table (note the the base table's 154 primary key is not unique on the historical table since there are multiple versions of it 155 on the historical table) 156- ``history_type``: ``+`` for create, ``~`` for update, and ``-`` for delete 157 158 159Now try saving an instance of ``Choice`` or ``Poll``. Check the historical table 160to see that the history is being tracked. 161