# django-pghistory
`django-pghistory` tracks changes to your Django models using [Postgres triggers](https://www.postgresql.org/docs/current/sql-createtrigger.html), 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.
<a id="quick_start"></a>
## Quick Start
Decorate your model with `pghistory.track`. For example:
```python
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:
```python
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.8 - 3.12, Django 3.2 - 5.0, Psycopg 2 - 3, and Postgres 12 - 16.
## Documentation
[View the django-pghistory docs here](https://django-pghistory.readthedocs.io/) 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.
## Contributing Guide
For information on setting up django-pghistory for development and contributing changes, view [CONTRIBUTING.md](CONTRIBUTING.md).
## Primary Authors
- [Wes Kendall](https://github.com/wesleykendall)
## Other Contributors
- @shivananda-sahu
- @asucrews
- @Azurency
- @dracos
- @adamchainz
- @eeriksp
- @pfouque
Raw data
{
"_id": null,
"home_page": "https://github.com/Opus10/django-pghistory",
"name": "django-pghistory",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8.0",
"maintainer_email": null,
"keywords": null,
"author": "Wes Kendall",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/84/31/76d71a8d8ee9bacedea6355764d81bd0e7d6c264b26771dcd2dab88c10a7/django_pghistory-3.2.0.tar.gz",
"platform": null,
"description": "# django-pghistory\n\n`django-pghistory` tracks changes to your Django models using [Postgres triggers](https://www.postgresql.org/docs/current/sql-createtrigger.html), providing:\n\n* Reliable history tracking everywhere with no changes to your application code.\n* Structured history models that mirror the fields of your models.\n* Grouping of history with additional context attached, such as the logged-in user.\n\n`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.\n\n<a id=\"quick_start\"></a>\n## Quick Start\n\nDecorate your model with `pghistory.track`. For example:\n\n```python\nimport pghistory\n\n@pghistory.track()\nclass TrackedModel(models.Model):\n int_field = models.IntegerField()\n text_field = models.TextField()\n```\n\nAbove we've tracked `TrackedModel`. Copies of the model will be stored in a dynamically-created event model on every insert and update.\n\nRun `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:\n\n```python\nfrom myapp.models import TrackedModel\n\nm = TrackedModel.objects.create(int_field=1, text_field=\"hello\")\nm.int_field = 2\nm.save()\n\nprint(m.events.values(\"pgh_obj\", \"int_field\"))\n\n> [{'pgh_obj': 1, 'int_field': 1}, {'pgh_obj': 1, 'int_field': 2}]\n```\n\nAbove 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.\n\n`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.\n\n## Compatibility\n\n`django-pghistory` is compatible with Python 3.8 - 3.12, Django 3.2 - 5.0, Psycopg 2 - 3, and Postgres 12 - 16.\n\n## Documentation\n\n[View the django-pghistory docs here](https://django-pghistory.readthedocs.io/) to learn more about:\n\n* The basics and terminology.\n* Tracking historical events on models.\n* Attaching dynamic application context to events.\n* Configuring event models.\n* Aggregating events across event models.\n* The Django admin integration.\n* Reverting models to previous versions.\n* A guide on performance and scale.\n\nThere's also additional help, FAQ, and troubleshooting guides.\n\n## Installation\n\nInstall `django-pghistory` with:\n\n pip3 install django-pghistory\n\nAfter this, add `pghistory` and `pgtrigger` to the `INSTALLED_APPS` setting of your Django project.\n\n## Contributing Guide\n\nFor information on setting up django-pghistory for development and contributing changes, view [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Primary Authors\n\n- [Wes Kendall](https://github.com/wesleykendall)\n\n## Other Contributors\n\n- @shivananda-sahu\n- @asucrews\n- @Azurency\n- @dracos\n- @adamchainz\n- @eeriksp\n- @pfouque\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "History tracking for Django and Postgres",
"version": "3.2.0",
"project_urls": {
"Documentation": "https://django-pghistory.readthedocs.io",
"Homepage": "https://github.com/Opus10/django-pghistory",
"Repository": "https://github.com/Opus10/django-pghistory"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a50f442a2b8eab0ab56e1b9a05c2b3946b6eebe725a5807518443123d2130473",
"md5": "1fa3f9015fc0cd17a8b9d368052c6d89",
"sha256": "74ff23bafd972b0456ce22af03ecf8234d2f7e1bf38da6389eaa227966162014"
},
"downloads": -1,
"filename": "django_pghistory-3.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fa3f9015fc0cd17a8b9d368052c6d89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8.0",
"size": 36316,
"upload_time": "2024-04-20T19:18:07",
"upload_time_iso_8601": "2024-04-20T19:18:07.921988Z",
"url": "https://files.pythonhosted.org/packages/a5/0f/442a2b8eab0ab56e1b9a05c2b3946b6eebe725a5807518443123d2130473/django_pghistory-3.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "843176d71a8d8ee9bacedea6355764d81bd0e7d6c264b26771dcd2dab88c10a7",
"md5": "b40c2de2272c3053473e951be58c4e2d",
"sha256": "de1bfc4372c918793ceec82b4eaaafed2c12d49b0b2b3c789893bb0e7232a067"
},
"downloads": -1,
"filename": "django_pghistory-3.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b40c2de2272c3053473e951be58c4e2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8.0",
"size": 29119,
"upload_time": "2024-04-20T19:18:09",
"upload_time_iso_8601": "2024-04-20T19:18:09.637775Z",
"url": "https://files.pythonhosted.org/packages/84/31/76d71a8d8ee9bacedea6355764d81bd0e7d6c264b26771dcd2dab88c10a7/django_pghistory-3.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-20 19:18:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Opus10",
"github_project": "django-pghistory",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "django-pghistory"
}
JSON
