{"id":25860736,"url":"https://github.com/marzukia/django-erd","last_synced_at":"2026-02-12T07:31:45.546Z","repository":{"id":278541923,"uuid":"935982689","full_name":"marzukia/django-erd","owner":"marzukia","description":"Django ERD Generator is a command-line tool designed to generate Entity-Relationship Diagrams (ERDs) from Django models. It supports multiple output formats, making it easy to visualise database relationships in different diagramming tools. ","archived":false,"fork":false,"pushed_at":"2025-10-08T17:51:12.000Z","size":254,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-14T13:43:52.018Z","etag":null,"topics":["conceptual-model","django","erd","erdiagram","logical-data-model"],"latest_commit_sha":null,"homepage":"https://mrzk.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marzukia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-20T10:40:48.000Z","updated_at":"2025-10-08T17:51:16.000Z","dependencies_parsed_at":null,"dependency_job_id":"7f62c17e-a7ba-414a-b8a8-182ec1a15038","html_url":"https://github.com/marzukia/django-erd","commit_stats":null,"previous_names":["marzukia/django-erd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marzukia/django-erd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzukia%2Fdjango-erd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzukia%2Fdjango-erd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzukia%2Fdjango-erd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzukia%2Fdjango-erd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marzukia","download_url":"https://codeload.github.com/marzukia/django-erd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzukia%2Fdjango-erd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29361456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T01:03:07.613Z","status":"online","status_checked_at":"2026-02-12T02:00:06.911Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conceptual-model","django","erd","erdiagram","logical-data-model"],"created_at":"2025-03-01T22:57:22.605Z","updated_at":"2026-02-12T07:31:45.540Z","avatar_url":"https://github.com/marzukia.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](https://github.com/marzukia/django-erd/blob/main/docs/img/logo.png?raw=true)\n\nDjango ERD Generator is a comprehensive command-line tool designed to generate Entity-Relationship Diagrams (ERDs) and data dictionaries from Django models. It supports multiple output formats, making it easy to visualise database relationships in different diagramming tools and create detailed documentation. The generator extracts model definitions, fields, and relationships, converting them into structured representations suitable for use with Mermaid.js, PlantUML, and dbdiagram.io, as well as comprehensive Markdown documentation.\n\n**Key Features:**\n* **ERD Generation**: Create visual database diagrams in multiple formats\n* **Data Dictionary**: Generate comprehensive model documentation in Markdown\n* **Multiple Dialects**: Support for Mermaid.js, PlantUML, and dbdiagram.io\n* **Flexible Output**: Console output or file export\n* **App Filtering**: Include specific Django apps or all apps\n* **Rich Documentation**: Field types, constraints, relationships, and help text\n\n**Supported ERD Dialects:**\n* Mermaid.js\n* PlantUML\n* dbdiagram.io\n\n## Feature Overview\n\n| Feature | ERD Generation | Data Dictionary |\n|---------|----------------|-----------------|\n| **Output Format** | Visual diagrams (Mermaid, PlantUML, dbdiagram) | Structured Markdown documentation |\n| **Primary Use** | Visual database schema representation | Comprehensive model documentation |\n| **Content** | Models, fields, relationships | Detailed field properties, constraints, help text |\n| **Integration** | Diagramming tools, documentation sites | Documentation sites, wikis, repositories |\n| **Best For** | Schema visualization, design reviews | Technical documentation, API docs, onboarding |\n\n## Quickstart\n\nTo generate an Entity-Relationship Diagram (ERD) in the desired syntax, use the `generate_erd` command:\n\n```sh\npython manage.py generate_erd [-h] [-a APPS] [-d DIALECT] [-o OUTPUT]\n```\n\n### Options\n\n| Option | Description |\n|--------|------------|\n| `-h, --help` | Show the help message and exit. |\n| `-a APPS, --apps APPS` | Specify the apps to include in the ERD, separated by commas (e.g., `\"shopping,polls\"`). If omitted, all apps will be included. |\n| `-d DIALECT, --dialect DIALECT` | Set the output format. Supported dialects: `mermaid`, `plantuml`, `dbdiagram`. |\n| `-o OUTPUT, --output OUTPUT` | Define the output file path. If omitted, the output is printed to the console. |\n\n### Examples\n\nGenerate an ERD for all apps in Mermaid format and print to console:\n```sh\npython manage.py generate_erd -d mermaid\n```\n\nGenerate an ERD for `shopping` and `polls` apps in PlantUML format and save to `erd.puml`:\n```sh\npython manage.py generate_erd -a shopping,polls -d plantuml -o erd.puml\n```\n\n### Example Output\n\n```py\nfrom django.db import models\n\n\nclass Customer(models.Model):\n    first_name = models.TextField()\n    last_name = models.TextField()\n    date_of_birth = models.DateField()\n\n\nclass Product(models.Model):\n    sku = models.TextField()\n    product_name = models.TextField()\n    product_code = models.TextField()\n    quantity = models.IntegerField()\n    price = models.DecimalField(max_digits=16, decimal_places=2)\n    regions = models.ManyToManyField(\"Region\")\n\n\nclass Order(models.Model):\n    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)\n    product = models.ForeignKey(Product, on_delete=models.CASCADE)\n    quantity = models.IntegerField()\n    order_total = models.DecimalField(max_digits=16, decimal_places=2)\n\n\nclass Region(models.Model):\n    name = models.TextField()\n    label = models.TextField()\n\n```\n\n### Mermaid.js\n\n#### Code Output\n\n```\nerDiagram\nCustomer {\n  integer id pk\n  text first_name\n  text last_name\n}\nProduct {\n  integer id pk\n  text sku\n  text product_name\n  text product_code\n  integer quantity\n  decimal price\n}\nOrder {\n  integer id pk\n  integer customer_id\n  integer product_id\n  integer quantity\n  decimal order_total\n}\nRegion {\n  integer id pk\n  text name\n  text label\n}\nProduct }|--|{ Region: \"\"\nOrder }|--|| Customer: \"\"\nOrder }|--|| Product: \"\"\n```\n\n#### Rendered Example\n\n![mermaid.js render example](https://github.com/marzukia/django-erd/blob/main/docs/img/examples/mermaid.png?raw=true \"Mermaid.js render example\")\n\n\n### PlantUML\n\n#### Code Output\n\n```\n@startuml\n\nentity Customer {\n  *id: integer\n  first_name: text\n  last_name: text\n}\nentity Product {\n  *id: integer\n  sku: text\n  product_name: text\n  product_code: text\n  quantity: integer\n  price: decimal\n}\nentity Order {\n  *id: integer\n  customer_id: integer\n  product_id: integer\n  quantity: integer\n  order_total: decimal\n}\nentity Region {\n  *id: integer\n  name: text\n  label: text\n}\nProduct }|--|{ Region\nOrder }|--|| Customer\nOrder }|--|| Product\n\n@enduml\n```\n\n#### Rendered Example\n\n![PlantUML render example](https://github.com/marzukia/django-erd/blob/main/docs/img/examples/plantuml.png?raw=true \"PlantUML render example\")\n\n### dbdiagram.io\n\n#### Code Output\n\n```\nTable Customer {\n  id \"integer\" [primary key]\n  first_name \"text\"\n  last_name \"text\"\n}\nTable Product {\n  id \"integer\" [primary key]\n  sku \"text\"\n  product_name \"text\"\n  product_code \"text\"\n  quantity \"integer\"\n  price \"decimal\"\n}\nTable Order {\n  id \"integer\" [primary key]\n  customer_id \"integer\"\n  product_id \"integer\"\n  quantity \"integer\"\n  order_total \"decimal\"\n}\nTable Region {\n  id \"integer\" [primary key]\n  name \"text\"\n  label \"text\"\n}\nRef: Product.regions \u003c\u003e Region.id\nRef: Order.customer_id \u003e Customer.id\nRef: Order.product_id \u003e Product.id\n```\n\n#### Rendered Example\n\n![dbdiagram render example](https://github.com/marzukia/django-erd/blob/main/docs/img/examples/dbdiagram.png?raw=true \"dbdiagram.io render example\")\n\n## Data Dictionary Generation\n\nThe Data Dictionary feature generates comprehensive, structured documentation of your Django models in Markdown format. This feature is perfect for creating technical documentation, onboarding new team members, and maintaining up-to-date schema documentation that stays in sync with your codebase.\n\n### Key Benefits\n\n- **Auto-Generated Documentation**: Automatically extracts model information without manual maintenance\n- **Structured Format**: Organized by Django app with consistent formatting\n- **Rich Metadata**: Includes field types, constraints, relationships, help text, and more\n- **Navigation-Friendly**: Table of contents with anchor links for easy browsing\n- **Version Tracking**: Includes git commit hash for version correlation\n- **Comprehensive Coverage**: Documents all field properties including nullable, unique, choices, etc.\n\n### Usage\n\n```bash\npython manage.py generate_data_dictionary [options]\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-a, --apps` | Specify which Django apps to include. Use comma-separated values (e.g., \"shopping,polls\"). If omitted, all apps are included. |\n| `-o, --output` | Define the output file path for the Markdown file. If omitted, content is printed to stdout. |\n\n### Examples\n\n**Generate documentation for all apps and display in console:**\n```bash\npython manage.py generate_data_dictionary\n```\n\n**Generate documentation for specific apps:**\n```bash\npython manage.py generate_data_dictionary --apps auth,contenttypes,myapp\n```\n\n**Save documentation to a file:**\n```bash\npython manage.py generate_data_dictionary --output docs/schema_documentation.md\n```\n\n**Combine app filtering and file output:**\n```bash\npython manage.py generate_data_dictionary --apps myapp,billing --output docs/core_models.md\n```\n\n### Generated Documentation Structure\n\nThe data dictionary includes:\n\n1. **Header Section**\n   - Project name (automatically detected from Django settings)\n   - Git commit hash for version tracking\n   - Generation timestamp\n\n2. **Table of Contents**\n   - Hierarchical navigation with clickable anchor links\n   - Organized by app, then by model\n   - Quick access to any model documentation\n\n3. **Model Documentation**\n   - **Model signature**: Shows the model constructor with all fields\n   - **Docstring**: Model-level documentation from your code\n   - **Field table**: Comprehensive field information including:\n     - Primary key indicators\n     - Field names and data types\n     - Related model links (clickable within the document)\n     - Field descriptions and help text\n     - Constraint information (nullable, unique, choices)\n     - Database-specific properties (max_length, db_index)\n\n### Field Information Captured\n\nFor each model field, the data dictionary captures:\n\n- **Field Type**: The Django field type (CharField, IntegerField, etc.)\n- **Data Type**: The underlying database data type\n- **Primary Key**: Whether the field is a primary key\n- **Related Models**: Links to related models (ForeignKey, ManyToMany)\n- **Constraints**: Nullable, unique, choices\n- **Validation**: Max length, database indexing\n- **Documentation**: Help text and field descriptions\n\n### Integration with Documentation Workflows\n\nThe data dictionary integrates well with various documentation workflows:\n\n- **CI/CD Integration**: Generate updated documentation on each deployment\n- **Documentation Sites**: Include generated files in Sphinx, MkDocs, or similar tools\n- **Version Control**: Track documentation changes alongside code changes\n- **Team Collaboration**: Share comprehensive schema information with stakeholders\n\n### Rendered Example\n\n```md\n# tests - Data Dictionary\n\nCommit `d3e45c95a2895dc3fe6c1c3629a5753d0e0a58d2`\n\n---\n\n## Table of Contents [#](#toc)\n\n- [Table of Contents](#toc)\n- [Modules](#modules)\n  - [tests](#tests)\n    - [Customer](#Customer)\n    - [Product](#Product)\n    - [Order](#Order)\n    - [Region](#Region)\n\n---\n\n## Modules [#](#modules)\n\n### tests\n\n#### Customer[#](#Customer)\n\n`Customer(id, first_name, last_name)`\n\n| pk | field_name | data_type | related_model | description | nullable | unique | choices | max_length | db_index |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| ✓ | id | `integer` |  |  |  | ✓ |  |  |  |\n|  | first_name | `text` |  |  |  |  |  |  |  |\n|  | last_name | `text` |  |  |  |  |  |  |  |\n\n#### Product[#](#Product)\n\n`Product(id, sku, product_name, product_code, quantity, price, regions)`\n\n| pk | field_name | data_type | related_model | description | nullable | unique | choices | max_length | db_index |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| ✓ | id | `integer` |  |  |  | ✓ |  |  |  |\n|  | sku | `text` |  |  |  |  |  |  |  |\n|  | product_name | `text` |  |  |  |  |  |  |  |\n|  | product_code | `text` |  |  |  |  |  |  |  |\n|  | quantity | `integer` |  |  |  |  |  |  |  |\n|  | price | `decimal` |  |  |  |  |  |  |  |\n\n#### Order[#](#Order)\n\n`Order(id, customer, product, quantity, order_total)`\n\n| pk | field_name | data_type | related_model | description | nullable | unique | choices | max_length | db_index |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| ✓ | id | `integer` |  |  |  |  |  |  |  |\n|  | customer_id | `integer` | [Customer](#Customer) |  |  |  |  |  | ✓ |\n|  | product_id | `integer` | [Product](#Product) |  |  |  |  |  | ✓ |\n|  | quantity | `integer` |  |  |  |  |  |  |  |\n|  | order_total | `decimal` |  |  |  |  |  |  |  |\n\n#### Region[#](#Region)\n\n`Region(id, name, label)`\n\n| pk | field_name | data_type | related_model | description | nullable | unique | choices | max_length | db_index |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| ✓ | id | `integer` |  |  |  |  |  |  |  |\n|  | name | `text` |  |  |  |  |  |  |  |\n|  | label | `text` |  |  |  |  |  |  |  |\n\n```\n\n## Use Cases \u0026 Workflows\n\n### Documentation Automation\n**Problem**: Keeping database documentation up-to-date is time-consuming and error-prone.\n**Solution**: Integrate ERD and data dictionary generation into your CI/CD pipeline.\n\n```yaml\n# Example GitHub Actions workflow\n- name: Generate Documentation\n  run: |\n    python manage.py generate_erd --output docs/database_schema.mermaid\n    python manage.py generate_data_dictionary --output docs/data_dictionary.md\n```\n\n### Team Onboarding\n**Problem**: New developers need to understand complex database relationships quickly.\n**Solution**: Generate visual ERDs and comprehensive data dictionaries as part of onboarding materials.\n\n```bash\n# Generate complete documentation package\npython manage.py generate_erd -d mermaid --output onboarding/schema_diagram.mermaid\npython manage.py generate_erd -d plantuml --output onboarding/schema_diagram.puml\npython manage.py generate_data_dictionary --output onboarding/model_reference.md\n```\n\n### Database Design Reviews\n**Problem**: Reviewing database changes requires understanding current and proposed schemas.\n**Solution**: Generate ERDs before and after changes for visual comparison.\n\n```bash\n# Before changes\npython manage.py generate_erd -d dbdiagram --output reviews/before_changes.dbml\n\n# After implementing changes\npython manage.py generate_erd -d dbdiagram --output reviews/after_changes.dbml\n```\n\n### API Documentation Enhancement\n**Problem**: API documentation lacks detailed schema information.\n**Solution**: Include generated data dictionaries in API documentation.\n\n```bash\n# Generate focused documentation for API-related models\npython manage.py generate_data_dictionary --apps api,core,billing --output api_docs/models.md\n```\n\n### Stakeholder Communication\n**Problem**: Non-technical stakeholders need to understand data structures.\n**Solution**: Use visual ERDs to communicate database design decisions.\n\n```bash\n# Generate clean visual representation\npython manage.py generate_erd -d mermaid --apps core --output stakeholder_review.mermaid\n```\n\n## Best Practices\n\n### 1. **Selective App Documentation**\nDon't overwhelm documentation with unnecessary apps:\n```bash\n# Focus on business-critical apps\npython manage.py generate_data_dictionary --apps core,billing,inventory\n```\n\n### 2. **Regular Updates**\nKeep documentation current with automated generation:\n```bash\n# Add to your deployment script\npython manage.py generate_data_dictionary --output docs/schema.md\ngit add docs/schema.md\n```\n\n### 3. **Format Selection**\nChoose the right ERD format for your audience:\n- **Mermaid**: Great for GitHub/GitLab integration\n- **PlantUML**: Best for detailed technical documentation\n- **dbdiagram.io**: Perfect for visual database design discussions\n\n### 4. **Version Control Integration**\nTrack documentation changes alongside code:\n```bash\n# Generate and commit documentation updates\npython manage.py generate_data_dictionary --output SCHEMA.md\ngit add SCHEMA.md \u0026\u0026 git commit -m \"Update schema documentation\"\n```\n\n## **Supported Versions**\n\nThis project is tested against the following versions:\n\n- **Python**: `3.8, 3.9, 3.10, 3.11, 3.12`\n- **Django**: Latest compatible version based on `tox` dependencies\n\nEnsure you have one of the supported Python versions installed before running tests. You can check your Python version with:\n```sh\npython --version\n```\n\nFor testing, tox will automatically create isolated environments for each supported Python version.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzukia%2Fdjango-erd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarzukia%2Fdjango-erd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzukia%2Fdjango-erd/lists"}