Metadata-Version: 2.4
Name: erdscope
Version: 0.12.1
Summary: Interactive, self-contained ER-diagram HTML and Excel table definitions from a MySQL, PostgreSQL, or SQLite database and/or application code (Rails / Prisma / Django / SQLAlchemy / Laravel) — single file, zero required dependencies
Author: tas6
License-Expression: MIT
Project-URL: Homepage, https://github.com/orapli/erdscope
Project-URL: Documentation, https://orapli.github.io/erdscope/manual.html
Project-URL: Live demo, https://orapli.github.io/erdscope/
Project-URL: Repository, https://github.com/orapli/erdscope
Project-URL: Issues, https://github.com/orapli/erdscope/issues
Keywords: erd,er-diagram,database,schema,mysql,postgresql,postgres,sqlite,rails,prisma,django,sqlalchemy,laravel,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mysql
Requires-Dist: PyMySQL; extra == "mysql"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]; extra == "postgres"
Provides-Extra: yaml
Requires-Dist: PyYAML; extra == "yaml"
Provides-Extra: all
Requires-Dist: PyMySQL; extra == "all"
Requires-Dist: psycopg[binary]; extra == "all"
Requires-Dist: PyYAML; extra == "all"
Dynamic: license-file

<div align="center">
  <img src="docs/img/erdscope-banner.svg" alt="erdscope — explore the schema you have" width="100%">

  **Database, application code, or config — turn whatever you have into one explorable schema.**

  [![CI](https://github.com/orapli/erdscope/actions/workflows/ci.yml/badge.svg)](https://github.com/orapli/erdscope/actions/workflows/ci.yml)
  [![PyPI](https://img.shields.io/pypi/v/erdscope)](https://pypi.org/project/erdscope/)
  [![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB)](https://pypi.org/project/erdscope/)
  [![License](https://img.shields.io/badge/license-MIT-14B8A6)](LICENSE)

  [Live demo](https://orapli.github.io/erdscope/) · [Recipes](https://orapli.github.io/erdscope/recipes.html) · [User manual](https://orapli.github.io/erdscope/manual.html) · [日本語 README](README.ja.md)
</div>

erdscope generates a **self-contained, interactive ER diagram** and, when you want it,
an **Excel table-definition workbook**. Start with a database, model code, a config file,
or any combination of them. The result is one portable HTML file you can explore, share,
and keep with your project.

```bash
pip install erdscope
erdscope demo
```

That is the whole quickstart. A sample shop diagram opens in your browser—no database,
account, or project setup required.

[![Interactive diagram generated by erdscope](docs/screenshot.png)](https://orapli.github.io/erdscope/)

## Who this helps

- **Onboarding onto an existing database.** Point erdscope at a live MySQL/PostgreSQL/SQLite
  connection with a read-only account and get an explorable diagram of what's actually
  deployed, instead of a stale hand-drawn ERD or none at all.
- **Reviewing models with no database access.** Point `--models` at a Rails, Prisma, Django,
  SQLAlchemy, or Laravel project and get the same kind of diagram from static analysis
  alone — useful for code review or working against a codebase you don't have DB
  credentials for.
- **Handing a schema to a client or auditor.** The output is one self-contained HTML
  file — nothing to install or host on their end. Add `notes:` for the design rationale
  and export an Excel workbook alongside it for anyone who wants it in a spreadsheet.

## Why trust it with your schema

- Runs **entirely locally** and sends nothing over the network beyond the database
  connection you give it — no telemetry, no external service involved.
- A **read-only database account is enough**: erdscope only ever reads schema metadata,
  never writes.
- The **generated HTML is self-contained** — no CDN dependency, nothing fetched once
  it's open in a browser.
- Merging DB structure, code-level associations, and your own documentation into one
  file is what sets erdscope apart from tools that only do one of the three.

## Bring whatever schema you have

<div align="center">
  <img src="docs/img/input-flow.svg" alt="Database, application code, and config merge into an interactive ER diagram and Excel workbook" width="880">
</div>

| Start from | What erdscope reads | Good for |
|---|---|---|
| **A database** | MySQL, PostgreSQL, or SQLite catalogs | Exploring the schema that is actually deployed |
| **Application code** | Rails, Prisma, Django, SQLAlchemy, or Laravel projects | Reviewing a project without database access |
| **Config** | JSON or YAML source declarations, tables, relations, notes, and groups | Reusing settings, designing a schema, or adding documentation |

Use just one source, or combine them. Physical database facts, application-level
associations, and your explicit documentation are merged into one consistent view.

The examples below use CLI arguments when that makes the input obvious. For repeatable
usage, put the same settings and model sources in `.erdscope.json`, `.erdscope.yml`, or
another file selected with `--config`. A config can also define a complete schema by
itself. Explicit CLI arguments override the corresponding config values.

## Pick your starting point

### Explore a live database

```bash
erdscope postgres://readonly@127.0.0.1:5432/myapp -o schema.html
```

MySQL uses the same shape. SQLite needs no driver and works with Python's standard library:

```bash
erdscope sqlite:///path/to/app.db -o schema.html
```

### Review application models without a database

```bash
# Rails, Prisma, Django, SQLAlchemy, or Laravel project — auto-detected
erdscope --models ./my-app -o schema.html
```

### Sketch or document a schema from config alone

```bash
erdscope --config examples/schema-only.json -o schema.html
```

[`examples/schema-only.json`](examples/schema-only.json) is a complete, zero-database
example with tables, relations, notes, and a domain group. Config can also patch or remove
items supplied by another source. See the [config guide](https://orapli.github.io/erdscope/manual.html#config-file).

### Combine database facts, application context, and documentation

```bash
erdscope mysql://readonly@127.0.0.1:3306/myapp \
  --config .erdscope.yml \
  -o schema.html
```

```yaml
# .erdscope.yml
models:
  - ./app/models
groups:
  - { id: sales, title: Sales, tables: [orders, order_items] }
notes:
  - id: order-retention
    target: { type: table, table: orders }
    text: Orders are retained for seven years after account closure.
```

This is where the layered input model shines: use the database for columns and real
foreign keys, code for associations such as polymorphic or through relations, and config
for corrections, domain groups, operational notes, and ADR links.

### Hand off both a diagram and table definitions

```bash
erdscope sqlite:///path/to/app.db \
  -o schema.html \
  --excel table-definitions.xlsx
```

The HTML is self-contained and the workbook can be styled with an Excel template—useful
for reviews, audits, onboarding, and documentation deliverables.

## What you can do in the viewer

- Search tables, columns, comments, and attached notes.
- Focus on dependencies or dependents and control traversal depth.
- Hide tables, rearrange the layout, and move domain groups together.
- Inspect DB FKs, schema FKs, declared associations, and inferred relations.
- Save named views and share a link to the current view.
- Export the current canvas as PNG or SVG, or print it cleanly.
- Switch to dark mode; everything runs locally in the generated HTML.

Try these interactions in the **[live demo](https://orapli.github.io/erdscope/)**, or use
the illustrated **[viewer guide](https://orapli.github.io/erdscope/manual.html#viewer-guide)**.

## Installation

```bash
pip install erdscope
```

The core CLI, SQLite reader, HTML generator, and Excel writer use only the Python standard
library. Install an optional driver when you want a direct server connection:

```bash
pip install 'erdscope[mysql]'     # PyMySQL
pip install 'erdscope[postgres]'  # psycopg
pip install 'erdscope[yaml]'      # PyYAML for .yml/.yaml config
pip install 'erdscope[all]'
```

Prefer a single file? Download [`erd.py`](erd.py) and run it with Python 3.9+:

```bash
python3 erd.py demo
```

## Config and CLI overrides

Config is the convenient home for recurring inputs and settings. It is auto-discovered
as `.erdscope.json`, `.erdscope.yml`, or `.erdscope.yaml` in the current directory, or
you can select a file with `--config`. When the same setting is supplied both ways, the
explicit CLI argument wins.

| Option | Purpose |
|---|---|
| `--config PATH` | Load model sources, defaults, schema definitions or patches, notes, and groups |
| `--models PATH` | Override config `models` with Rails, Prisma, Django, SQLAlchemy, or Laravel input; repeatable |
| `--excel FILE.xlsx` | Also generate a table-definition workbook (includes Notes/Groups sheets when configured) |
| `--emit-json FILE.json` | Also write a canonical JSON schema snapshot with a content fingerprint (`-` for stdout) |
| `--emit-config FILE.yml\|.json` | Also write the schema as a config-authoring file, re-importable via `--config` (`-` for stdout, always JSON) |
| `--diff SNAPSHOT.json` | Compare this run against a saved `--emit-json` snapshot and exit 0/1/2 instead of generating output (CI drift gate) |
| `--emit-digest FILE.md` | Also write a token-efficient Markdown digest of the schema, with design notes, for LLMs/agents (`-` for stdout; `--digest-verbose` adds nullable/default/sql_type) |
| `--emit-dbml FILE.dbml` | Also write a minimal DBML export of the schema — tables/columns/indexes/single-column-FK relations/table comments (`-` for stdout; no notes/groups/`TableGroup`) |
| `--emit-mermaid FILE.mmd` | Also write a Mermaid `erDiagram` export of the schema — tables/columns/PK-FK markers/relationships (`-` for stdout; no notes/groups) |
| `--emit-plantuml FILE.puml` | Also write a PlantUML entity-relationship export of the schema — tables/columns/PK-FK markers/relationships (`-` for stdout; no notes/groups) |
| `--no-html` | Skip the HTML diagram and write only the other requested outputs (needs at least one `--emit-*` or `--excel`; cannot be combined with `-o/--output`) |
| `--only 'user*,order*'` | Generate only matching tables |
| `--exclude '*_logs'` | Leave matching tables out |
| `--infer-fk` | Add clearly marked relation guesses from `*_id` columns |
| `--no-open` | Do not open the browser after `demo` |

For every option and config key, see the **[CLI and config reference](https://orapli.github.io/erdscope/manual.html#cli-reference)**.

## Supported inputs

erdscope is tested against MySQL 8.4, PostgreSQL 16, CPython's bundled SQLite, Rails
7.x/8.x projects, Prisma 5/6 schemas, Django 4.2/5.x models, SQLAlchemy declarative
models (classic and 2.0 styles), and Laravel Eloquent models. Details and parser
boundaries are listed in the
[compatibility guide](https://orapli.github.io/erdscope/manual.html#verified-versions).

## Project resources

- **[Live demo](https://orapli.github.io/erdscope/)** — explore a generated shop schema.
- **[Recipes](https://orapli.github.io/erdscope/recipes.html)** — task-oriented guides with copy-paste commands ([日本語](https://orapli.github.io/erdscope/recipes.ja.html)).
- **[User manual](https://orapli.github.io/erdscope/manual.html)** — complete setup, viewer, config, export, and troubleshooting guide.
- **[Examples](examples/)** — ready-to-run inputs plus a drift-checked
  SQLite/config/model showcase with committed HTML, Excel, and schema outputs.
- **[Changelog](CHANGELOG.md)** — features and behavior by release.
- **[Issues](https://github.com/orapli/erdscope/issues)** — bug reports and feature requests.

## Development

Source lives under `src/erdscope/`; the distributable `erd.py` is generated from it.

```bash
python3 -m unittest discover -s tests -v
python3 tools/build_single_file.py --check
```

See the [engineering quickstart](openwiki/quickstart.md) before changing providers,
merge behavior, the viewer, or generated artifacts.

## License

[MIT](LICENSE)
