Django Migration Visualizer

Interactive visualization of Django migration graphs with a modern UI, draggable nodes, dependency edges, and detailed migration inspection.

This package helps developers understand complex migration histories by displaying migrations as an interactive graph directly inside a Django project.

It works without external JavaScript frameworks — the frontend is built with vanilla JavaScript, CSS, and SVG.

---

Features

Migration Graph Visualization

• Displays migrations as nodes connected by dependency edges.
• Automatically extracts graph structure from Django’s migration loader.
• Supports multiple apps.

Interactive UI

• Draggable migration nodes.
• Zoom and pan support.
• Reset layout option.

Migration Inspection Panel

Click a migration to view detailed information:

• Migration name
• App label
• Dependencies
• run_before relations
• replaces (squashed migrations)
• Operation list
• Human-readable operation descriptions

Operation Details

Operations are parsed and displayed including:

• CreateModel
• AddField
• AlterField
• RemoveField
• DeleteModel
• RenameModel
• RenameField
• and more

Each operation includes a readable description generated from Django’s migration operation representation.

Filtering

Supports filtering migrations by: • specific Django app • optionally hiding Django internal apps

No Frontend Dependencies

Uses: • Vanilla JavaScript • SVG rendering • Pure CSS styling

No React, Vue, or third-party libraries required.

---

Example Use Cases

• Understanding Complex Migrations
• Understanding dependency chains
• Understanding squashed migrations
• Understanding migration ordering , circular dependencies and missing dependencies
• Exploring unfamiliar projects
• Architecture documentation
• Teaching Django ORM relationships
• Debugging model structures
• Visualizing complex SaaS schemas

---

Installation

pip install django-migration-visualizer

Add the app to your Django project.

settings.py

INSTALLED_APPS = [
    ...
    "migration_visualizer",
]

Add the URL route.

urls.py

from django.urls import include, path

urlpatterns = [
    path("migviz/", include("migration_visualizer.urls")),
]

⸻

Usage

Start your Django server.

python manage.py runserver

Open the visualizer:

http://127.0.0.1:8000/migviz/

You will see a graphical representation of your project’s models.

Filtering Models

The sidebar allows filtering:

Option	Description
App label	Show models from a specific Django app
Include Django internal apps	Show admin/auth/contenttypes models

** For most projects, leaving these unchecked gives a cleaner graph.

JSON API

The visualizer exposes a schema API.

GET /migviz/api/graph/

Example request:

/migviz/api/graph/?app_label=catalog

Example response structure:

{
  "meta": {
    "node_count": 18,
    "edge_count": 21
  },
  "nodes": [
    {
      "id": "catalog.0001_initial",
      "name": "0001_initial",
      "app_label": "catalog",
      "operation_count": 3
    }
  ],
  "edges": [
    {
      "from": "catalog.0001_initial",
      "to": "catalog.0002_add_stock"
    }
  ]
}

Development

Clone the repository:

git clone https://github.com/yourname/django-migration-visualizer.git

cd django-migration-visualizer

Install development dependencies:

pip install -e .

Run tests

python -m tests.runtests

⸻

Project Structure

migration_visualizer/
├── apps.py
├── forms.py
├── serializers.py
├── services.py
├── urls.py
├── views.py
├── templates/
│   └── migration_visualizer/
│       └── index.html
├── static/
│   └── migration_visualizer/
│       ├── app.js
│       └── styles.css

⸻

Compatibility

Supported Python versions:

• Python 3.10+
• Python 3.11
• Python 3.12

Supported Django versions:

• Django 4.2
• Django 5.x

⸻

Security

The visualizer exposes project structure.

• For production environments it is recommended to restrict access to staff users.

Example:

from django.contrib.admin.views.decorators import staff_member_required

⸻

License

MIT License

⸻

Author

Created by a Django developer as a lightweight tool for exploring Django migration graphs..

Contributions and improvements are welcome.