Metadata-Version: 2.5
Name: laranex-schema-viewer
Version: 0.6.0
Summary: laranex-schema 2.0 documents, an ERD viewer, and read-only MCP tools for SQLAlchemy, SQLModel, Django, Tortoise ORM, and Peewee
Project-URL: Homepage, https://github.com/laranex/python-schema-viewer
Project-URL: Documentation, https://laranex.github.io/python-schema-viewer/
Project-URL: Repository, https://github.com/laranex/python-schema-viewer
Project-URL: Issues, https://github.com/laranex/python-schema-viewer/issues
Project-URL: Changelog, https://github.com/laranex/python-schema-viewer/blob/main/CHANGELOG.md
Author-email: Soe Thura <thixpin@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: database,django,erd,mcp,peewee,schema,sqlalchemy,sqlmodel,tortoise-orm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: tomli>=1.1; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: django<7,>=4.2; extra == 'dev'
Requires-Dist: mcp<3,>=2.3; extra == 'dev'
Requires-Dist: peewee<5,>=3.19; extra == 'dev'
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'dev'
Requires-Dist: pymysql[rsa]<2,>=1.1; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff<0.18,>=0.8; extra == 'dev'
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'dev'
Requires-Dist: sqlmodel<0.1,>=0.0.22; extra == 'dev'
Requires-Dist: tortoise-orm<2,>=1.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django<7,>=4.2; extra == 'django'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
Provides-Extra: mysql
Requires-Dist: pymysql[rsa]<2,>=1.1; extra == 'mysql'
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'mysql'
Provides-Extra: peewee
Requires-Dist: peewee<5,>=3.19; extra == 'peewee'
Provides-Extra: postgresql
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgresql'
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'postgresql'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'sqlalchemy'
Provides-Extra: sqlmodel
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'sqlmodel'
Requires-Dist: sqlmodel<0.1,>=0.0.22; extra == 'sqlmodel'
Provides-Extra: tortoise
Requires-Dist: tortoise-orm<2,>=1.0; extra == 'tortoise'
Description-Content-Type: text/markdown

# 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](https://github.com/laranex/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](https://laranex.github.io/schema-viewer-ui/contract) 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:

```bash
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](https://docs.astral.sh/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](https://laranex.github.io/python-schema-viewer/installation.html).

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](https://laranex.github.io/python-schema-viewer/viewer.html), 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](https://github.com/laranex/python-schema-viewer/blob/main/SECURITY.md) and the shared [viewer security policy](https://laranex.github.io/schema-viewer-ui/security.html).

## Documentation

- [Installation](https://laranex.github.io/python-schema-viewer/installation.html) and [quick start](https://laranex.github.io/python-schema-viewer/quick-start.html)
- [Supported ORMs](https://laranex.github.io/python-schema-viewer/orm-support.html): [SQLAlchemy](https://laranex.github.io/python-schema-viewer/sqlalchemy.html), [SQLModel](https://laranex.github.io/python-schema-viewer/sqlmodel.html), [Django](https://laranex.github.io/python-schema-viewer/django.html), [Tortoise ORM](https://laranex.github.io/python-schema-viewer/tortoise.html), [Peewee](https://laranex.github.io/python-schema-viewer/peewee.html), and [model discovery](https://laranex.github.io/python-schema-viewer/discovery.html)
- [CLI reference](https://laranex.github.io/python-schema-viewer/cli.html), [database introspection](https://laranex.github.io/python-schema-viewer/database.html), [schema comparison](https://laranex.github.io/python-schema-viewer/comparison.html) of tenant schemas and connections, the [CI schema drift gate](https://laranex.github.io/python-schema-viewer/check.html) (`check`), and [interactive viewer](https://laranex.github.io/python-schema-viewer/viewer.html)
- [MCP for Codex and Claude Code](https://laranex.github.io/python-schema-viewer/mcp.html)
- [Agent skills](https://laranex.github.io/python-schema-viewer/agent-skills.html) and [troubleshooting](https://laranex.github.io/python-schema-viewer/troubleshooting.html)

Install agent skills with `npx skills add laranex/python-schema-viewer`; see the [skills guide](https://laranex.github.io/python-schema-viewer/agent-skills.html).

## Contributing

See [CONTRIBUTING.md](https://github.com/laranex/python-schema-viewer/blob/main/CONTRIBUTING.md) for synthetic fixtures, the allowlist and the pre-commit scan, and [AGENTS.md](https://github.com/laranex/python-schema-viewer/blob/main/AGENTS.md) for architecture, development commands, testing, and documentation maintenance. [Validation](https://github.com/laranex/python-schema-viewer/blob/main/docs/validation.md) and [skill verification](https://github.com/laranex/python-schema-viewer/blob/main/docs/agent-skills-validation.md) describe test coverage and limitations. Report vulnerabilities as described in [SECURITY.md](https://github.com/laranex/python-schema-viewer/blob/main/SECURITY.md). Release notes are in the [changelog](https://github.com/laranex/python-schema-viewer/blob/main/CHANGELOG.md).

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

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

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

## License

[MIT](https://github.com/laranex/python-schema-viewer/blob/main/LICENSE). See [NOTICE](https://github.com/laranex/python-schema-viewer/blob/main/NOTICE) for attribution.
