Metadata-Version: 2.4
Name: django-migration-visualizer
Version: 0.1.0
Summary: Reusable Django app to visualize Django migration dependencies
Author-email: Hossein Tajfirouz <hosseintajfirouz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ht21992/django-migration-visualizer
Project-URL: Repository, https://github.com/ht21992/django-migration-visualizer
Project-URL: Issues, https://github.com/ht21992/django-migration-visualizer/issues
Keywords: django,models,migrations,visualization,erd,schema
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Dynamic: license-file

# 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

```bash
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.
