django-migration-snapshots 0.5.1
Capture django migration history snapshots
License: BSD
Keywords: django-migration-snapshots

=============================
Django Migration Snapshots
=============================

.. image:: https://img.shields.io/badge/license-BSD-blue.svg
   :target: https://github.com/Lenders-Cooperative/django-migration-snapshots/blob/main/LICENSE

.. image:: https://readthedocs.org/projects/django-migration-snapshots/badge/?version=stable&style=flat
   :target: https://django-migration-snapshots.readthedocs.io

.. image:: https://img.shields.io/pypi/v/django-migration-snapshots.svg
   :target: https://pypi.org/project/django-migration-snapshots/

.. image:: https://img.shields.io/pypi/pyversions/django-migration-snapshots
   :target: https://pypi.org/project/django-migration-snapshots/

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black


Capture snapshots of your django project's migration history. These snapshots are represented as a directed graph using ``pygraphviz`` in both textual and graphical formats.

Documentation
-------------

The full documentation is at https://django-migration-snapshots.readthedocs.io.

Quickstart
----------

Install Django Migration Snapshots::

    pip install django-migration-snapshots

Add it to your ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = (
        ...
        "migration_snapshots",
        ...
    )

1) Execute management command to create snapshot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python

    # creates snapshot of entire migration history
    python manage.py create_snapshot

    # filter migrations before applied date (YYYY-MM-DD)
    python manage.py create_snapshot --date="2022-10-15"

2) Create object programmatically or from the admin panel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python

    MigrationSnapshot.objects.create(output_format="pdf")

3) Automatically create migration snapshots with the `post_migrate` signal
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python

    from django.apps import AppConfig
    from django.db.models.signals import post_migrate

    def my_snapshot_callback(sender, **kwargs):
        # Create migration snapshot
        MigrationSnapshot.objects.create(output_format="pdf")

    class MyAppConfig(AppConfig):
        ...

        def ready(self):
            # send signal only once after all migrations execute
            post_migrate.connect(my_snapshot_callback, sender=self)


Text Snapshot
-------------

.. code-block:: python

    digraph {
        "admin/0001_initial" -> "auth/0001_initial"
        "admin/0001_initial" -> "contenttypes/0001_initial"
        "admin/0002_logentry_remove_auto_add" -> "admin/0001_initial"
        "admin/0003_logentry_add_action_flag_choices" -> "admin/0002_logentry_remove_auto_add"
        "auth/0001_initial" -> "contenttypes/0001_initial"
        "auth/0002_alter_permission_name_max_length" -> "auth/0001_initial"
        ...
    }


Graphical Snapshot
------------------

.. image:: docs/migration_snapshot.jpeg
  :width: 600
  :alt: JPEG visual representation of migration history


Features
--------
* ``MigrationSnapshot`` data model
* Supported output formats

  * *BMP, CGIMAGE, DOT_CANON, DOT, GV, XDOT, XDOT12, XDOT14, EPS, EXR, FIG, GD, GIF, GTK, ICO, CMAP, ISMAP, IMAP, CMAPX, IMAGE_NP, CMAPX_NP, JPG, JPEG, JPE, JPEG_2000, JSON, JSON0, DOT_JSON, XDOT_JSON, PDF, PIC, PICT, APPLE_PICT, PLAIN_TEXT, PLAIN_EXT, PNG, POV_RAY, PS_PDF, PSD, SGI, SVG, SVGZ, TGA, TIF, TIFF, TK, VML, VMLZ, VRML, WBMP, WEBP, XLIB, X11*
* View migration history based on the miigration's applied timestamp


TODO's
-------
* Additional test coverage
* Setup tox
* Additional filters in management command (ie; per app, per model, etc.)


Local Development
-----------------

::

    make install
    make test


Deployment
----------

::

    make build
    make deploy


License
-------

This project is provided under the `BSD License <https://github.com/theognis1002/django-migration-snapshots/blob/main/LICENSE>`_.