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