Metadata-Version: 2.5
Name: quickdbd-cli
Version: 0.1.13
Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
Project-URL: Homepage, https://github.com/MarkPhamm/quickdbd-cli
Author: Minh (Mark) Pham
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: src/quickdbd_cli/assets/Inter-LICENSE.txt
License-File: src/quickdbd_cli/assets/elk-LICENSE.md
Keywords: database,diagram,erd,quickdbd,schema
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: mini-racer>=0.14
Requires-Dist: resvg-py>=0.5
Provides-Extra: dev
Requires-Dist: fonttools>=4.50; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/logo-wordmark-dark.svg">
    <img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/logo-wordmark-light.svg" alt="qdbd" width="220">
  </picture>
</p>

<p align="center"><b>Interactive ER diagrams from QuickDBD text or a dbt project, readable at 200+ tables</b></p>

<p align="center">
  <a href="https://qdbd.dev/">Docs</a> · <a href="https://qdbd.dev/demo/">Live demos</a> · <a href="#quickstart">Quickstart</a> · <a href="https://pypi.org/project/quickdbd-cli/">PyPI</a>
</p>

<p align="center">
  <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/hero.png" alt="The AdventureWorks sample database as a qdbd diagram, with the SalesOrderHeader table selected" width="760"></a>
</p>
<p align="center">
  <em>AdventureWorks (68 tables) with its column descriptions, built by qdbd. <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader">Try it live →</a></em>
</p>

## What is qdbd?

qdbd is a **command-line tool that turns a database schema written as text into an interactive ER diagram**.

- Diagrams drawn by hand look good, but they live outside the repo and go stale the first time the schema changes.
- Generated diagrams stay current, but most become unreadable past a few dozen tables.

With qdbd the schema is a plain-text file in git, written in [QuickDBD](https://www.quickdatabasediagrams.com)'s syntax or generated from a dbt project. qdbd checks it, lays it out, and builds **one self-contained HTML page** you can search, filter, click through and share.

You get **a diagram that lives next to your code** and **stays usable at hundreds of tables**.

qdbd is not affiliated with QuickDBD. It reads the same text syntax, so schemas copy back and forth between the two.

## Key features

- **QuickDBD-compatible**: the parser mirrors QuickDBD's own, error messages included. A file that passes `qdbd check --strict` pastes into QuickDBD unchanged.
- **dbt import**: `qdbd import dbt` reads `manifest.json`. Primary keys come from `unique` + `not_null` tests or constraints, relationships from `relationships` tests, and `--infer-fks` fills the gaps from column names.
- **Readable at 200+ tables**: automatic layout, search, dbt-style selectors (`+orders+1`, `group:marts`, `tag:fact`), shaded regions per file, collapsed views and a minimap.
- **Review changes in pull requests**: `qdbd diff` reports what a branch changed, the GitHub Action posts it as a PR comment, and `--diff-base` colours the changes in the diagram.
- **One schema, many outputs**: an HTML page, PNG, SVG, editable draw.io, or a shareable link. Installs with pip: no Node, Graphviz or browser needed.

## Demo gallery

Every demo is a single HTML page written by `qdbd build`, from a QuickDBD schema or a dbt manifest.

<!-- gallery:start: generated by `python scripts/build_gallery.py --readme` from gallery/demos.toml -->
| | |
|---|---|
| [![200 tables](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthetic.png)](https://qdbd.dev/demo/synthetic/)<br>**[200 tables](https://qdbd.dev/demo/synthetic/)**<br>Five business domains, 200 tables and every relationship type. Search, filter, click a table to focus it. | [![Schema diff](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/diff.png)](https://qdbd.dev/demo/diff/)<br>**[Schema diff](https://qdbd.dev/demo/diff/)**<br>What a branch changed, coloured in: new tables in green, changed columns in amber, removals listed. |
| [![AdventureWorks](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/adventureworks.png)](https://qdbd.dev/demo/adventureworks/)<br>**[AdventureWorks](https://qdbd.dev/demo/adventureworks/)**<br>Microsoft's bicycle-company OLTP database: 68 tables in five schemas, one region each, with column descriptions. | [![OMOP CDM on Synthea](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthea.png)](https://qdbd.dev/demo/synthea/#t=concept)<br>**[OMOP CDM on Synthea](https://qdbd.dev/demo/synthea/#t=concept)**<br>OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests. |

[View all 14 demos →](https://qdbd.dev/demo/)
<!-- gallery:end -->

## Quickstart

### Fastest start: try it without installing

```sh
curl -O https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/examples/quickdbd-sample.txt
uvx --from quickdbd-cli qdbd serve quickdbd-sample.txt
```

A browser tab opens with the diagram and an editor. Change the text and the diagram reloads; drag tables to arrange them.

### Or step by step

#### 1. Install

```sh
pipx install quickdbd-cli      # or: pip install quickdbd-cli / uv tool install quickdbd-cli
```

Python 3.11+. See [Install](https://qdbd.dev/install/) for other options.

#### 2. Write a schema, or generate one from dbt

Save this as `schema.txt`, or paste in a schema from QuickDBD unchanged:

```text
Customer
-
CustomerId PK int
Email string UNIQUE

Order as o
----
OrderId PK int
CustomerId int FK >- Customer.CustomerId
Total decimal(10,2)
```

A table is a name, a line of dashes, then one column per line. `FK >- Customer.CustomerId` means many orders to one customer. The full syntax is in [Schema Syntax](https://qdbd.dev/syntax/).

For a dbt project, generate the schema instead:

```sh
dbt docs generate                                  # writes target/manifest.json + catalog.json
qdbd import dbt target/ -o erd/ --infer-fks        # one .txt file per dbt folder
```

#### 3. Edit it live

```sh
qdbd serve schema.txt
```

Edit in the browser or in your own editor; the diagram reloads on save. Dragged positions are saved to `schema.layout.json`, which you commit next to the schema.

#### 4. Build, export and share

```sh
qdbd build schema.txt -o schema.html      # one self-contained page
qdbd export schema.txt -o schema.png      # or .svg, .drawio
qdbd share schema.txt                     # a link to the page, via a GitHub gist
```

## Run in CI

The GitHub Action checks the schema and builds the diagram. On pull requests it also posts one schema-diff comment, updated on every push.

```yaml
# .github/workflows/erd.yml
name: ERD
on: [pull_request, push]
jobs:
  erd:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: MarkPhamm/quickdbd-cli@v0.1.11
        with:
          path: erd/                  # schema file(s) or folder(s)
          output: site/index.html
```

dbt projects, GitHub Pages, pre-commit and GitLab CI are covered in [CI and Automation](https://qdbd.dev/github-action/).

## How qdbd works

```text
dbt project ──qdbd import dbt──┐
                               ├──▶ schema/*.txt   (QuickDBD syntax, in git)
hand-written / pasted ─────────┘           │
                                           ├──▶ qdbd check   validation, QuickDBD's error messages  ──▶ CI gate
                                           ├──▶ qdbd serve   live editor, drag to arrange           ──▶ schema.layout.json
                                           ├──▶ qdbd build   interactive HTML                       ──▶ GitHub Pages, artifacts
                                           ├──▶ qdbd diff    what changed vs main                   ──▶ PR comment
                                           └──▶ qdbd export  PNG · SVG · draw.io                    ──▶ docs, slides, wikis
```

- **The parser** follows QuickDBD's own parser step by step, so the same text gives the same tables and the same errors.
- **The layout** comes from [ELK](https://eclipse.dev/elk/). Positions you drag are saved by table name, and new tables are placed next to the tables they relate to, so the diagram doesn't reshuffle.
- **One renderer** draws both the page and the images. It runs in the browser, and inside an embedded JavaScript engine for CLI exports, so a PNG always matches the page.
- **Builds are deterministic**: no timestamps or randomness, so the output only changes when the schema does.

## What it looks like

**1. The schema**, a text file in your repo:

```text
# Every order belongs to one customer.
Order as o
----
OrderId PK int IDENTITY
CustomerId int FK >- Customer.CustomerId
Status string="pending" # current fulfilment state
```

**2. The command:**

```sh
qdbd build schema/ -o erd.html
```

**3. The page:** click a table for its columns, comments and relationships, or type another table's name to get the join path as SQL.

![Table details panel](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/details.png)

## qdbd and QuickDBD

| | qdbd | QuickDBD |
|---|---|---|
| Text syntax | QuickDBD's | QuickDBD's |
| Tables per diagram | no limit | 10 on the free plan |
| Where it runs | your terminal and CI; the result is a static HTML file | the QuickDBD web app |
| Where the schema lives | `.txt` files in your git repo | the web app |
| dbt import, schema diffs, PR comments | ✅ | — |

Use QuickDBD's editor when you want it: a schema that passes `qdbd check --strict` pastes in unchanged.

## FAQ

**Do I need a QuickDBD account?**
No. qdbd only borrows the text syntax.

**Does qdbd connect to my database?**
No. It reads `.txt` schema files or a dbt `manifest.json`. Nothing connects to a warehouse.

**Does my schema leave my machine?**
Only if you run `qdbd share`, which uploads the page to a GitHub gist in your account (secret by default). `qdbd serve` loads its code editor from a CDN; the built pages load nothing.

**How big can a diagram get?**
The demos go up to 200 tables. Search, selectors, regions and collapsed views keep large diagrams workable; `--select` builds a page with just the part you need.

**Can I edit the diagram by hand?**
You edit the text; the diagram is generated from it. Table positions are the one thing you arrange yourself, by dragging in `qdbd serve`.

## Learn more

- [Install](https://qdbd.dev/install/) and [Quick Start](https://qdbd.dev/getting-started/)
- [Schema Syntax](https://qdbd.dev/syntax/), [many files](https://qdbd.dev/files/), [table positions](https://qdbd.dev/layout/), [tags and colours](https://qdbd.dev/tags/)
- [Reading the Diagram](https://qdbd.dev/reading-the-diagram/), [selectors](https://qdbd.dev/selectors/), [exports](https://qdbd.dev/exports/), [sharing a link](https://qdbd.dev/sharing/)
- [dbt Projects](https://qdbd.dev/dbt/), with a [jaffle_shop walkthrough](https://qdbd.dev/example/)
- [Schema Diffs](https://qdbd.dev/diffs/), the [GitHub Action](https://qdbd.dev/github-action/) and the [CLI reference](https://qdbd.dev/cli/)
- [Development](https://qdbd.dev/development/): working on qdbd itself, releasing, and adding a demo

## About the author

qdbd is built and maintained by **Minh (Mark) Pham** ([@MarkPhamm](https://github.com/MarkPhamm)). Issues, ideas and pull requests are welcome on [GitHub](https://github.com/MarkPhamm/quickdbd-cli/issues).

## License

Apache-2.0. Bundled third-party files (ELK, Inter) and the sources of the demo schemas are listed in [NOTICE](https://github.com/MarkPhamm/quickdbd-cli/blob/main/NOTICE).
