db_tools: Instructions file for Codex

AGENTS.md — db_tools

Guidance for agents working in this app. Read this before adding or changing a tool.

What this app is

A Frappe app that ships a suite of read-only database inspection tools, served as website pages under /db_tools. There are no DocTypes and no desk pages — every tool is a whitelisted API plus a Jinja page.

All eighteen tools are implemented and working. Nothing is stubbed.

Layout

db_tools/
├── backend/
│   ├── __init__.py                 # TOOLS registry — drives the /db_tools hub page
│   ├── common.py                   # shared helpers: guard(), coercion, renderers
│   └── <tool_key>/
│       ├── __init__.py             # module docstring explaining the tool
│       └── api.py                  # pure logic + @frappe.whitelist() endpoint
├── templates/
│   └── db_tools_base.html          # shared CSS + the DBTool frontend engine
└── www/db_tools/
    ├── index.py / index.html       # the hub page
    └── <tool_key>/
        ├── index.py                # get_context — blocks Guest
        └── index.html              # extends the base template, supplies a config

broken_link_detector is the one tool split across several modules (scanner.py, validator.py, queries.py, models.py, report.py) because it is substantially more complex. Every other tool fits in a single api.py.

database_tools/api.py is a backwards-compatible shim re-exporting backend.schema_comparison.api. Leave it alone unless removing it deliberately.

The eighteen tools

Every endpoint is prefixed db_tools.backend.. category on each registry entry drives the hub page's filter chips.

#	Key	Category	Endpoint (<key>.api.…)
01	schema_comparison	Schema	get_extra_db_columns_report
02	broken_link_detector	Integrity	get_broken_links_report
03	orphan_child_detector	Integrity	get_orphan_children_report
04	orphan_table_finder	Schema	get_orphan_tables_report
05	largest_tables_analyzer	Storage	get_largest_tables_report
06	duplicate_index_detector	Performance	get_duplicate_indexes_report
07	missing_index_advisor	Performance	get_missing_indexes_report
08	database_health_report	Operations	get_health_report
09	migration_sql_generator	Operations	get_migration_sql
10	site_schema_comparison	Operations	get_site_schema_comparison, get_sites
11	schema_drift_detector	Schema	get_schema_drift_report
12	empty_column_analyzer	Storage	get_empty_columns_report
13	log_table_analyzer	Storage	get_log_tables_report
14	customization_auditor	Integrity	get_customization_report
15	collation_auditor	Schema	get_collation_report
16	fragmentation_analyzer	Performance	get_fragmentation_report
17	row_size_auditor	Schema	get_row_size_report
18	mariadb_limits_auditor	Schema	get_limits_report