English · Русский · Español · 中文

Django ORM Lens

The schema intelligence layer for Django.

Your entire model graph — live in your editor sidebar, gating your CI, and answering your AI agent over MCP. All from static parsing: no database, no runserver, no working venv.

Replaces: graph_models + django-schema-graph + hand-drawn ER diagrams + grep archaeology.

_{Featured in Django News #347 · PyCoder's Weekly #746}

⚡ 10 seconds to first insight

uvx django-orm-lens scan      # or: pipx run django-orm-lens scan

Cold clone, broken venv, no settings module — you still get every app, model, field, and relation of the project in your terminal.

Then pick your surface — three distributions, one parser core:

MCP setup is one JSON block — see Integrations. Point DJANGO_ORM_LENS_ROOT at your Django project's absolute path.

🆓 Paid-tier capabilities, free and MIT

Schema review is a paid category nearly everywhere. A bot that reviews every pull request, analysis that follows a queryset past the function it was built in, a check that catches schema drift, index advice grounded in real table statistics — those normally sit behind a per-seat or per-database subscription.

All of it is here, MIT-licensed, with no tier gate, no seat count, no account, and no telemetry:

There is no Pro tier, and none is planned. If the tool saves you an afternoon, a star is the entire ask.

📊 Traction

If the tool saves you a grep next time you touch a strange Django project — a star helps others find it.

📈 Star growth

⚡ Install

VS Code / Cursor / Windsurf (VS Code Marketplace):

code --install-extension frowningdev.django-orm-lens

VSCodium / code-server / Gitpod / any OSS Code fork (Open VSX):

codium --install-extension frowningdev.django-orm-lens

Or search Django ORM Lens in the Extensions view — same publisher frowningdev on both registries.

Terminal & AI coding agents:

pip install django-orm-lens              # CLI only
pip install "django-orm-lens[mcp]"       # + MCP server for AI agents

Requires Python 3.9+. Zero runtime dependencies for the CLI.

Docker (v0.6+):

docker run --rm -v "$PWD:/workspace" ghcr.io/frowningdev/django-orm-lens scan --path .

Multi-arch (amd64 + arm64). No Python required on the host. Good for CI and one-off audits.

🎯 The problem

Works offline. Works on a broken venv. Works on someone else's laptop. Works in CI.

You open a Django project. It has 20 apps. You need to answer a simple question:

"Which app owns the Order model, and how is it connected to User?"

Today, that means: Ctrl+P, "models", scroll through 30 hits, open five files, Ctrl+F for class Order, read through 400 lines of ForeignKey('otherapp.Something') strings, try to remember what you learned two files ago.

Half a day gone. Every time. On every project.

✨ With Django ORM Lens

🚀 Power features

📸 What it looks like

Live sample — real django-orm-lens er output, rendered by GitHub right here:

erDiagram
  User {
    CharField display_name
  }
  Tag {
    CharField name
  }
  Post {
    CharField title
    DateTimeField created_at
  }
  Comment {
    TextField body
  }
  Post }o--|| User : "author [CASCADE, as posts]"
  Post }o--o{ Tag : "tags [as posts]"
  Comment }o--|| Post : "post [CASCADE, as comments]"
  Comment }o--|| User : "author [SET_NULL]"

Also included in the extension:

• 🕸️ Live ER diagram — Mermaid cardinality arrows, edge labels (CASCADE, through Model, as related_name), theme-aware, one-click SVG export
• 🔎 Hover cards — over any ForeignKey('app.Model') or ManyToManyField(...), with a one-click jump link
• 🧭 CodeLens — above every class Model line: field count, relation count, and an Open ER diagram action
• 🎨 Named themes — auto / default / dark / forest / neutral for the diagram webview

🤖 For terminals and AI coding agents

The same parser that powers the VS Code extension ships as a standalone Python package — with an optional MCP (Model Context Protocol) server so any MCP-compatible AI agent can navigate your Django schema without importing Django or booting your app.

CLI

django-orm-lens scan -f json                 # every app, every model, every field
django-orm-lens describe blog.Post           # one model in Markdown
django-orm-lens list | fzf                   # flat app.Model — pipes anywhere
django-orm-lens er > schema.mmd              # ER diagram — Mermaid (default)
django-orm-lens er -f dbml > schema.dbml     # …or DBML: paste into dbdiagram.io
django-orm-lens er -f d2 > schema.d2         # …or D2 / plantuml / dot
django-orm-lens diff before.json after.json  # what a PR changes structurally
django-orm-lens nplusone --format github     # N+1 findings as PR annotations
django-orm-lens migration-risk -f sarif      # SARIF for GitHub Code Scanning
django-orm-lens suggest-indexes blog.Post    # Meta.indexes proposals from usage
django-orm-lens signals                      # sender→signal→handler graph
django-orm-lens migration-deps blog -f mermaid   # per-app migration DAG
django-orm-lens cascade blog.Author          # what one delete() takes down
django-orm-lens impact author                # what still references a field
django-orm-lens blast-radius -f markdown     # risks + who still reads them
django-orm-lens drift                        # migrations vs models, no boot
django-orm-lens stats-sql                    # read-only SQL for --stats

impact, blast-radius, drift and stats-sql ship in py-1.7.0 and later.

Every command accepts --path <dir> and --exclude <glob>. nplusone / migration-risk / diff exit code 1 on findings — drop them into CI to block PRs on regressions.

MCP server

Register it once with your agent and it exposes thirteen read-only tools:

# Start it directly
django-orm-lens-mcp

# Or via the CLI subcommand
django-orm-lens mcp

Workspace resolution (py-1.3.0+). Every tool accepts an optional workspace_root argument on the call. Resolution priority: explicit arg → $DJANGO_ORM_LENS_ROOT → current working directory. Invalid or non-Django paths return a structured envelope ({"error": "WORKSPACE_NOT_DJANGO", "hint": "…"}) instead of empty results, so the agent can self-correct. Optional sandbox via DJANGO_ORM_LENS_ALLOWED_ROOTS (;-separated on Windows, : elsewhere).

🛡️ Gate your CI

Schema regressions are cheapest to catch the moment they enter a PR. Four zero-config ways to block them:

Blast-radius PR bot — the whole schema review as one comment, updated in place on every push instead of a new comment each time:

name: Schema review
on: pull_request

permissions:
  contents: read
  pull-requests: write        # only for `comment: true`

jobs:
  blast-radius:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: FROWNINGdev/django-orm-lens@action-v1
        with:
          command: blast-radius
          only-changed: true          # scope to migrations this PR touches
          comment: true               # post once, then update in place
          github-token: ${{ github.token }}

The comment goes up before the job fails, so a blocked PR still explains why. only-changed reads the PR's file list from the API rather than git diff, because actions/checkout defaults to fetch-depth: 1 and the base commit is not in the local history. On push events both flags skip with a notice instead of failing, so one workflow covers both triggers.

The Action installs from PyPI, so blast-radius and drift need py-1.7.0 or later — pin it with version: 1.7.0 if your workflow must not drift. To run an unreleased build instead, add install: false and install the source yourself; this repo's own workflow does exactly that, and is what verifies the Action on every PR.

pre-commit — two hooks, nothing to install locally:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/FROWNINGdev/django-orm-lens
    rev: py-v1.8.1
    hooks:
      - id: django-orm-lens-nplusone
      - id: django-orm-lens-migration-risk

GitHub Action — findings appear as PR annotations with zero extra permissions:

- uses: FROWNINGdev/django-orm-lens@action-v1
  with:
    command: migration-risk      # or: nplusone
    format: github               # ::error / ::warning annotations on the diff

SARIF → Code Scanning — findings land in the repo Security tab:

- run: |
    pip install django-orm-lens
    django-orm-lens migration-risk --format sarif --exit-zero > lens.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: lens.sarif

Exit codes are CI-native: diff and nplusone exit 1 on findings, migration-risk and blast-radius exit 1 on critical findings, drift exits 1 when a field is declared but never migrated. Add --exit-zero for report-only mode.

🔌 Integrations

Example: Cursor / any MCP client

{
  "mcpServers": {
    "django-orm-lens": {
      "command": "django-orm-lens-mcp",
      "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
    }
  }
}

⚡ Performance

The regression suite parses the vendored model graphs of Zulip, Saleor, Wagtail, django CMS, and Mezzanine — 59 models across 13,478 lines of real-world models.py — in about 20 ms end-to-end on a laptop (21 ms best-of-3 on the repo's golden-fixture corpus; a <2 s guard runs in CI on every matrix cell).

Reproduce it yourself:

git clone https://github.com/FROWNINGdev/django-orm-lens && cd django-orm-lens/cli
pip install -e . && python -m pytest tests/test_golden_fixtures.py tests/test_golden_snapshots.py -q

🎯 Who this is for

• Django developers joining a codebase with 10+ apps and getting lost in models.py sprawl.
• Contract / freelance engineers who need to grasp an unfamiliar Django project in the first hour, not the first week.
• Teams onboarding new hires who want a one-glance schema view without spinning up documentation infrastructure.
• AI-agent power users (Cursor / Aider / Zed / Continue / any MCP-compatible client) who need the agent to answer schema questions accurately — without giving it database credentials or booting Django.
• CI pipelines that verify schema shape (e.g. "did we accidentally break a related_name?") without importing the project.
• Solo indie devs on a broken venv or someone else's laptop — no runserver, no manage.py migrate, still works.

🗺️ Market position

Django ORM Lens sits at the intersection of editor tooling and AI-agent tooling — a slot no existing package covers:

Django ORM Lens is the only tool that ships three surfaces from one parser: a VS Code extension (any Code fork), a zero-dep CLI (terminals + CI), and an MCP server (AI agents). All static. All free. All MIT.

🤔 How is this different?

django-schema-graph has not been updated since 2023-05 and does not test Django 5.x.

When you want something else

Honest boundaries: profiling a live request → django-debug-toolbar. Historical request profiling → django-silk. Query-count assertions inside a test suite → django-perf-rec. Production APM on real traffic → Scout / Sentry. Django ORM Lens deliberately stays static — it's the layer that works before the app can even boot, and the only one your CI and your AI agent can use on any checkout.

⚙️ Configuration

The defaults are opinionated and sensible. If you need to tweak:

// .vscode/settings.json
{
  "djangoOrmLens.excludeGlobs": [
    "**/migrations/**",
    "**/node_modules/**",
    "**/venv/**",
    "**/.venv/**",
    "**/env/**"
  ],
  "djangoOrmLens.autoRefresh": true
}

🔬 Rule catalogue

Sixteen editor-side checks (DOL001–DOL032) with Ruff-style codes, per-rule severity, and Clippy-style applicability — plus fifteen CLI-side migration-risk rules and the static N+1 analyzer. Every rule now has its own documentation page.

→ Full rule reference — every code with bad/good examples, QuickFix behaviour, and suppression syntax.

Suppress inline

# django-orm-lens-disable-next-line DOL007
for user in User.objects.all():
    print(user.profile)  # not flagged

qs.count() > 0  # django-orm-lens-disable-line DOL001

# django-orm-lens-disable DOL011  ← on its own line, kills DOL011 for the rest of the file

Applicability follows Rust's Clippy: safe fixes can be applied automatically ("Fix All"), suggestion fixes are offered as a QuickFix but reviewed, unsafe findings never auto-apply. Fixes are separated from analyzers (Roslyn-style), so one rule can grow multiple fixers over time without touching detection logic.

🧭 Commands

Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Django ORM Lens":

🗺️ Roadmap

Shipped

• Sidebar tree grouped by app
• Live Mermaid ER diagram
• Hover cards over ForeignKey('app.Model')
• Filter tree by name
• Split models/ package support
• Export ER diagram as SVG
• Python CLI + MCP server for terminals and AI agents
• Welcome view for empty workspaces
• Path-safe jump-to-definition and sanitized hover markdown
• v0.3.0 — CodeLens above each model class (N fields · N relations · Open ER diagram)
• v0.3.0 — Edge labels on the diagram (CASCADE, SET_NULL, PROTECT, related_name)
• v0.3.0 — Named color themes (auto / default / dark / forest / neutral)
• v0.3.1 — through_model on M2M edges (contributed by @kingrubic)
• v0.3.1 — Listed in the official MCP Registry + Glama.ai
• v0.6.0 — CLI nplusone — static N+1 detector (FK/M2M access inside loops without select_related/prefetch_related)
• v0.6.0 — CLI migration-risk — flags risky operations in migrations/*.py (15 rules today)
• v0.6.0 — CLI diff — compare two schema JSON dumps for PR review
• v0.6.0 — ER-diagram minimap color-codes nodes by Django app
• v0.6.0 — README translations: 🇷🇺 Russian, 🇪🇸 Spanish, 🇨🇳 Chinese
• v0.6.0 — Docker image on GHCR: docker run ghcr.io/frowningdev/django-orm-lens
• v0.7.0 — settings.AUTH_USER_MODEL resolves everywhere: n+1 reverse-relations, signal senders, Mermaid ER, VS Code webview, inbound-relation panel, React ER
• v0.7.0 — AST-based field parser: ForeignKey(on_delete=CASCADE, to='User') resolves regardless of kwarg order (Python + TS parity)
• v0.7.0 — Public shared helpers: find_user_model, resolve_related_tail, find_model, iter_workspace_py_files (Python) + findUserModel, resolveRelatedTail (TS)
• v0.7.0 — --verbose no longer walks the tree twice; WorkspaceIndex.scanned_files carries the count
• v0.7.3 — PEP-526 type annotations on fields (jti: CharField[str] = models.CharField(...)) now parse — reported by @jsabater (#25) with a clean Django Ninja 1.6 repro
• v0.7.4 — PEP-695 generic class headers (Python 3.12+): class Container[T](https://github.com/FROWNINGdev/django-orm-lens/blob/HEAD/models.Model): now parses
• v0.7.5 — Aliased models module (from django.db import models as m) and third-party field packages (jsonfield.JSONField) now detected
• v0.7.6 — Tab-indented model bodies now parse (editors defaulting to tabs no longer show empty models)
• v0.8.0 — Inline QuickFixes: 16 rules (DOL001..DOL032) with per-rule severity + Ruff-style select/ignore + inline # django-orm-lens-disable-next-line
• v0.8.0 — Factory generator: factory_boy scaffold from any model with Faker providers keyed by field type
• v0.8.0 — Time-Travel Schema Diff: pick two commits → typed markdown diff with first-class rename detection
• v0.8.0 — Impact analysis: workspace-wide field-reference scan across every Django layer with Certain/Likely/Possibly confidence tags
• v0.8.0 — Interactive Query Builder: right-click → template → snippet inserted at cursor, grammar-aware (FK gets .select_related, related_name honoured)
• v0.8.0 — Sidebar UX overhaul: stable TreeItem.id, MarkdownString tooltips with command: deep-links, FileDecorationProvider badges, TreeView.badge on the activity bar, three when-gated viewsWelcome states

v1.5.0 — the "one core, three surfaces" wave

• CI formats: SARIF 2.1.0 + --format github PR annotations for nplusone and migration-risk
• Four analyzers promoted from MCP-only to the CLI: suggest-indexes, signals, migration-deps, cascade
• er --format dbml | d2 | plantuml | dot — community-standard diagram exports (dbdiagram.io, D2, PlantUML, Graphviz — dot contributed by @JJordan0C)
• Three new migration-risk rules: runpython_no_reverse, alter_unique_together_lock, alter_index_together_deprecated — 15 total
• pre-commit hooks (django-orm-lens-nplusone, django-orm-lens-migration-risk) + composite GitHub Action
• docs/rules/ — a documentation page for every rule (19 pages)
• Golden-snapshot regression suite over 59 real-world models (Zulip / Saleor / Wagtail / django CMS / Mezzanine); ruff + mypy now gate CI
• Migration dependency graph — migration-deps (text / json / mermaid)

py-1.7 → 1.8 — the schema-intelligence wave

• blast-radius — migration risks joined with what still reads the schema they touch, as a PR bot (comment: true, sticky, only-changed)
• drift — makemigrations --check without booting Django
• impact <name> — what still references a model or field, grouped by Django layer
• blast-radius --stats + stats-sql — optional production row counts from read-only SQL you run yourself (the tool never holds a DB credential)
• nplusone resolves across functions — a queryset returned by a helper is followed into the loop that consumes it
• blast_radius, drift and impact exposed as MCP tools — thirteen tools for AI agents
• drift documents its !! / ~ marks in the report and in --help — reported by @sevdog (#57)
• drift follows inheritance from abstract bases — an abstract base's fields count as the concrete child's own, as Django treats them — reported by @sevdog (#58)
• suggest-index recognises the indexes Django already made — primary key (pk and id are one lookup), db_index, unique, foreign keys, unique_together, UniqueConstraint — reported by @sevdog (#60), same cause independently found by @RinZ27 (#61)
• A sixth golden fixture — Read the Docs joins Zulip, Saleor, Wagtail, django-CMS and Mezzanine, putting the parser under 75 models and 538 fields of real-world Django — contributed by @JJordan0C (#62, closing #51)
• django-taggit TaggableManager is read as the M2M it is — through taggit.TaggedItem to taggit.Tag, through= overrides honoured, in both the Python and the TypeScript parser — contributed by @Guflly (#63, closing #50)
• DOL021 states the USE_TZ default correctly — False through Django 4.2, True from 5.0, with the startproject template's USE_TZ = True since 4.0 called out as the separate thing it is — and no longer claims timezone.now() is always aware UTC — found by @Justine0211 while translating the page (#52)
• The parity_input.py fixture carries the models import a real models.py would have — contributed by @RinZ27 (#64)

py-1.9 → 1.12 — the real-checkout wave

Found by running the CLI over actual checkouts of django-oscar, django-guardian, django-allauth and django-cms rather than over fixtures. Every one of these was invisible to a green test suite, and two of them made the tool answer confidently with something false.

• Models declared inside a module-level block parse — the swappable-model idiom (if not is_model_registered(...): and then an indented class) that every pluggable Django framework uses, against class discovery anchored on ^class. django-oscar went from 12 models, every one of them from its own tests/ directory, to 82. All six golden snapshots stayed byte-identical: a column-0 class parses exactly as before
• abstract_models.py is read alongside models.py — pluggable frameworks keep the abstract base there and leave models.py holding only the concrete subclass, so 72 of django-oscar's 83 models reported zero fields between them. Now 8, and those 8 are correct: they subclass concrete models, where multi-table inheritance leaves the columns on the parent's table
• drift no longer fails a build over two app directories sharing a name — replayed migration state is merged per app name, matching how the declared side is already keyed. On a real django-guardian checkout the blocking count goes 1 → 0 and the contradictory duplicate row disappears, while a genuinely unmigrated field still blocks
• django-mptt models are no longer invisible — MPTTModel is a recognised base, and TreeForeignKey / TreeOneToOneField / TreeManyToManyField are reported as the Django fields they subclass, so TreeForeignKey('self', ...) draws exactly the self-edge a plain ForeignKey('self', ...) does. No django-mptt dependency is added — the parser keeps working against a broken venv. Saleor's product.Category and its children edge now appear in the golden snapshot: 76 added lines, none removed (closing #49)
• The MCP server reports its own version — FastMCP forwards none, so the SDK fell back to importlib.metadata.version("mcp") and every initialize response named the wrong project's release number to the client

v0.9 → v0.12.1 — the extension catches up

• v0.9.0 — Partial UniqueConstraint tracking in Time-Travel Schema Diff: add / drop / change / rename as typed events, with fromCondition carrying the pre-change predicate so a review comment can show Q(is_primary=True) → Q(is_primary=True, deleted=False), and a rename no longer showing up as a lossy add + drop pair. Multiple unnamed constraints on one model key onto #anon-<index> instead of collapsing into a single event. Prompted by django-extensions #1813, where sqldiff drops the condition= predicate so migration reviewers never see what changed
• v0.10.0 — Impact-analysis layer detection runs on the workspace-relative path. It used to match /tests/ and /views.py anywhere in a file's absolute path, so a project checked out under any directory called tests — or a monorepo with services/tests/ above it — had every file reported as that layer, views.py as a test, admin.py as a test. Also: webview messages validated by origin rather than by source, and conflicting leaf migrations detected — two migrations claiming the same parent, which Django only complains about at migrate time
• v0.10.1 — The Marketplace listing names impact analysis, blast radius and schema drift, and says plainly that the tool is free and MIT with no Pro tier. The store page had still described the extension as a sidebar and an ER diagram — what it was two waves earlier — so nobody searching for those features found it. Metadata takes effect only on publish, which is why it needed a release of its own
• v0.11.0 — The TypeScript half of django-mptt support, cut as its own release rather than folded into a later one: between py-1.12.0 shipping and this build, the CLI and the extension disagreed about what a django-mptt schema contains, which is the exact failure the shared golden fixture exists to prevent
• v0.12.0 — The extension asks for a GitHub star, on the third user-initiated ER-diagram open. Not on install: a prompt arriving before the tool has done anything gets dismissed reflexively, and that dismissal is permanent in the user's mind. Sidebar refreshes that re-render an already-open panel are not counted — they are not the user asking for anything. "Later" and "Don't ask again" are stored as separate states, so a deferral re-arms the ask exactly once, twelve opens later; two prompts is the lifetime maximum. The policy is a pure function covered by six tests that need no VS Code host
• v0.12.1 — Export as SVG wrote an unopenable file. toSvg returns percent-encoded markup where toPng returns base64; the save path assumed base64 for anything starting with data:, and base64-decoding percent-encoded text does not fail — the decoder silently drops every character outside its alphabet and returns bytes. A 48-character <svg> document reached disk with the right name, a plausible size and no valid content anywhere in it. The transfer encoding is now read from the data-URL header instead of guessed from the prefix

Next

• ORM query autocomplete inside .filter() / .exclude() / .annotate() (#3)
• App / model toggle checkboxes to declutter huge schemas
• DOL rule engine ported into the Python CLI — one rule catalogue, three surfaces

Later

• Third-party field support — django-model-utils (django-taggit shipped in py-1.11.0, django-mptt in py-1.12.0 / v0.11.0)
• JetBrains / PyCharm plugin (if there is demand)

Vote by 👍-ing the corresponding issue.

❓ FAQ

🆘 Support

• 🐛 Bug reports — GitHub Issues (please include a minimal models.py snippet)
• 💡 Feature requests / ideas — GitHub Discussions
• 📝 Marketplace reviews — rate the extension (the fastest signal that keeps this project moving)
• 🐍 PyPI page — pypi.org/project/django-orm-lens
• 💚 Sponsor — github.com/sponsors/FROWNINGdev

📜 License

MIT © FROWNINGdev