Быстрый старт

Установите

Установите из PyPI с pip:

$ pip install django-simple-history

Настроить

Настройки

Добавьте simple_history к вашему INSTALLED_APPS.

INSTALLED_APPS = [
    # ...
    'simple_history',
]

Исторические модели могут отслеживать, кто внес каждое изменение. Чтобы автоматически заполнять историю пользователей, вы можете добавить HistoryRequestMiddleware в настройки Django:

MIDDLEWARE = [
    # ...
    'simple_history.middleware.HistoryRequestMiddleware',
]

Если вы не хотите использовать промежуточное ПО, вы можете явно указать пользователя, вносящего изменения, как это описано в Отслеживание пользователей.

История пути

Чтобы отследить историю для модели, создайте экземпляр simple_history.models.HistoricalRecords на модели.

Пример для отслеживания изменений в моделях Poll и Choice в учебнике Django:

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()

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)
    history = HistoricalRecords()

Теперь все изменения в экземплярах моделей Poll и Choice будут отслеживаться в базе данных.

История пути для модели третьей стороны

Чтобы отследить историю для модели, которую вы не создавали, используйте функцию simple_history.register. Вы можете использовать ее для отслеживания моделей из сторонних приложений, над которыми у вас нет контроля. Вот пример использования функции simple_history.register для отслеживания истории модели User из приложения django.contrib.auth:

from simple_history import register
from django.contrib.auth.models import User

register(User)

Если вы хотите отделить миграции исторической модели в приложение, отличное от приложения сторонней модели, вы можете установить параметр app в register. Например, если вы хотите, чтобы миграции жили в папке migrations пакета, в котором вы зарегистрировали модель, вы можете сделать следующее:

register(User, app=__package__)

Запуск миграций

После внесения изменений в модель создайте и примените миграции базы данных:

$ python manage.py makemigrations
$ python manage.py migrate

Существующие проекты

Для существующих проектов можно вызвать команду populate, чтобы сгенерировать начальные изменения для ранее существовавших экземпляров модели:

$ python manage.py populate_history --auto

По умолчанию строки истории вставляются партиями по 200 штук. При необходимости это можно изменить для больших таблиц, используя опцию --batchsize, например --batchsize 500.

Что теперь?

Добавляя HistoricalRecords к модели или регистрируя модель с помощью register, вы автоматически начинаете отслеживать любое создание, обновление или удаление, которое происходит в этой модели. Теперь вы можете query the history programmatically и view the history in Django admin.

Что django-simple-history делает за кулисами?

Если вы попробовали код above и запустили на нем миграции, то в вашей базе данных появятся следующие таблицы:

  • app_choice

  • app_historicalchoice

  • app_historicalpoll

  • app_poll

Две дополнительные таблицы с приставкой historical к их именам - это таблицы, созданные с помощью django-simple-history. Эти таблицы хранят все изменения, которые вы вносите в соответствующие базовые таблицы. Каждый раз, когда происходит создание, обновление или удаление в Choice или Poll, создается новая строка в исторической таблице для этой модели, включающая все поля экземпляра базовой модели, а также другие метаданные:

  • history_user: пользователь, который выполнил создание/обновление/удаление

  • history_date: время, в которое произошло создание/обновление/удаление

  • history_change_reason: причина, по которой произошло создание/обновление/удаление (по умолчанию null)

  • history_id: первичный ключ для исторической таблицы (обратите внимание, что первичный ключ базовой таблицы не является уникальным для исторической таблицы, поскольку существует несколько его версий в исторической таблице)

  • history_type: + для создания, ~ для обновления и - для удаления

Теперь попробуйте сохранить экземпляр Choice или Poll. Проверьте таблицу истории, чтобы убедиться, что история отслеживается.

django-simple-history
Запрос истории
Вернуться на верх