quickdbd-cli 0.1.19__tar.gz → 0.2.1__tar.gz

quickdbd_cli-0.2.1/NOTICE

@@ -0,0 +1,38 @@
+quickdbd-cli
+Copyright 2026 Minh (Mark) Pham
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This product bundles third-party components, distributed unmodified:
+
+* elkjs 0.12.0 (src/quickdbd_cli/assets/elk.bundled.js)
+  Eclipse Layout Kernel compiled to JavaScript. Licensed under the Eclipse Public
+  License 2.0 (src/quickdbd_cli/assets/elk-LICENSE.md).
+  Source code: https://github.com/kieler/elkjs and https://github.com/eclipse/elk
+
+* Inter 4.1 font (src/quickdbd_cli/assets/Inter-*.ttf, Inter-*.woff2)
+  Copyright The Inter Project Authors. Licensed under the SIL Open Font License 1.1
+  (src/quickdbd_cli/assets/Inter-LICENSE.txt). Source: https://github.com/rsms/inter
+
+The demo gallery (gallery/, not part of the Python package) includes schemas derived from:
+
+* Northwind, pubs, AdventureWorks and AdventureWorks DW (gallery/northwind, gallery/pubs,
+  gallery/adventureworks, gallery/adventureworks-dw), converted from
+  microsoft/sql-server-samples. Copyright (c) Microsoft Corporation. MIT License.
+* Sakila (gallery/sakila), converted from sakila-schema.sql. Copyright (c) 2006, 2026, Oracle and/or
+  its affiliates. BSD-3-Clause.
+* Chinook (gallery/chinook), converted from lerocha/chinook-database. Copyright (c) 2008-2024
+  Luis Rocha. MIT License.
+* dbt-synthea (gallery/synthea), OHDSI. Apache License 2.0. Trimmed dbt manifest and catalog only.
+* dbt_shopify (gallery/shopify), Fivetran. Apache License 2.0. Trimmed dbt manifest and catalog only.
+
+Each folder keeps the upstream licence in its LICENSE file.
+
+`qdbd serve` loads CodeMirror 5 (MIT) from cdnjs at runtime; it is not bundled.
+
+QuickDBD is a product of its respective owners; this project is not affiliated with it.
+
+The test suite (tests/fixtures/dbml-ref, not part of the Python package) includes the snapshot test inputs of
+@dbml/parse 10.3.1 (github.com/holistics/dbml, commit 34108bb), copied by scripts/import_dbml_corpus.py with
+their expected results reduced to the parts qdbd checks. Copyright Holistics. Apache License 2.0
+(tests/fixtures/dbml-ref/LICENSE).

quickdbd_cli-0.2.1/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: quickdbd-cli
+Version: 0.2.1
+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> · <a href="https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd">VS Code Marketplace</a> · <a href="https://open-vsx.org/extension/MarkPhamm/quickdbd">Open VSX</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 [DBML](https://dbml.dbdiagram.io/docs/) (dbdiagram.io's), 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 or dbdiagram.io. It reads the same text syntaxes, so schemas copy back and forth, and `qdbd convert` turns one syntax into the other.
+
+## 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.
+- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor. Export, share, compare with git and dbt import from the Command Palette, with no terminal: it installs the CLI itself. Get it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) or, for Cursor, Windsurf and VSCodium, [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd) ([docs](https://qdbd.dev/vscode/)).
+- **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 19 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/). DBML from dbdiagram.io works as it is, as `.dbml` or `.txt` ([DBML](https://qdbd.dev/dbml/)).
+
+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.
+
+In VS Code (or Cursor), the [extension](https://qdbd.dev/vscode/) does the same inside the editor, with errors as you type and the diagram following your cursor. Search **QuickDBD** in the Extensions view: it's on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) and [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd).
+
+#### 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` / `.dbml` 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` / `.dbml` 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).

quickdbd_cli-0.2.1/README.md

@@ -0,0 +1,228 @@
+<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> · <a href="https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd">VS Code Marketplace</a> · <a href="https://open-vsx.org/extension/MarkPhamm/quickdbd">Open VSX</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 [DBML](https://dbml.dbdiagram.io/docs/) (dbdiagram.io's), 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 or dbdiagram.io. It reads the same text syntaxes, so schemas copy back and forth, and `qdbd convert` turns one syntax into the other.
+
+## 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.
+- **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor. Export, share, compare with git and dbt import from the Command Palette, with no terminal: it installs the CLI itself. Get it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) or, for Cursor, Windsurf and VSCodium, [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd) ([docs](https://qdbd.dev/vscode/)).
+- **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 19 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/). DBML from dbdiagram.io works as it is, as `.dbml` or `.txt` ([DBML](https://qdbd.dev/dbml/)).
+
+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.
+
+In VS Code (or Cursor), the [extension](https://qdbd.dev/vscode/) does the same inside the editor, with errors as you type and the diagram following your cursor. Search **QuickDBD** in the Extensions view: it's on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkPhamm.quickdbd) and [Open VSX](https://open-vsx.org/extension/MarkPhamm/quickdbd).
+
+#### 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` / `.dbml` 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` / `.dbml` 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).

quickdbd_cli-0.2.1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quickdbd-cli"
+version = "0.2.1"
+description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE", "src/quickdbd_cli/assets/*LICENSE*"]
+requires-python = ">=3.11"
+authors = [{ name = "Minh (Mark) Pham" }]
+keywords = ["erd", "database", "diagram", "quickdbd", "schema"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Topic :: Database",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+  "mini-racer>=0.14",
+  "resvg-py>=0.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "fonttools>=4.50"]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5,<10"]
+
+[project.scripts]
+qdbd = "quickdbd_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MarkPhamm/quickdbd-cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quickdbd_cli"]
+
+[tool.hatch.build.targets.sdist]
+# Anchored: an unanchored "src" also matches vscode/node_modules/**/src.
+include = ["/src", "/tests", "/examples", "/scripts", "/README.md", "/LICENSE", "/NOTICE"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]