django-db-schema-doc 1.0.0__tar.gz

django_db_schema_doc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-db-schema-doc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_db_schema_doc-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: django-db-schema-doc
+Version: 1.0.0
+Summary: Generate DATABASE.md schema documentation for Django projects and LLM agents
+Author: MrHiB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/behzad-njf/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"
+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/)
+
+Generate **DATABASE.md** — full schema documentation for developers and LLM/AI agents — from any database configured in your Django project's `DATABASES`.
+
+Supports **PostgreSQL**, **MySQL/MariaDB**, **Microsoft SQL Server**, **SQLite**, **Oracle**, and other backends Django can introspect.
+
+## Install
+
+```bash
+pip install django-db-schema-doc
+```
+
+## Setup
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "db_schema_doc",
+]
+```
+
+## Usage
+
+```bash
+python manage.py generate_database_doc
+```
+
+Writes `DATABASE.md` in your project `BASE_DIR` by default.
+
+### Common options
+
+```bash
+python manage.py generate_database_doc -o docs/schema.md
+python manage.py generate_database_doc --with-row-counts
+python manage.py generate_database_doc --database reporting
+python manage.py generate_database_doc --project-hints "See accounts_childuserrelation for parent-child links."
+```
+
+Run `python manage.py generate_database_doc --help` for all options.
+
+## What is generated
+
+- Connection metadata (engine, vendor, database — no passwords)
+- Tables grouped by name prefix (`app_model` style)
+- Hub tables (most referenced by foreign keys)
+- Table of contents with anchors
+- Foreign key index
+- Per table: columns, types, PKs, indexes, incoming/outgoing FKs
+
+On PostgreSQL, MySQL, and SQL Server, foreign keys include `ON DELETE` / `ON UPDATE` rules when available.
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- Your project's database driver (e.g. `psycopg`, `mysqlclient`, `mssql-django`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_db_schema_doc-1.0.0/README.md

@@ -0,0 +1,65 @@
+# 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/)
+
+Generate **DATABASE.md** — full schema documentation for developers and LLM/AI agents — from any database configured in your Django project's `DATABASES`.
+
+Supports **PostgreSQL**, **MySQL/MariaDB**, **Microsoft SQL Server**, **SQLite**, **Oracle**, and other backends Django can introspect.
+
+## Install
+
+```bash
+pip install django-db-schema-doc
+```
+
+## Setup
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "db_schema_doc",
+]
+```
+
+## Usage
+
+```bash
+python manage.py generate_database_doc
+```
+
+Writes `DATABASE.md` in your project `BASE_DIR` by default.
+
+### Common options
+
+```bash
+python manage.py generate_database_doc -o docs/schema.md
+python manage.py generate_database_doc --with-row-counts
+python manage.py generate_database_doc --database reporting
+python manage.py generate_database_doc --project-hints "See accounts_childuserrelation for parent-child links."
+```
+
+Run `python manage.py generate_database_doc --help` for all options.
+
+## What is generated
+
+- Connection metadata (engine, vendor, database — no passwords)
+- Tables grouped by name prefix (`app_model` style)
+- Hub tables (most referenced by foreign keys)
+- Table of contents with anchors
+- Foreign key index
+- Per table: columns, types, PKs, indexes, incoming/outgoing FKs
+
+On PostgreSQL, MySQL, and SQL Server, foreign keys include `ON DELETE` / `ON UPDATE` rules when available.
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- Your project's database driver (e.g. `psycopg`, `mysqlclient`, `mssql-django`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_db_schema_doc-1.0.0/db_schema_doc/__init__.py

@@ -0,0 +1,3 @@
+"""Reusable Django app: generate DATABASE.md schema documentation from any configured database."""
+
+__version__ = "1.0.0"

django_db_schema_doc-1.0.0/db_schema_doc/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DbSchemaDocConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "db_schema_doc"
+    verbose_name = "Database schema documentation"

django_db_schema_doc-1.0.0/db_schema_doc/collector.py

@@ -0,0 +1,379 @@
+"""
+Collect database schema metadata using Django's introspection API.
+
+Works with any database backend Django supports (PostgreSQL, MySQL/MariaDB,
+Microsoft SQL Server, Oracle, SQLite, etc.). Optional INFORMATION_SCHEMA
+queries enrich foreign-key ON DELETE / ON UPDATE rules when available.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any
+
+from django.db import connections
+
+
+@dataclass
+class ColumnInfo:
+    name: str
+    type_display: str
+    nullable: bool
+    default: str | None
+    ordinal: int
+    is_primary_key: bool = False
+
+
+@dataclass
+class ForeignKeyInfo:
+    from_table: str
+    from_column: str
+    to_table: str
+    to_column: str
+    constraint_name: str = ""
+    on_delete: str = ""
+    on_update: str = ""
+
+
+@dataclass
+class IndexInfo:
+    name: str
+    columns: list[str]
+    unique: bool = False
+
+
+@dataclass
+class TableInfo:
+    name: str
+    schema: str = "dbo"
+    columns: list[ColumnInfo] = field(default_factory=list)
+    primary_key: list[str] = field(default_factory=list)
+    outgoing_fks: list[ForeignKeyInfo] = field(default_factory=list)
+    incoming_fks: list[ForeignKeyInfo] = field(default_factory=list)
+    indexes: list[IndexInfo] = field(default_factory=list)
+    row_count: int | None = None
+
+
+@dataclass
+class DatabaseSchema:
+    vendor: str
+    database_name: str
+    host: str
+    port: str
+    engine: str
+    tables: list[TableInfo] = field(default_factory=list)
+
+    @property
+    def fk_count(self) -> int:
+        return sum(len(t.outgoing_fks) for t in self.tables)
+
+    @property
+    def column_count(self) -> int:
+        return sum(len(t.columns) for t in self.tables)
+
+
+class SchemaCollector:
+    """Introspect a Django database connection and build a DatabaseSchema."""
+
+    def __init__(self, database: str = "default", include_views: bool = False):
+        self.database = database
+        self.include_views = include_views
+        self.connection = connections[database]
+
+    def collect(self, row_counts: bool = False) -> DatabaseSchema:
+        introspection = self.connection.introspection
+        settings_dict = self.connection.settings_dict
+
+        with self.connection.cursor() as cursor:
+            db_name = self._database_name(cursor)
+            table_names = introspection.table_names(
+                cursor, include_views=self.include_views
+            )
+            table_names = sorted(set(table_names))
+
+            fk_rules = self._fetch_fk_rules(cursor)
+            tables: list[TableInfo] = []
+
+            for table_name in table_names:
+                table = self._collect_table(
+                    cursor, introspection, table_name, fk_rules
+                )
+                if row_counts:
+                    table.row_count = self._row_count(cursor, table_name)
+                tables.append(table)
+
+        incoming = self._build_incoming_fks(tables)
+        for table in tables:
+            table.incoming_fks = incoming.get(table.name, [])
+
+        return DatabaseSchema(
+            vendor=self.connection.vendor,
+            database_name=db_name,
+            host=str(settings_dict.get("HOST", "")),
+            port=str(settings_dict.get("PORT", "")),
+            engine=str(settings_dict.get("ENGINE", "")),
+            tables=tables,
+        )
+
+    def _database_name(self, cursor) -> str:
+        try:
+            if self.connection.vendor == "postgresql":
+                cursor.execute("SELECT current_database()")
+            elif self.connection.vendor == "mysql":
+                cursor.execute("SELECT DATABASE()")
+            elif self.connection.vendor == "microsoft":
+                cursor.execute("SELECT DB_NAME()")
+            elif self.connection.vendor == "sqlite":
+                return str(self.connection.settings_dict.get("NAME", "sqlite"))
+            else:
+                cursor.execute("SELECT 1")
+                return str(self.connection.settings_dict.get("NAME", ""))
+            return str(cursor.fetchone()[0])
+        except Exception:
+            return str(self.connection.settings_dict.get("NAME", "unknown"))
+
+    def _collect_table(
+        self, cursor, introspection, table_name: str, fk_rules: dict
+    ) -> TableInfo:
+        pk_columns = list(introspection.get_primary_key_columns(cursor, table_name))
+        descriptions = introspection.get_table_description(cursor, table_name)
+
+        columns: list[ColumnInfo] = []
+        for ordinal, col in enumerate(descriptions, start=1):
+            type_display = introspection.get_field_type(col.type_code, col)
+            columns.append(
+                ColumnInfo(
+                    name=col.name,
+                    type_display=type_display,
+                    nullable=bool(col.null_ok),
+                    default=self._format_default(col.default),
+                    ordinal=ordinal,
+                    is_primary_key=col.name in pk_columns,
+                )
+            )
+
+        outgoing = self._collect_outgoing_fks(
+            cursor, introspection, table_name, fk_rules
+        )
+        indexes = self._collect_indexes(introspection, cursor, table_name, pk_columns)
+
+        return TableInfo(
+            name=table_name,
+            columns=columns,
+            primary_key=pk_columns,
+            outgoing_fks=outgoing,
+            indexes=indexes,
+        )
+
+    def _collect_outgoing_fks(
+        self, cursor, introspection, table_name: str, fk_rules: dict
+    ) -> list[ForeignKeyInfo]:
+        fks: list[ForeignKeyInfo] = []
+        seen: set[tuple[str, str, str, str]] = set()
+
+        try:
+            key_columns = introspection.get_key_columns(cursor, table_name)
+        except NotImplementedError:
+            key_columns = []
+
+        for from_col, to_table, to_col in key_columns:
+            key = (table_name, from_col, to_table, to_col)
+            if key in seen:
+                continue
+            seen.add(key)
+            rules = fk_rules.get((table_name, from_col), {})
+            fks.append(
+                ForeignKeyInfo(
+                    from_table=table_name,
+                    from_column=from_col,
+                    to_table=to_table,
+                    to_column=to_col,
+                    constraint_name=rules.get("constraint_name", ""),
+                    on_delete=rules.get("on_delete", ""),
+                    on_update=rules.get("on_update", ""),
+                )
+            )
+
+        # Fallback: constraints API (some backends only expose FKs here)
+        try:
+            constraints = introspection.get_constraints(cursor, table_name)
+        except NotImplementedError:
+            constraints = {}
+
+        for cname, info in constraints.items():
+            fk = info.get("foreign_key")
+            if not fk:
+                continue
+            to_table, to_col = fk
+            for from_col in info.get("columns", []):
+                key = (table_name, from_col, to_table, to_col)
+                if key in seen:
+                    continue
+                seen.add(key)
+                rules = fk_rules.get((table_name, from_col), {})
+                fks.append(
+                    ForeignKeyInfo(
+                        from_table=table_name,
+                        from_column=from_col,
+                        to_table=to_table,
+                        to_column=to_col,
+                        constraint_name=cname,
+                        on_delete=rules.get("on_delete", ""),
+                        on_update=rules.get("on_update", ""),
+                    )
+                )
+
+        return sorted(fks, key=lambda f: (f.from_column, f.to_table))
+
+    def _collect_indexes(
+        self, introspection, cursor, table_name: str, pk_columns: list[str]
+    ) -> list[IndexInfo]:
+        indexes: list[IndexInfo] = []
+        try:
+            constraints = introspection.get_constraints(cursor, table_name)
+        except NotImplementedError:
+            return indexes
+
+        for name, info in constraints.items():
+            if not info.get("index"):
+                continue
+            if info.get("primary_key"):
+                continue
+            cols = info.get("columns") or []
+            if not cols:
+                continue
+            indexes.append(
+                IndexInfo(
+                    name=name,
+                    columns=list(cols),
+                    unique=bool(info.get("unique")),
+                )
+            )
+        return sorted(indexes, key=lambda i: i.name)
+
+    def _fetch_fk_rules(self, cursor) -> dict[tuple[str, str], dict[str, str]]:
+        """Optional FK ON DELETE/UPDATE from INFORMATION_SCHEMA (where supported)."""
+        vendor = self.connection.vendor
+        if vendor == "microsoft":
+            return self._fk_rules_mssql(cursor)
+        if vendor == "postgresql":
+            return self._fk_rules_postgresql(cursor)
+        if vendor == "mysql":
+            return self._fk_rules_mysql(cursor)
+        return {}
+
+    def _fk_rules_mssql(self, cursor) -> dict[tuple[str, str], dict[str, str]]:
+        sql = """
+            SELECT
+                fk.TABLE_NAME,
+                fk.COLUMN_NAME,
+                rc.CONSTRAINT_NAME,
+                rc.DELETE_RULE,
+                rc.UPDATE_RULE
+            FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS rc
+            JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE fk
+              ON rc.CONSTRAINT_NAME = fk.CONSTRAINT_NAME
+             AND rc.CONSTRAINT_SCHEMA = fk.CONSTRAINT_SCHEMA
+        """
+        try:
+            cursor.execute(sql)
+            rows = cursor.fetchall()
+        except Exception:
+            return {}
+        result = {}
+        for table, column, cname, on_delete, on_update in rows:
+            result[(table, column)] = {
+                "constraint_name": cname,
+                "on_delete": on_delete or "",
+                "on_update": on_update or "",
+            }
+        return result
+
+    def _fk_rules_postgresql(self, cursor) -> dict[tuple[str, str], dict[str, str]]:
+        sql = """
+            SELECT
+                tc.table_name,
+                kcu.column_name,
+                tc.constraint_name,
+                rc.delete_rule,
+                rc.update_rule
+            FROM information_schema.table_constraints tc
+            JOIN information_schema.key_column_usage kcu
+              ON tc.constraint_name = kcu.constraint_name
+             AND tc.table_schema = kcu.table_schema
+            JOIN information_schema.referential_constraints rc
+              ON tc.constraint_name = rc.constraint_name
+             AND tc.table_schema = rc.constraint_schema
+            WHERE tc.constraint_type = 'FOREIGN KEY'
+        """
+        try:
+            cursor.execute(sql)
+            rows = cursor.fetchall()
+        except Exception:
+            return {}
+        result = {}
+        for table, column, cname, on_delete, on_update in rows:
+            result[(table, column)] = {
+                "constraint_name": cname,
+                "on_delete": on_delete or "",
+                "on_update": on_update or "",
+            }
+        return result
+
+    def _fk_rules_mysql(self, cursor) -> dict[tuple[str, str], dict[str, str]]:
+        sql = """
+            SELECT
+                kcu.TABLE_NAME,
+                kcu.COLUMN_NAME,
+                kcu.CONSTRAINT_NAME,
+                rc.DELETE_RULE,
+                rc.UPDATE_RULE
+            FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+            JOIN INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS rc
+              ON kcu.CONSTRAINT_NAME = rc.CONSTRAINT_NAME
+             AND kcu.CONSTRAINT_SCHEMA = rc.CONSTRAINT_SCHEMA
+            WHERE kcu.REFERENCED_TABLE_NAME IS NOT NULL
+              AND kcu.TABLE_SCHEMA = DATABASE()
+        """
+        try:
+            cursor.execute(sql)
+            rows = cursor.fetchall()
+        except Exception:
+            return {}
+        result = {}
+        for table, column, cname, on_delete, on_update in rows:
+            result[(table, column)] = {
+                "constraint_name": cname,
+                "on_delete": on_delete or "",
+                "on_update": on_update or "",
+            }
+        return result
+
+    def _build_incoming_fks(
+        self, tables: list[TableInfo]
+    ) -> dict[str, list[ForeignKeyInfo]]:
+        incoming: dict[str, list[ForeignKeyInfo]] = defaultdict(list)
+        for table in tables:
+            for fk in table.outgoing_fks:
+                incoming[fk.to_table].append(fk)
+        for refs in incoming.values():
+            refs.sort(key=lambda f: (f.from_table, f.from_column))
+        return dict(incoming)
+
+    def _row_count(self, cursor, table_name: str) -> int | None:
+        qn = self.connection.ops.quote_name(table_name)
+        try:
+            cursor.execute(f"SELECT COUNT(*) FROM {qn}")
+            return int(cursor.fetchone()[0])
+        except Exception:
+            return None
+
+    @staticmethod
+    def _format_default(value: Any) -> str | None:
+        if value is None:
+            return None
+        text = str(value).strip()
+        if len(text) > 80:
+            return text[:77] + "..."
+        return text

django_db_schema_doc-1.0.0/db_schema_doc/management/commands/generate_database_doc.py

@@ -0,0 +1,133 @@
+"""
+Management command: generate DATABASE.md (or custom path) from the configured database.
+
+Portable across Django projects — add ``db_schema_doc`` to INSTALLED_APPS (or copy
+this package into your project) and run::
+
+    python manage.py generate_database_doc
+
+See db_schema_doc/README.md for setup in other projects.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from django.conf import settings
+from django.core.management.base import BaseCommand, CommandError
+from django.db import connections
+
+from db_schema_doc.collector import SchemaCollector
+from db_schema_doc.writer import MarkdownWriter
+
+
+class Command(BaseCommand):
+    help = (
+        "Generate Markdown database schema documentation (DATABASE.md) "
+        "from the configured Django database connection."
+    )
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "-o",
+            "--output",
+            default="DATABASE.md",
+            help="Output Markdown file path (default: DATABASE.md in project root).",
+        )
+        parser.add_argument(
+            "--database",
+            default="default",
+            help="DATABASES alias to introspect (default: default).",
+        )
+        parser.add_argument(
+            "--title",
+            default="",
+            help="Document title (default: '<db_name> Database Schema Reference').",
+        )
+        parser.add_argument(
+            "--include-views",
+            action="store_true",
+            help="Include database views in the documentation.",
+        )
+        parser.add_argument(
+            "--with-row-counts",
+            action="store_true",
+            help="Run COUNT(*) per table (slow on large databases).",
+        )
+        parser.add_argument(
+            "--hub-limit",
+            type=int,
+            default=25,
+            help="Number of hub tables to list in the overview (default: 25).",
+        )
+        parser.add_argument(
+            "--no-fk-index",
+            action="store_true",
+            help="Omit the foreign-key relationship index section.",
+        )
+        parser.add_argument(
+            "--no-hub-section",
+            action="store_true",
+            help="Omit the hub-tables overview section.",
+        )
+        parser.add_argument(
+            "--project-hints",
+            default="",
+            help="Optional Markdown paragraph with project-specific notes for agents.",
+        )
+        parser.add_argument(
+            "--stdout",
+            action="store_true",
+            help="Print Markdown to stdout instead of writing a file.",
+        )
+
+    def handle(self, *args, **options):
+        database = options["database"]
+        if database not in connections.databases:
+            raise CommandError(
+                f"Unknown database alias {database!r}. "
+                f"Available: {', '.join(sorted(connections.databases))}"
+            )
+
+        self.stdout.write(f"Introspecting database {database!r}...")
+        collector = SchemaCollector(
+            database=database,
+            include_views=options["include_views"],
+        )
+        schema = collector.collect(row_counts=options["with_row_counts"])
+
+        title = options["title"] or None
+        hints = options["project_hints"] or None
+        writer = MarkdownWriter(
+            schema,
+            title=title,
+            include_fk_index=not options["no_fk_index"],
+            include_hub_section=not options["no_hub_section"],
+            hub_limit=options["hub_limit"],
+            project_hints=hints,
+        )
+        markdown = writer.write()
+
+        if options["stdout"]:
+            self.stdout.write(markdown)
+            return
+
+        output_path = self._resolve_output_path(options["output"])
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(markdown, encoding="utf-8")
+
+        size_kb = output_path.stat().st_size / 1024
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Wrote {output_path} "
+                f"({len(schema.tables)} tables, {schema.column_count} columns, "
+                f"{schema.fk_count} FKs, {size_kb:.1f} KB)"
+            )
+        )
+
+    def _resolve_output_path(self, output: str) -> Path:
+        path = Path(output)
+        if path.is_absolute():
+            return path
+        base = Path(getattr(settings, "BASE_DIR", Path.cwd()))
+        return base / path

django_db_schema_doc-1.0.0/db_schema_doc/writer.py

@@ -0,0 +1,282 @@
+"""
+Render DatabaseSchema as Markdown for LLM / human consumption.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from .collector import DatabaseSchema, ForeignKeyInfo, TableInfo
+
+
+# Known framework table prefixes (any Django project)
+FRAMEWORK_PREFIXES = (
+    "django_",
+    "auth_",
+    "django_celery_beat_",
+    "jet_",
+    "south_",
+)
+
+
+def infer_domain(table_name: str) -> str:
+    """Group tables by first underscore segment, with framework heuristics."""
+    for prefix in FRAMEWORK_PREFIXES:
+        if table_name.startswith(prefix):
+            return "django_system"
+    if "_" in table_name:
+        return table_name.split("_", 1)[0]
+    return "other"
+
+
+def hub_tables(schema: DatabaseSchema, limit: int = 25) -> list[tuple[str, int, int | None]]:
+    """Tables most often referenced by FKs (incoming), with optional row counts."""
+    in_degree: dict[str, int] = defaultdict(int)
+    row_by_name = {t.name: t.row_count for t in schema.tables}
+    for table in schema.tables:
+        for fk in table.outgoing_fks:
+            in_degree[fk.to_table] += 1
+    ranked = sorted(in_degree.items(), key=lambda x: (-x[1], x[0]))[:limit]
+    return [(name, deg, row_by_name.get(name)) for name, deg in ranked]
+
+
+class MarkdownWriter:
+    def __init__(
+        self,
+        schema: DatabaseSchema,
+        *,
+        title: str | None = None,
+        include_fk_index: bool = True,
+        include_hub_section: bool = True,
+        hub_limit: int = 25,
+        project_hints: str | None = None,
+    ):
+        self.schema = schema
+        self.title = title or f"{schema.database_name} Database Schema Reference"
+        self.include_fk_index = include_fk_index
+        self.include_hub_section = include_hub_section
+        self.hub_limit = hub_limit
+        self.project_hints = project_hints
+
+    def write(self) -> str:
+        lines: list[str] = []
+        w = lines.append
+
+        w(f"# {self.title}")
+        w("")
+        w(
+            f"> Auto-generated by `python manage.py generate_database_doc` "
+            f"| {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}"
+        )
+        w(
+            f"> Tables: {len(self.schema.tables)} | "
+            f"Columns: {self.schema.column_count} | "
+            f"Foreign keys: {self.schema.fk_count}"
+        )
+        w("")
+        w("---")
+        w("")
+        self._section_purpose(w)
+        self._section_connection(w)
+        if self.project_hints:
+            w("### Project notes")
+            w("")
+            w(self.project_hints)
+            w("")
+            w("---")
+            w("")
+        self._section_domains(w)
+        if self.include_hub_section:
+            self._section_hubs(w)
+        self._section_toc(w)
+        if self.include_fk_index:
+            self._section_fk_index(w)
+        self._section_tables(w)
+
+        return "\n".join(lines) + "\n"
+
+    def _section_purpose(self, w) -> None:
+        w("## 1. Purpose and how to use this document")
+        w("")
+        w("This file describes the **live database schema** behind your Django project's")
+        w("`DATABASES` configuration. Use it to:")
+        w("")
+        w("- Write correct SQL with real table and column names")
+        w("- Understand relationships via foreign keys")
+        w("- Navigate tables grouped by name prefix / domain")
+        w("")
+        w("**Conventions:**")
+        w("")
+        w("- Table names match the database (often `app_label_modelname` when using Django migrations).")
+        w("- Column types are shown as Django field class names from introspection (e.g. `CharField`, `BigAutoField`).")
+        w("- 🔑 marks primary key columns.")
+        w("")
+        w("---")
+        w("")
+
+    def _section_connection(self, w) -> None:
+        w("## 2. Connection metadata")
+        w("")
+        w("| Setting | Value |")
+        w("|--------|-------|")
+        w(f"| Engine | `{self.schema.engine}` |")
+        w(f"| Vendor | `{self.schema.vendor}` |")
+        w(f"| Database | `{self.schema.database_name}` |")
+        w(f"| Host | `{self.schema.host}` |")
+        w(f"| Port | `{self.schema.port}` |")
+        w("")
+        w("Credentials come from environment variables / settings — never commit passwords.")
+        w("")
+        w("---")
+        w("")
+
+    def _section_domains(self, w) -> None:
+        w("## 3. Domain overview")
+        w("")
+        domains: dict[str, list[TableInfo]] = defaultdict(list)
+        for table in self.schema.tables:
+            domains[infer_domain(table.name)].append(table)
+
+        w("| Domain | Tables |")
+        w("|--------|--------|")
+        for dom in sorted(domains.keys(), key=lambda x: (-len(domains[x]), x)):
+            w(f"| `{dom}` | {len(domains[dom])} |")
+        w("")
+        w("---")
+        w("")
+
+    def _section_hubs(self, w) -> None:
+        w("## 4. Hub tables (most referenced by foreign keys)")
+        w("")
+        hubs = hub_tables(self.schema, self.hub_limit)
+        if not hubs:
+            w("*(No foreign keys detected.)*")
+            w("")
+            w("---")
+            w("")
+            return
+
+        w("| Table | Referenced by | Rows |")
+        w("|-------|---------------|------|")
+        for name, deg, rows in hubs:
+            row_s = str(rows) if rows is not None else "—"
+            w(f"| `{name}` | {deg} | {row_s} |")
+        w("")
+        w("---")
+        w("")
+
+    def _section_toc(self, w) -> None:
+        section = "5" if self.include_hub_section else "4"
+        w(f"## {section}. Table of contents (by domain)")
+        w("")
+        domains: dict[str, list[TableInfo]] = defaultdict(list)
+        for table in self.schema.tables:
+            domains[infer_domain(table.name)].append(table)
+
+        for dom in sorted(domains.keys(), key=lambda x: (-len(domains[x]), x)):
+            w(f"### {dom}")
+            for table in sorted(domains[dom], key=lambda t: t.name):
+                anchor = table.name.lower()
+                w(f"- [{table.name}](#table-{anchor})")
+            w("")
+        w("---")
+        w("")
+
+    def _section_fk_index(self, w) -> None:
+        section = "6" if self.include_hub_section else "5"
+        w(f"## {section}. Foreign key relationship index")
+        w("")
+        w("Outgoing foreign keys per table (`child.column` → `parent.column`).")
+        w("")
+        for table in self.schema.tables:
+            if not table.outgoing_fks:
+                continue
+            w(f"### `{table.name}`")
+            for fk in table.outgoing_fks:
+                w(self._fk_line(fk))
+            w("")
+        w("---")
+        w("")
+
+    def _section_tables(self, w) -> None:
+        base = 7 if self.include_hub_section else 6
+        if not self.include_fk_index:
+            base -= 1
+        w(f"## {base}. Tables — columns, keys, indexes")
+        w("")
+
+        for table in sorted(self.schema.tables, key=lambda t: t.name):
+            self._write_table(w, table)
+            w("---")
+            w("")
+
+    def _write_table(self, w, table: TableInfo) -> None:
+        anchor = table.name.lower()
+        dom = infer_domain(table.name)
+
+        w(f'<a id="table-{anchor}"></a>')
+        w(f"### `{table.name}`")
+        w("")
+        w(f"- **Domain:** `{dom}`")
+        if table.primary_key:
+            w(f"- **Primary key:** `{', '.join(table.primary_key)}`")
+        else:
+            w("- **Primary key:** *(none)*")
+        if table.row_count is not None:
+            w(f"- **Row count:** {table.row_count}")
+        w("")
+
+        if table.outgoing_fks:
+            w("**References (outgoing):**")
+            w("")
+            for fk in table.outgoing_fks:
+                w(self._fk_line(fk, prefix="- "))
+            w("")
+
+        if table.incoming_fks:
+            w("**Referenced by (incoming):**")
+            w("")
+            for fk in table.incoming_fks:
+                w(
+                    f"- `{fk.from_table}.{fk.from_column}` → "
+                    f"`{table.name}.{fk.to_column}`"
+                )
+            w("")
+
+        w("**Columns:**")
+        w("")
+        w("| # | Column | Type | Nullable | Default |")
+        w("|---|--------|------|----------|---------|")
+        for col in table.columns:
+            pk = " 🔑" if col.is_primary_key else ""
+            null = "YES" if col.nullable else "NO"
+            default = col.default or ""
+            w(
+                f"| {col.ordinal} | `{col.name}`{pk} | {col.type_display} "
+                f"| {null} | {default} |"
+            )
+        w("")
+
+        if table.indexes:
+            w("**Indexes:**")
+            w("")
+            for idx in table.indexes:
+                uniq = "UNIQUE " if idx.unique else ""
+                cols = ", ".join(idx.columns)
+                w(f"- `{idx.name}` ({uniq}): {cols}")
+            w("")
+
+    @staticmethod
+    def _fk_line(fk: ForeignKeyInfo, prefix: str = "- ") -> str:
+        rules = ""
+        if fk.on_delete or fk.on_update:
+            parts = []
+            if fk.on_delete:
+                parts.append(f"ON DELETE `{fk.on_delete}`")
+            if fk.on_update:
+                parts.append(f"ON UPDATE `{fk.on_update}`")
+            rules = " — " + ", ".join(parts)
+        return (
+            f"{prefix}`{fk.from_column}` → `{fk.to_table}.{fk.to_column}`{rules}"
+        )

django_db_schema_doc-1.0.0/django_db_schema_doc.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: django-db-schema-doc
+Version: 1.0.0
+Summary: Generate DATABASE.md schema documentation for Django projects and LLM agents
+Author: MrHiB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/behzad-njf/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"
+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/)
+
+Generate **DATABASE.md** — full schema documentation for developers and LLM/AI agents — from any database configured in your Django project's `DATABASES`.
+
+Supports **PostgreSQL**, **MySQL/MariaDB**, **Microsoft SQL Server**, **SQLite**, **Oracle**, and other backends Django can introspect.
+
+## Install
+
+```bash
+pip install django-db-schema-doc
+```
+
+## Setup
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "db_schema_doc",
+]
+```
+
+## Usage
+
+```bash
+python manage.py generate_database_doc
+```
+
+Writes `DATABASE.md` in your project `BASE_DIR` by default.
+
+### Common options
+
+```bash
+python manage.py generate_database_doc -o docs/schema.md
+python manage.py generate_database_doc --with-row-counts
+python manage.py generate_database_doc --database reporting
+python manage.py generate_database_doc --project-hints "See accounts_childuserrelation for parent-child links."
+```
+
+Run `python manage.py generate_database_doc --help` for all options.
+
+## What is generated
+
+- Connection metadata (engine, vendor, database — no passwords)
+- Tables grouped by name prefix (`app_model` style)
+- Hub tables (most referenced by foreign keys)
+- Table of contents with anchors
+- Foreign key index
+- Per table: columns, types, PKs, indexes, incoming/outgoing FKs
+
+On PostgreSQL, MySQL, and SQL Server, foreign keys include `ON DELETE` / `ON UPDATE` rules when available.
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- Your project's database driver (e.g. `psycopg`, `mysqlclient`, `mssql-django`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

django_db_schema_doc-1.0.0/django_db_schema_doc.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+db_schema_doc/__init__.py
+db_schema_doc/apps.py
+db_schema_doc/collector.py
+db_schema_doc/py.typed
+db_schema_doc/writer.py
+db_schema_doc/management/__init__.py
+db_schema_doc/management/commands/__init__.py
+db_schema_doc/management/commands/generate_database_doc.py
+django_db_schema_doc.egg-info/PKG-INFO
+django_db_schema_doc.egg-info/SOURCES.txt
+django_db_schema_doc.egg-info/dependency_links.txt
+django_db_schema_doc.egg-info/requires.txt
+django_db_schema_doc.egg-info/top_level.txt

django_db_schema_doc-1.0.0/django_db_schema_doc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_db_schema_doc-1.0.0/django_db_schema_doc.egg-info/requires.txt

@@ -0,0 +1,6 @@
+Django>=4.2
+
+[dev]
+build>=1.0
+twine>=4.0
+ruff>=0.1

django_db_schema_doc-1.0.0/django_db_schema_doc.egg-info/top_level.txt

@@ -0,0 +1 @@
+db_schema_doc

django_db_schema_doc-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-db-schema-doc"
+version = "1.0.0"
+description = "Generate DATABASE.md schema documentation for Django projects and LLM agents"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "MrHiB" },
+]
+keywords = ["django", "database", "schema", "documentation", "llm", "markdown", "introspection"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Documentation",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "Django>=4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.0",
+    "twine>=4.0",
+    "ruff>=0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/behzad-njf/django-db-schema-doc"
+Documentation = "https://github.com/behzad-njf/django-db-schema-doc#readme"
+Repository = "https://github.com/behzad-njf/django-db-schema-doc"
+Issues = "https://github.com/behzad-njf/django-db-schema-doc/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["db_schema_doc*"]
+
+[tool.setuptools.package-data]
+db_schema_doc = ["py.typed"]

django_db_schema_doc-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+