Django ORM Lens is a static analysis tool for the Django ORM. It can parse a Django project's model graph without a database, without running runserver, and without a working virtual environment. It offers three usage interfaces: a VS Code extension, a command-line tool (CLI), and an MCP server, all three sharing the same parsing core.
Main Capabilities
- ER diagram generation: Displays the entire database schema through a Mermaid entity-relationship diagram, supports cardinality arrows for foreign key, one-to-one, and many-to-many relationships, and can be exported as SVG.
- N+1 query detection: Statically analyzes foreign key/many-to-many access in loops that does not use select_related or prefetch_related.
- Migration risk checks: Flags dangerous operations in migrations/*.py, supporting 16 CLI-side migration risk rules.
- Schema drift detection: Checks whether model declarations and migration files are consistent without starting Django, and fails the build only when a field is declared but not migrated.
- Inline diagnostics and quick fixes: 18 editor-side check rules (DOL001–DOL041), using Ruff-style codes and Clippy-style applicability, with support for overriding severity per rule.
- Factory generator: Right-click a model to generate factory_boy's DjangoModelFactory scaffolding, using Faker providers based on field types.
- Time travel mode diff: Select two commits to generate a typed diff, with support for rename detection (Levenshtein + field shape Jaccard).
- Impact analysis: Right-click a field or model to scan the entire workspace, grouped by Django layer (models, serializers, forms, admin, views, URLs, templates, tests, migrations), with confidence levels annotated.
- Interactive query builder: Right-click a field or model, choose a template, and insert a code snippet at the cursor, automatically appending select_related, prefetch_related, and more.
- MCP server: Provides 13 read-only tools for AI coding agents, with support for workspace parsing and sandboxing.
Usage
- VS Code / Cursor / Windsurf: Install the extension from the VS Code Marketplace.
- VSCodium / code-server / Gitpod: Install from Open VSX.
- Terminal and AI coding agents: Run the CLI via pipx or uvx, requires Python 3.9+, and the CLI has zero runtime dependencies.
- Docker: Supports multiple architectures (amd64 + arm64), requires no host Python installation, and is suitable for CI and one-off audits.
- MCP setup: Configure it with a single JSON block, pointing DJANGO_ORM_LENS_ROOT to the absolute path of the Django project.
Use Cases
- Developers joining a Django codebase with more than 10 apps and scattered models.py files.
- Contract/freelance engineers who need to understand an unfamiliar Django project within the first hour.
- Teams onboarding new employees who want a schema view without setting up documentation infrastructure.
- Advanced AI agent users (Cursor / Aider / Zed / Continue, etc.) who need agents to answer schema questions accurately without database credentials or starting Django.
- CI pipelines validating schema shape (for example, whether related_name was accidentally broken) without importing the project.
- Independent developers facing a broken virtual environment or someone else's laptop, without runserver or manage.py migrate.
Limitations
- The tool focuses on static analysis and does not perform live request analysis. For live request analysis, django-debug-toolbar is recommended; for historical request analysis, django-silk; for query count assertions in test suites, django-perf-rec; and for production APM, Scout / Sentry.
- Some features (such as impact, blast-radius, drift, stats-sql) require py-1.7.0 or later.
- Migration risk checks currently have 15 rules (as of v0.6.0).
- The tool is free and licensed under MIT, with no paid tiers, no seat limits, no accounts, and no telemetry.
