django-db-schema-doc
Schema intelligence for Django — Markdown docs, JSON/DBML export, optional diff, and an interactive React Flow ERD from your live database.
Live ERD explorer: behzad-njf.github.io/django-db-schema-doc — open in the browser, upload graph.json from python manage.py generate_erd.
Supports PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, SQLite, Oracle, and other backends Django can introspect.
Install
pip install django-db-schema-doc
Setup
INSTALLED_APPS = [
# ...
"db_schema_doc",
]
Commands
Markdown documentation
python manage.py generate_database_doc
python manage.py generate_database_doc -o docs/schema.md --to-stdout
python manage.py generate_database_doc --with-row-counts --project-hints "Notes for AI agents."
When Django models use db_table matching the database, the doc also merges model docstrings, verbose names, and field help text (disable with --no-model-metadata). Rule-based business context (domain, FK roles, hub/junction heuristics, column hints) is added by default (--no-business-descriptions to skip).
JSON snapshot (CI, diff, agents)
python manage.py export_schema_json -o schema.json
Stable format with "schema_version": 1 — tables, columns, foreign keys, indexes, optional django_model / field labels, connection metadata (no passwords).
AI / RAG export
python manage.py export_ai_schema -o ai_schema.json
python manage.py export_ai_schema --project-name "My Shop" --to-stdout
python manage.py export_ai_schema --no-fk-chunks # table + overview chunks only
Produces documents[] with embeddable content per table (and optional per foreign key), plus metadata for filtering — suitable for vector DBs and agent context pipelines.
Schema search (CLI + ERD)
python manage.py search_schema customer email
python manage.py search_schema order status --format json
python manage.py search_schema product --from-json schema.json
Matches table/column names, Django labels, business descriptions, and FK targets (light synonyms: e.g. fk → foreign key, user → customer). The ERD explorer search box uses the same idea on loaded graph.json.
SQL / ORM query examples
python manage.py export_schema_examples -o schema_examples.json
Auto-generated per table when you run any schema command (disable with --no-query-examples): sample SQL (SELECT, JOIN, filters) and Django ORM snippets (select_related, prefetch_related, etc.). Shown in DATABASE.md, JSON exports, and the ERD table detail panel after generate_erd.
DBML export
python manage.py export_dbml -o schema.dbml
Import into dbdiagram.io, dbdocs.io, etc.
Schema diff (optional)
python manage.py export_schema_json -o before.json # baseline
# ... migrate ...
python manage.py export_schema_json -o after.json
python manage.py schema_diff before.json after.json -o SCHEMA_DIFF.md
Interactive ERD (React Flow)
python manage.py generate_erd -o schema-erd
Online: use the live explorer (no install). Offline: open schema-erd/index.html from generate_erd. Double-click a table for details; Esc to clear focus / close panel.
The PyPI package includes pre-built UI assets. Contributors rebuilding the UI:
cd db_schema_doc/frontend && npm install && npm run build
Using with InsightAI
InsightAI is a separate FastAPI app that turns natural language into safe read-only SQL, runs queries on your database, and (optionally) answers from a Knowledge vector index. It expects schema metadata as Markdown and business docs in Knowledge/. This package exports both.
1. Export schema from your Django project
python manage.py migrate
python manage.py generate_database_doc -o DATABASE.md --project-name "My Project"
python manage.py export_ai_schema -o ai_schema.json --project-name "My Project"
# optional: structural snapshot and examples
python manage.py export_schema_json -o schema.json
python manage.py export_schema_examples -o schema_examples.json
Use model docstrings, verbose_name, and help_text on your models so exports include business meaning (enabled by default). Re-run after migrations or model changes.
2. Wire schema into InsightAI (SQL path)
InsightAI loads table/column/join context from schema/database_schema.md (schema folder).
# In your InsightAI clone
cp /path/to/your/django/project/DATABASE.md schema/database_schema.md
Restart the API (or rely on your deploy process) so the LLM sees the updated tables, FKs, and per-table Query examples sections.
3. Optional hybrid RAG (Knowledge path)
When INSIGHTAI_RAG_ENABLED=true, InsightAI can route questions to documents as well as SQL. Put material under Knowledge/ (.md, .txt, .pdf) and sync:
# Copy human-readable docs (policies, glossaries, onboarding) into Knowledge/
# You can also add extra .md files derived from DATABASE.md sections or ai_schema.json chunks
insightai-knowledge-sync --force # requires pip install -e ".[rag]" in InsightAI
See InsightAI’s Knowledge/README.md and docs/RAG_INGEST.md.
| Export from django-db-schema-doc | Typical use in InsightAI |
|---|---|
DATABASE.md |
schema/database_schema.md — primary source for NL → SQL |
ai_schema.json |
Split documents[].content into Knowledge/*.md for semantic search |
DATABASE.md + --project-hints |
Same file; hints appear at the top for agents |
schema_examples.json |
Reference when authoring trusted SQL in config/semantic/ |
schema.json |
Diff/CI; not required by InsightAI out of the box |
4. RAG tips (better answers)
- One topic per Knowledge file — e.g.
Knowledge/shop-orders.md, not one giant dump of the whole schema. - Refresh on schema changes — regenerate
DATABASE.mdin CI aftermigrate, copy into InsightAI, runinsightai-knowledge-sync --force. - Separate concerns — schema export describes tables/columns; put policies, SLAs, and “how we define active customer” in
Knowledge/. - Use
export_ai_schemafor embedding — eachdocuments[]entry is already a self-contained chunk withcontent+metadata(table, domain,django_model). - Read-only DB user — point InsightAI at the same database (or a replica) with SELECT-only credentials (InsightAI security model).
- Governance — for production, use InsightAI’s
config/governance/and API keys (docs/GOVERNANCE.md).
There is no hard dependency between the two repos: django-db-schema-doc generates artifacts; InsightAI consumes them. Deeper setup (Docker, LLM keys, pgvector): follow the InsightAI README.
What Markdown includes
- Connection metadata (engine, vendor, database — no passwords)
- Tables grouped by name prefix / domain
- Hub tables (most referenced by FKs)
- TOC, FK index, per-table columns, PKs, indexes, incoming/outgoing FKs
- ON DELETE / ON UPDATE on PostgreSQL, MySQL, SQL Server when available
Requirements
- Python 3.10+
- Django 4.2+
- Database driver for your project
Development
Contributor roadmap and phase notes are maintained locally (not in the public repo).
git clone https://github.com/behzad-njf/django-db-schema-doc.git
cd django-db-schema-doc
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cd db_schema_doc/frontend && npm install && npm run build
cd ../../ && pytest
Demo project: examples/demo_project/.
GitHub Pages (ERD website)
The interactive ERD is published on push to main/master via .github/workflows/deploy-pages.yml.
One-time setup on GitHub:
- Settings → Pages → Build and deployment
- Source: GitHub Actions (not “Deploy from a branch”)
After the workflow runs, the site is at:
https://behzad-njf.github.io/django-db-schema-doc/
Local production build (same as CI):
cd db_schema_doc/frontend
VITE_BASE_PATH=/django-db-schema-doc/ npm run build
License
MIT — see LICENSE.
Metadata
Release files for django-db-schema-doc 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_db_schema_doc-1.1.1.tar.gz | 163.2 kB | Without provenance | Details for django_db_schema_doc-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_db_schema_doc-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for django_db_schema_doc-1.1.1-py3-none-any.whl |
Total release size: 330.1 kB
Release files / django_db_schema_doc-1.1.1.tar.gz
| Download URL | django_db_schema_doc-1.1.1.tar.gz |
|---|---|
| Size | 163.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c20461a60883e7906ed2922c90f6e4d9a5f7004f8227d0198c035838203da265
|
|
BLAKE2b-256 checksum How to use checksums |
01a2d008bc56ec2081264c3d4191622f3107524e2cc6b384c9d890ce786818c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / django_db_schema_doc-1.1.1-py3-none-any.whl
| Download URL | django_db_schema_doc-1.1.1-py3-none-any.whl |
|---|---|
| Size | 166.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
14a9336658ab92a0c6092c12c10ff443f615b1c68404e264cbb52b7b0772ff88
|
|
BLAKE2b-256 checksum How to use checksums |
6156e1875be6f9fe86b678eed92c728578c95d35ad64f09248bc4c0610d46a19
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for django-db-schema-doc 1.1.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.