Skip to main content

History tracking for Django and Postgres

Project description

django-pghistory

django-pghistory tracks changes to your Django models using Postgres triggers, providing:

  • Reliable history tracking everywhere with no changes to your application code.
  • Structured history models that mirror the fields of your models.
  • Grouping of history with additional context attached, such as the logged-in user.

django-pghistory has a number of ways in which you can configure history tracking for your application's needs and for performance and scale. An admin integration and middleware is included out of the box too.

Quick Start

Decorate your model with pghistory.track. For example:

import pghistory

@pghistory.track()
class TrackedModel(models.Model):
    int_field = models.IntegerField()
    text_field = models.TextField()

Above we've tracked TrackedModel. Copies of the model will be stored in a dynamically-created event model on every insert and update.

Run python manage.py makemigrations followed by migrate and voila, every change to TrackedModel is now stored. This includes bulk methods and even changes that happen in raw SQL. For example:

from myapp.models import TrackedModel

m = TrackedModel.objects.create(int_field=1, text_field="hello")
m.int_field = 2
m.save()

print(m.events.values("pgh_obj", "int_field"))

> [{'pgh_obj': 1, 'int_field': 1}, {'pgh_obj': 1, 'int_field': 2}]

Above we printed the history of int_field. We also printed pgh_obj, which references the tracked object. We'll cover how these fields and additional metadata fields are tracked later.

django-pghistory can track a subset of fields and conditionally store events based on specific field transitions. Users can also store free-form context from the application in event metadata, all with no additional database queries. See the next steps below on how to dive deeper and configure it for your use case.

Compatibility

django-pghistory is compatible with Python 3.9 - 3.13, Django 4.2 - 5.2, Psycopg 2 - 3, and Postgres 14 - 17.

Documentation

View the django-pghistory docs here to learn more about:

  • The basics and terminology.
  • Tracking historical events on models.
  • Attaching dynamic application context to events.
  • Configuring event models.
  • Aggregating events across event models.
  • The Django admin integration.
  • Reverting models to previous versions.
  • A guide on performance and scale.

There's also additional help, FAQ, and troubleshooting guides.

Installation

Install django-pghistory with:

pip3 install django-pghistory

After this, add pghistory and pgtrigger to the INSTALLED_APPS setting of your Django project.

Other Material

There's a DjangoCon 2023 talk that walks through how the library works and provides an overview of problems that can be solved through history-tracking in Django, discussing context-tracking, event reversions, and soft-deletes.

Contributing Guide

For information on setting up django-pghistory for development and contributing changes, view CONTRIBUTING.md.

Creator

Other Contributors

  • @max-muoto
  • @shivananda-sahu
  • @asucrews
  • @Azurency
  • @dracos
  • @adamchainz
  • @eeriksp
  • @pfouque
  • @tobiasmcnulty
  • @lokhman
  • @SupImDos
  • @pmdevita
  • @pablogadhi
  • @xaitec
  • @foobarna
  • @pmdevita

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_pghistory-3.7.0.tar.gz (32.2 kB view details)

Uploaded Source

Built Distribution

django_pghistory-3.7.0-py3-none-any.whl (39.6 kB view details)

Uploaded Python 3

File details

Details for the file django_pghistory-3.7.0.tar.gz.

File metadata

  • Download URL: django_pghistory-3.7.0.tar.gz
  • Upload date:
  • Size: 32.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.12.7 Linux/6.8.0-1029-aws

File hashes

Hashes for django_pghistory-3.7.0.tar.gz
Algorithm Hash digest
SHA256 f44523bd80df511e032c530760415a808627372adef981fcfc8640fddbad9c83
MD5 5f71fd30d4f4b7a6089216cee5122102
BLAKE2b-256 b63d93ce62d506a223ef6bbe6ccd3fa4d1e92ec8dd1c17f7576762390e7a9fee

See more details on using hashes here.

File details

Details for the file django_pghistory-3.7.0-py3-none-any.whl.

File metadata

  • Download URL: django_pghistory-3.7.0-py3-none-any.whl
  • Upload date:
  • Size: 39.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.12.7 Linux/6.8.0-1029-aws

File hashes

Hashes for django_pghistory-3.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8211be1cded05bf5983bdc6f0e9ee659e79080342bd1f43d2f39fc1b0370256c
MD5 773af40c9e0fd4bfcace6db1f3810000
BLAKE2b-256 241bcc2301693e84ac44d7cc996571c527162c017a7571ba25bca1e73df49dac

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page