Laranex Schema Viewer

Framework-independent schema documents, an interactive ERD, and read-only MCP tools for SQLAlchemy 2.x, SQLModel, Django, Tortoise ORM, and Peewee. Inspired by Laravel Schema Viewer.

Build once from model definitions, a live database's catalogs (read-only), or both reconciled with drift, then browse or query the saved JSON without starting your application. Every build writes a laranex-schema 2.0 document, the format the Laravel and Node.js schema viewers share. Foreign keys and declared ORM relationships remain separate throughout extraction, viewing, and MCP queries.

Quick start

Requires Python 3.10+. Install from PyPI in an isolated environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'laranex-schema-viewer[sqlmodel,mcp]'

cd /absolute/path/to/application
laranex-schema-viewer init     # optional: save defaults in pyproject.toml
laranex-schema-viewer build    # finds your models package; writes schema-viewer.json
laranex-schema-viewer serve

Replace sqlmodel with your ORM's extra: sqlalchemy, django, tortoise, or peewee. In a Django project, build reads the settings module from manage.py.

With uv, add it to your application instead: uv add --dev 'laranex-schema-viewer[sqlmodel,mcp]', then prefix commands with uv run. The python3 bundled with macOS is 3.9 and is not supported; see installation.

Open http://127.0.0.1:8765 to search tables, inspect indexes and relationships, and navigate the graph. The viewer is the shared Laranex Schema Viewer UI, packaged prebuilt: it needs no Node.js or web framework and loads nothing from the internet.

Build only trusted modules: imports and mapper callbacks execute application code. A declared document describes model metadata, not deployed database state; review documents before sharing.

Security notice

• The viewer is a development tool: never expose it in production. serve has no authentication and is for one developer on loopback only; reach it from elsewhere only through an authenticated HTTPS reverse proxy or tunnel.
• Schema snapshots and every export of them (offline HTML, JSON, DBML, Mermaid, Markdown, SVG, PNG), and gate reports, reveal your schema. Never commit or publish them, even in a private repository.
• If you serve the viewer or a document any other way, protect every delivery path server-side: page, assets, document, downloads and caches.
• Run laranex-schema-viewer scan --tracked --untracked in a pre-commit hook and in CI, and fail on any non-zero exit.

See SECURITY.md and the shared viewer security policy.

Documentation

• Installation and quick start
• Supported ORMs: SQLAlchemy, SQLModel, Django, Tortoise ORM, Peewee, and model discovery
• CLI reference, database introspection, schema comparison of tenant schemas and connections, the CI schema drift gate (check), and interactive viewer
• MCP for Codex and Claude Code
• Agent skills and troubleshooting

Install agent skills with npx skills add laranex/python-schema-viewer; see the skills guide.

Contributing

See CONTRIBUTING.md for synthetic fixtures, the allowlist and the pre-commit scan, and AGENTS.md for architecture, development commands, testing, and documentation maintenance. Validation and skill verification describe test coverage and limitations. Report vulnerabilities as described in SECURITY.md. Release notes are in the changelog.

Documentation Markdown lives in docs/; VitePress tooling lives in .gh-page/:

cd .gh-page
npm install
npm run dev -- --port 5173 --strictPort

Preview at http://127.0.0.1:5173/python-schema-viewer/.

License

MIT. See NOTICE for attribution.