Metadata-Version: 2.4
Name: django-db-schema-doc
Version: 1.1.1
Summary: Generate DATABASE.md schema documentation for Django projects and LLM agents
Author: MrHiB
License-Expression: MIT
Project-URL: Homepage, https://behzad-njf.github.io/django-db-schema-doc/
Project-URL: Documentation, https://github.com/behzad-njf/django-db-schema-doc#readme
Project-URL: Repository, https://github.com/behzad-njf/django-db-schema-doc
Project-URL: Issues, https://github.com/behzad-njf/django-db-schema-doc/issues
Keywords: django,database,schema,documentation,llm,markdown,introspection
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Dynamic: license-file

# django-db-schema-doc

[![PyPI version](https://img.shields.io/pypi/v/django-db-schema-doc.svg)](https://pypi.org/project/django-db-schema-doc/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-db-schema-doc.svg)](https://pypi.org/project/django-db-schema-doc/)
[![ERD explorer](https://img.shields.io/badge/demo-schema%20explorer-2563eb)](https://behzad-njf.github.io/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](https://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

```bash
pip install django-db-schema-doc
```

## Setup

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

## Commands

### Markdown documentation

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

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

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

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

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

```bash
python manage.py export_dbml -o schema.dbml
```

Import into [dbdiagram.io](https://dbdiagram.io), [dbdocs.io](https://dbdocs.io), etc.

### Schema diff (optional)

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

```bash
python manage.py generate_erd -o schema-erd
```

**Online:** use the [live explorer](https://behzad-njf.github.io/django-db-schema-doc/) (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:

```bash
cd db_schema_doc/frontend && npm install && npm run build
```

## Using with [InsightAI](https://github.com/behzad-njf/InsightAI)

[InsightAI](https://github.com/behzad-njf/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

```bash
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](https://github.com/behzad-njf/InsightAI/tree/master/schema)).

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

```bash
# 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](https://github.com/behzad-njf/InsightAI/blob/master/Knowledge/README.md) and [docs/RAG_INGEST.md](https://github.com/behzad-njf/InsightAI/blob/master/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](https://github.com/behzad-njf/InsightAI#security-model)).
- **Governance** — for production, use InsightAI’s `config/governance/` and API keys ([docs/GOVERNANCE.md](https://github.com/behzad-njf/InsightAI/blob/master/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](https://github.com/behzad-njf/InsightAI#quick-start).

## 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).

```bash
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/`](examples/demo_project/).

## GitHub Pages (ERD website)

The interactive ERD is published on push to `main`/`master` via [`.github/workflows/deploy-pages.yml`](.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):

```bash
cd db_schema_doc/frontend
VITE_BASE_PATH=/django-db-schema-doc/ npm run build
```

## License

MIT — see [LICENSE](LICENSE).
