Skip to main content

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

Metadata

Release files for django-dbml 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-dbml 1.2.0
File Size Uploaded Provenance Actions
django_dbml-1.2.0.tar.gz 18.4 kB With provenance Details for django_dbml-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-dbml 1.2.0
File Interpreter ABI Platform Actions
django_dbml-1.2.0-py3-none-any.whl Python 3 none any Details for django_dbml-1.2.0-py3-none-any.whl

Total release size: 32.4 kB

Release files / django_dbml-1.2.0.tar.gz

Download URL django_dbml-1.2.0.tar.gz
Size 18.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7f1af2a35e173be04acf0a84d6046df713420d51f957563fc90c9913de62c32b
BLAKE2b-256 checksum
How to use checksums
f057ab184ad95603bb379d773cfd414495c0ffa97c028924b60d249043cceb41
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

Release files / django_dbml-1.2.0-py3-none-any.whl

Download URL django_dbml-1.2.0-py3-none-any.whl
Size 13.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fa28fcb0b8d6092738022fb2538d39451aa8e0f006cf6cb33a27bf1c29f2591a
BLAKE2b-256 checksum
How to use checksums
010e71d22956358785a82dd7735feceee64ba0a771cbc5b6be382a2303b1fbdd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

Security for django-dbml 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for django_dbml-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page