django-dbml

django-dbml is a Django app that generates a DBML schema from your Django models.

It is useful when you want to:

• visualize your schema in tools that understand DBML
• document an existing Django project
• export a model-based schema for reviews, planning, or onboarding

The generated output includes:

• tables
• foreign key and one-to-one relationships
• autogenerated many-to-many join tables
• indexes and unique constraints
• enums derived from Django field choices
• notes derived from model and field metadata

Requirements

• Python >=3.11
• Django >=4.2,<7.0

Every supported Python and Django combination is exercised in CI; see docs/development.md for the matrix.

Installation

Install the package:

pip install django-dbml

Add django_dbml to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_dbml",
]

Quick Start

Generate DBML for all installed models:

python manage.py dbml

Write the schema to a file:

python manage.py dbml --output_file schema.dbml

Generate DBML for a single app:

python manage.py dbml billing

Generate DBML for a single model:

python manage.py dbml billing.Invoice

When you target a specific app or model, django-dbml also includes the forward-related tables needed to keep the schema usable.

Command Reference

The management command is:

python manage.py dbml [app_label[.ModelName] ...] [options]

Supported options:

• --output_file PATH Write the generated DBML to a file instead of stdout.
• --table_names Use the underlying database table names instead of Django model labels such as app_label.ModelName.
• --group_by_app Add TableGroup blocks grouped by app/module.
• --color_by_app Add headercolor to each table based on its app/module.
• --add_project_name NAME Set the DBML project name.
• --add_project_notes TEXT Set the DBML project notes.
• --disable_update_timestamp Do not append the Last Updated At ... UTC line to the project notes.

Examples

Generate the whole project

python manage.py dbml --add_project_name "Backoffice"

Generate a subset of apps

python manage.py dbml accounts billing crm

Generate a subset of models

python manage.py dbml billing.Invoice billing.InvoiceLine

Save output to a file

python manage.py dbml --output_file docs/schema.dbml

Use physical table names instead of model labels

python manage.py dbml --table_names

Add project metadata

python manage.py dbml \
  --add_project_name "Commerce Platform" \
  --add_project_notes "Generated from production models." \
  --output_file schema.dbml

Group and color tables by app

python manage.py dbml --group_by_app --color_by_app

How Metadata Is Mapped

django-dbml extracts useful schema notes from Django metadata when available.

Model-level metadata:

• model docstrings are emitted as table notes
• db_table_comment is emitted as a table note
• when --table_names is not used, the DB table name is added to the note

Field-level metadata:

• help_text is emitted as a field note
• verbose_name is emitted as a field note
• db_comment is emitted as a field note
• choices are converted into DBML enums
• default, null, unique, and primary key information are included in field attributes

Relationship handling:

• ForeignKey is rendered as a one-to-many reference
• OneToOneField is rendered as a one-to-one reference
• autogenerated ManyToManyField join tables are rendered as explicit DBML tables and references
• a relation column is typed by the column it points at, not by the relation itself, so a foreign key to a BigAutoField primary key is rendered as big_auto

Example Output

Example command:

python manage.py dbml library --add_project_name "Library"

Example shape of the generated DBML:

Project "Library" {
  database_type: 'PostgreSQL'
  Note: '''Generated from Django models.
  Last Updated At 03-30-2026 02:15PM UTC'''
}

Table library.Book {
  title char [not null]
  author_id big_auto [not null]
}

ref: library.Book.author_id > library.Author.id

The exact output depends on your models, database backend, indexes, choices, and comments.

Development

This repository is managed with uv.

Bootstrap the environment:

make sync

Common commands:

make test
make lint
make build

Run the test suite against a specific Django series:

make test-django DJANGO_CONSTRAINT="django>=5.1,<5.2" PYTHON=3.13

More development details are available in CONTRIBUTING.md and docs/development.md.

Contributors

Thanks to the people who helped improve this project through patches and pull requests, including:

• Michel Wilhelm
• Ee Durbin
• Mathieu Hinderyckx
• Rebecca Sutton Koeser
• Evgeny
• Nick Budak
• jcp
• johnecon

Credits

The initial code was based on https://github.com/hamedsj/DbmlForDjango