← All posts
Repository evaluation
10 min read Browse Awesome Team

Test Django history packages against your actual write paths

Before choosing a Django history package, test the operations your application actually uses. Separate reproducible SQLite and PostgreSQL trials check configured write paths, including bulk and direct-SQL changes. The purpose is a better-supported shortlist, not a package ranking or production audit guarantee.

PostgreSQL extension checked November 17, 2026, UTC. The original November 9 SQLite observations remain separate.

From repository discovery to a write-path decision Choose one required operation, run it in a disposable model, inspect both model state and history, and keep or exclude the candidate for that requirement. 1. Define one write-path requirement 2. Run a disposable model trial 3. Check stored state AND history 4. Keep or exclude for that task
Discovery finds a candidate. A scoped trial tests one requirement, not the whole package.

To evaluate a Django history package, test your application's write paths before comparing repository popularity. An instance save, a queryset update and a relation change do not exercise the same hooks. Use a disposable model, verify both its stored state and its history, then keep candidates that meet your specific evidence requirement.

This walkthrough supplies a runnable synthetic fixture for two candidates: django-simple-history and django-auditlog. Browse Awesome executed it on November 9, 2026, UTC, using Python 3.14.7, Django 5.2.19, django-simple-history 3.13.0 and django-auditlog 3.4.2. Three fresh-process runs produced the same assertions and results. These are local behavior checks with fictional records, not customer analytics, a performance benchmark or a security assessment. The separate PostgreSQL extension in step 5 preserves those original observations and tests a different database and capture mechanism.

1. Define the evidence before finding a package

Start with one sentence: “When this operation succeeds, I need to recover this evidence.” For example, an import job may update product names in bulk, while an administrator edits one product through a form. If both paths matter, testing only the form's instance save leaves the import unanswered.

Use Django repository discovery or Awesome Django to find candidates, then read their current source and documentation. A catalog match is a lead, not proof of installed behavior. The dependency-evidence walkthrough explains how to distinguish an application dependency from development or example configuration before testing it.

The two candidates here also store different kinds of evidence. django-simple-history provides historical model-state records. django-auditlog records model changes as log entries. Equal row counts would not establish equal contents, retention behavior or ability to answer your question. Decide whether you need a state snapshot, a field change, an attempted business action, or something else before using the table below.

This guide tests automatic model-change coverage. It does not test denied requests, sensitive reads, actor attribution or evidence outside a rolled-back transaction. Djass's audit-log guide covers the broader distinction between model history and security or business events; it is not independent validation of this trial.

2. Run the fixture in a disposable environment

Install uv first. Use a local checkout of the Browse Awesome repository, or download the fixture into an empty working directory with these exact relative paths: docs/examples/django-history/trial.py, docs/examples/django-history/probe/__init__.py and docs/examples/django-history/probe/models.py. Keep the empty initialization file too, so the local probe remains an importable package. The fixture uses an in-memory SQLite database and fictional names. It configures its own Django settings, performs local migrations and makes no network requests. Do not point it at your application settings or a production database.

From the repository root, run the following command. The syntax follows uv's script/environment documentation; --no-project keeps the example's package environment separate from this website's dependencies. The exact package versions below are the versions exercised in this walkthrough, not an instruction to change an existing application's lockfile.

uv run --no-project --python 3.14.7 \
  --with Django==5.2.19 \
  --with django-simple-history==3.13.0 \
  --with django-auditlog==3.4.2 \
  python docs/examples/django-history/trial.py

The command can download Python or packages if they are not already available. A successful run prints JSON containing the actual interpreter and package versions, operation results, exclusions and source-file hashes. An assertion failure is a failed check: preserve its output and investigate rather than deleting the assertion to obtain a pass. Package-install or migration errors are also not a clean result.

The fixture uses equivalent models with a name and a many-to-many tag relation. One has HistoricalRecords(m2m_fields=["tags"]); the other is registered with auditlog.register(..., m2m_fields={"tags"}). Both relations are explicitly configured for tracking. See the simple-history historical-model documentation and Auditlog usage documentation. The fixture links the tested release sources too: moving documentation is a useful current reference, not a version pin.

3. Read stored state and history separately

Each case creates a fresh starting object before measuring new history records. The baseline creation is excluded from the deltas below. The script separately checks the resulting model value or deletion, so “no new history” cannot be mistaken for “the write did not happen.”

Observed fixture results, November 9, 2026, UTC:

Operation simple-history: new records Auditlog: new entries
Save without changing the name 1 0
Change the name and save 1 1
Change the name with QuerySet.update() 0 0
Change the name with ordinary bulk_update() 0 0
Create two objects with ordinary bulk_create() 0 0
Add a tag to the explicitly tracked relation 1 1
Save inside an atomic block, then roll it back 0 0
Delete the object through a queryset 1 1

These are operation-level observations from the named fixture and versions, not coverage percentages or package scores. In the bulk-update cases, the model's name changed in the database despite the zero history delta. In the rollback case, neither the changed name nor the transaction's new history record remained. Queryset deletion did create history in this fixture: do not generalize “bulk operations” into a single behavior.

The unchanged-save difference is another reason not to rank packages by record volume. A historical snapshot and a change entry answer different questions. An extra snapshot is not automatically better evidence; an absent change entry after an unchanged save is not automatically lost data. Inspect the record's meaning, not only its count.

4. Test supported alternatives without hiding the default

Django's queryset reference documents that ordinary bulk creation and updating bypass the per-instance save signals used by these paths. The simple-history bulk-operation documentation describes its bulk_create_with_history() and bulk_update_with_history() helpers.

The fixture exercises those helpers separately: creating two objects adds two historical records, and updating those objects through the history-aware helper adds two more. Keeping that check separate preserves the important distinction between the ordinary manager method and a deliberately chosen history-aware write path. It does not mean existing import jobs will start using the helpers when a package is installed.

When adapting the fixture, keep a failing ordinary-operation case beside the proposed alternative. First establish that the business row actually changed. Then inspect the history record for the specific value or relation you expected to recover. Finally, repeat the rollback check with the alternative inside the same transaction boundary. A total record count alone can pass even when the record describes the wrong object or lacks the evidence you need. If your requirement includes an actor or a reason, add an explicit content assertion for it; this fixture leaves those requirements unanswered rather than filling them with a placeholder identity.

Auditlog's tested receiver source and manual logging interfaces are relevant when designing another path. This fixture does not implement or test a manual Auditlog bulk adapter. “Not tested here” is not “impossible.” Do not treat an unimplemented alternative as a reason to declare one package the winner.

5. Check PostgreSQL bulk and raw-SQL paths separately

If your application writes directly to PostgreSQL, a SQLite result leaves a material question unanswered. Browse Awesome ran a separate disposable PostgreSQL fixture on November 17, 2026, UTC. It adds django-pghistory as a trigger-based candidate alongside equivalent simple-history and Auditlog models. Each has only a name field and Django's primary key; no automatic timestamp changes an otherwise unchanged save.

The observed environment was PostgreSQL 15.19, Python 3.14.7, Django 5.2.19, django-simple-history 3.13.0, django-auditlog 3.4.2, django-pghistory 3.9.2, django-pgtrigger 4.17.0 and psycopg 3.3.4. The pinned pghistory release documents @pghistory.track() and the normal migration workflow. Its default insert/update configuration is what this fixture tests, not every configurable tracker. The event-tracking documentation explains changed-field conditions and snapshot choices.

You need a non-root Unix account, uv and already-installed PostgreSQL 15 server binaries. From the repository root, run the command below, adjusting --postgres-bin to that installation. The uv flags follow the script-environment reference. The fixture's cluster lifecycle follows the official PostgreSQL 15 initdb and pg_ctl references; these settings are for disposable testing, not deployment.

uv run --no-project --python 3.14.7 \
  --with Django==5.2.19 \
  --with django-simple-history==3.13.0 \
  --with django-auditlog==3.4.2 \
  --with django-pghistory==3.9.2 \
  --with django-pgtrigger==4.17.0 \
  --with 'psycopg[binary]==3.3.4' \
  python docs/examples/django-history-postgres/trial.py \
  --postgres-bin /usr/lib/postgresql/15/bin

The script creates a new local cluster inside a private temporary directory, listens only on its own Unix socket and ignores application database settings. Trust authentication and skipped initialization sync apply only there. It copies the example models into that directory, generates and applies real migrations, runs Django checks, and confirms two installed, enabled pghistory triggers. It stops its own server and removes its temporary files after a confirmed shutdown; an unconfirmed shutdown retains that directory for inspection. Package downloads may use the network; the database trial uses no external service or production records. JSON output includes source hashes, generated-migration hashes, versions and checked event contents.

On narrow screens, scroll the table sideways to see all three libraries.

Observed PostgreSQL fixture results, November 17, 2026, UTC. Initial creation is excluded from update deltas. The bulk-create row is a separate operation creating two fictional objects.

Operation simple-history: new records Auditlog: new entries pghistory: new events
Save without changing the name 1 0 0
Change the name and save 1 1 1
Change the name with QuerySet.update() 0 0 1
Change the name with ordinary bulk_update() 0 0 1
Parameterized raw SQL changes the name 0 0 1
Ordinary bulk_create() of two objects 0 0 2
Roll back the raw-SQL change 0 0 0

The trial checks the stored name independently from history. When a new record is expected, it also checks the tracked object's identity and recorded name; Auditlog's changed-save entry must contain the exact before/after values and update action. Pghistory's new-row snapshot must carry the expected insert or update label. In the rollback case, the script first confirms the changed row and pghistory event inside the transaction, then verifies that neither survives rollback. Two fresh-cluster runs produced the same checked results and source hashes. That checks reproducibility of this small setup, not reliability across applications.

The practical question is where your required write can bypass the capture mechanism. In this configuration, the pghistory triggers captured the tested ordinary bulk and direct-SQL changes that the two automatic signal-based configurations did not. That is consistent with pghistory's documented scope, but the observed values and assertions—not the package description—are this trial's evidence. Raw SQL uses bound values following Django 5.2's custom-SQL reference.

Do not turn that distinction into a winner. The earlier simple-history helpers remain deliberately different write paths; a manual Auditlog adapter is untested here, not impossible. Default pghistory tracking does not imply deletion coverage, and its context documentation treats context separately: this fixture configures no actor identity. It does not retest many-to-many changes or deletion on PostgreSQL, nor establish concurrency, performance, tamper resistance or durable logging of rolled-back attempts. Reproduce the requirement with your own schema and transaction boundary before choosing an integration.

6. Turn the result into a shortlist decision

Write down the required operation, expected evidence, tested version, observed state, observed history and unresolved question. A useful decision could be: “Our import uses ordinary bulk updates. The original SQLite trial found no automatic history for the two signal-based setups. The PostgreSQL trial captured that operation with pghistory. Evaluate the required event contents and deployment constraints, or a deliberate history-aware alternative, before choosing an integration.” That is narrower and more actionable than “this library supports auditing.”

For an application that needs point-in-time model snapshots, investigate simple-history's documented query and administration workflows next. For one that needs change entries with selected fields and actor context, investigate Auditlog's documented configuration next. Those are reasons to continue evaluating, not findings that this fixture tested either workflow end to end.

Then extend the test only where your actual requirement differs. Relevant next cases might include a custom manager, explicit through models, worker actor context, a database router or direct SQL. Run against your database engine and transaction design before making an integration decision. The original SQLite fixture leaves PostgreSQL and raw SQL untested; the separate PostgreSQL extension answers only the named operations and configuration. Neither trial establishes concurrency, throughput, storage growth, tamper resistance, access policy or regulatory suitability.

Keep the versions, command, source hashes and failed checks with the decision. Re-run when the package version or your application's write path changes, not merely because a repository's star count moved. Return to the repository-shortlisting worksheet to combine this small behavior trial with license, maintenance and task-fit evidence. The goal is a shorter shortlist with a testable reason for each candidate—not a universal ranking of Django history packages.

Django Reproducible trials