Metadata-Version: 2.4
Name: django-dbml
Version: 1.1.2
Summary: Django extension aimed to generate DBML from installed models.
Author-email: Michel Wilhelm <michelwilhelm@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/makecodesdev/django-dbml
Project-URL: Repository, https://github.com/makecodesdev/django-dbml
Keywords: django,dbml,schema
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django<6.0,>=4.2
Dynamic: license-file

# 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,<6.0`

## Installation

Install the package:

```bash
pip install django-dbml
```

Add `django_dbml` to `INSTALLED_APPS`:

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

## Quick Start

Generate DBML for all installed models:

```bash
python manage.py dbml
```

Write the schema to a file:

```bash
python manage.py dbml --output_file schema.dbml
```

Generate DBML for a single app:

```bash
python manage.py dbml billing
```

Generate DBML for a single model:

```bash
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:

```bash
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

```bash
python manage.py dbml --add_project_name "Backoffice"
```

### Generate a subset of apps

```bash
python manage.py dbml accounts billing crm
```

### Generate a subset of models

```bash
python manage.py dbml billing.Invoice billing.InvoiceLine
```

### Save output to a file

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

### Use physical table names instead of model labels

```bash
python manage.py dbml --table_names
```

### Add project metadata

```bash
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

```bash
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

## Example Output

Example command:

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

Example shape of the generated DBML:

```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 bigint [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:

```bash
make sync
```

Common commands:

```bash
make test
make lint
make build
```

Run the test suite against a specific Django series:

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

More development details are available in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/development.md](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
