django-db-schema-doc 1.1.1

Generate DATABASE.md schema documentation for Django projects and LLM agents

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.md in CI after migrate, copy into InsightAI, run insightai-knowledge-sync --force.
• Separate concerns — schema export describes tables/columns; put policies, SLAs, and “how we define active customer” in Knowledge/.
• Use export_ai_schema for embedding — each documents[] entry is already a self-contained chunk with content + 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:

1. Settings → Pages → Build and deployment
2. 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.