quickdbd-cli 0.1.3__tar.gz → 0.1.5__tar.gz

{quickdbd_cli-0.1.3 → quickdbd_cli-0.1.5}/.gitignore

@@ -220,3 +220,4 @@ __marimo__/
 .streamlit/secrets.toml
 .venv/
 .superpowers/
+site/

{quickdbd_cli-0.1.3 → quickdbd_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.3
+Version: 0.1.5
 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
@@ -21,6 +21,9 @@ 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
 
 # quickdbd-cli (`qdbd`)
@@ -44,19 +47,25 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
+
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
 ## Features
 
 - **Same syntax as QuickDBD:** tables, aliases, quoted names, all 9 relationship operators, `rel` lines, PK/FK/NULL/UNIQUE/INDEX/IDENTITY, `default=`, doc comments, `[settings]` and `[layout]` sections. Error messages are QuickDBD's own.
 - **Interactive page:**
-  - search and jump to a table (`/`)
+  - explorer sidebar: tables grouped by file or dbt folder, with search (`/`, Enter jumps to the best match)
+  - table detail panel (dbt-docs style, for relationships): description, columns with type/keys/docs, and clickable **References** / **Referenced by** lists
   - minimap
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
-  - PNG/SVG export buttons
+  - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
+  - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
 - **Pip-only install:** no Graphviz, Node or browser needed. Layout uses [ELK](https://eclipse.dev/elk/), running in an embedded V8.
@@ -82,15 +91,55 @@ qdbd build erd/ -o erd.html
 
 Re-running the import overwrites the generated files. Table positions survive because they live in the layout file, keyed by table name.
 
+## Selecting tables
+
+Like dbt's `--select`, but it follows relationships instead of lineage. It works in the page's filter box and as `-s/--select` / `--exclude` on `build` and `export`.
+
+| Selector | Tables |
+|---|---|
+| `orders` / `stg_*` | by name or alias (glob, case-insensitive) |
+| `+orders` | `orders` and every table it references (any depth); `1+orders` limits to one hop |
+| `orders+` | `orders` and every table that references it; `orders+2` limits to two hops |
+| `+orders+1` | both directions |
+| `group:marts` | a file or dbt folder (and its subfolders) |
+| `file:core.txt` | a schema file (glob) |
+| `col:customer_id` | tables with a matching column |
+| `diff:modified` / `diff:added` / `diff:changed` | changed since `--diff-base` (like dbt `state:modified`) |
+| `a b` / `a,b` / `!a` | union / intersection / exclude |
+
+```bash
+qdbd build erd/ -s 'group:marts' --exclude '*_tmp' -o marts.html
+qdbd export erd/ -s '+orders+1' -o orders.png
+```
+
+## Schema diffs
+
+```bash
+qdbd diff old.txt new.txt                         # two versions
+qdbd diff --base origin/main erd/                 # git ref vs working tree
+qdbd diff --base origin/main erd/ --format markdown -o diff.md   # for a PR comment
+qdbd build erd/ --diff-base origin/main -o erd.html              # colour what changed
+```
+
+`diff` reports tables added and removed, column changes (added, removed, type and flag changes) and relationships added and removed. `--format json` is available, and `--exit-code` exits 1 when anything changed.
+
+With `--diff-base`, the page:
+- marks new tables green and changed tables amber, with a bar on each changed column;
+- shows a summary banner, and its **Show changes** link filters to the changes plus their neighbours;
+- lists each table's changes in the detail panel.
+
+The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's `state:modified`, e.g. `-s 'diff:modified+1'`.
+
 ## Commands
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
-qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG or SVG image
+qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -123,27 +172,45 @@ Once a layout exists, a new table is placed next to the tables it's related to,
 
 ## CI
 
+**GitHub Action:** checks the schema and builds the diagram. On pull requests it also posts one schema-diff comment, updated on every push, and highlights the changes in the diagram artifact.
+
+```yaml
+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.5
+        with:
+          path: erd/                 # schema file(s) or folder(s)
+          output: site/index.html
+```
+
+| Input | Default | |
+|---|---|---|
+| `path` | (required) | schema files or folders |
+| `output` | `erd/index.html` | HTML diagram path |
+| `check` / `strict` | `true` / `false` | fail on errors / also on QuickDBD-compatibility warnings |
+| `comment` | `true` | post the diff comment on PRs |
+| `select` | | dbt-style selector for the diagram |
+| `qdbd-version` | `latest` | PyPI version |
+
+Outputs are `html`, `changed` and `diff-file`.
+
+**Publishing:** to publish the diagram on GitHub Pages, add `actions/upload-pages-artifact` + `actions/deploy-pages` after it. See [`.github/workflows/erd.yml`](.github/workflows/erd.yml), which publishes this repo's demo.
+
 **pre-commit:**
 
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.0
+    rev: v0.1.5
     hooks:
       - id: qdbd-check
-        files: ^schema/.*\.txt$   # point at your schema files
-```
-
-**GitHub Actions:**
-
-```yaml
-- uses: actions/setup-python@v5
-  with: { python-version: "3.12" }
-- run: pip install quickdbd-cli
-- run: qdbd check schema/
-- run: qdbd build schema/ -o site/schema.html
-- uses: actions/upload-artifact@v4
-  with: { name: schema-diagram, path: site/schema.html }
+        files: ^erd/.*\.txt$   # point at your schema files
 ```
 
 **GitLab CI:**
@@ -153,10 +220,10 @@ erd:
   image: python:3.12
   script:
     - pip install quickdbd-cli
-    - qdbd check schema/
-    - qdbd build schema/ -o public/schema.html
+    - qdbd check erd/
+    - qdbd build erd/ -o public/index.html
   artifacts:
-    paths: [public/schema.html]
+    paths: [public/index.html]
 ```
 
 ## Development

{quickdbd_cli-0.1.3 → quickdbd_cli-0.1.5}/README.md

@@ -19,19 +19,25 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
+
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
 ## Features
 
 - **Same syntax as QuickDBD:** tables, aliases, quoted names, all 9 relationship operators, `rel` lines, PK/FK/NULL/UNIQUE/INDEX/IDENTITY, `default=`, doc comments, `[settings]` and `[layout]` sections. Error messages are QuickDBD's own.
 - **Interactive page:**
-  - search and jump to a table (`/`)
+  - explorer sidebar: tables grouped by file or dbt folder, with search (`/`, Enter jumps to the best match)
+  - table detail panel (dbt-docs style, for relationships): description, columns with type/keys/docs, and clickable **References** / **Referenced by** lists
   - minimap
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
-  - PNG/SVG export buttons
+  - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
+  - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
 - **Pip-only install:** no Graphviz, Node or browser needed. Layout uses [ELK](https://eclipse.dev/elk/), running in an embedded V8.
@@ -57,15 +63,55 @@ qdbd build erd/ -o erd.html
 
 Re-running the import overwrites the generated files. Table positions survive because they live in the layout file, keyed by table name.
 
+## Selecting tables
+
+Like dbt's `--select`, but it follows relationships instead of lineage. It works in the page's filter box and as `-s/--select` / `--exclude` on `build` and `export`.
+
+| Selector | Tables |
+|---|---|
+| `orders` / `stg_*` | by name or alias (glob, case-insensitive) |
+| `+orders` | `orders` and every table it references (any depth); `1+orders` limits to one hop |
+| `orders+` | `orders` and every table that references it; `orders+2` limits to two hops |
+| `+orders+1` | both directions |
+| `group:marts` | a file or dbt folder (and its subfolders) |
+| `file:core.txt` | a schema file (glob) |
+| `col:customer_id` | tables with a matching column |
+| `diff:modified` / `diff:added` / `diff:changed` | changed since `--diff-base` (like dbt `state:modified`) |
+| `a b` / `a,b` / `!a` | union / intersection / exclude |
+
+```bash
+qdbd build erd/ -s 'group:marts' --exclude '*_tmp' -o marts.html
+qdbd export erd/ -s '+orders+1' -o orders.png
+```
+
+## Schema diffs
+
+```bash
+qdbd diff old.txt new.txt                         # two versions
+qdbd diff --base origin/main erd/                 # git ref vs working tree
+qdbd diff --base origin/main erd/ --format markdown -o diff.md   # for a PR comment
+qdbd build erd/ --diff-base origin/main -o erd.html              # colour what changed
+```
+
+`diff` reports tables added and removed, column changes (added, removed, type and flag changes) and relationships added and removed. `--format json` is available, and `--exit-code` exits 1 when anything changed.
+
+With `--diff-base`, the page:
+- marks new tables green and changed tables amber, with a bar on each changed column;
+- shows a summary banner, and its **Show changes** link filters to the changes plus their neighbours;
+- lists each table's changes in the detail panel.
+
+The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's `state:modified`, e.g. `-s 'diff:modified+1'`.
+
 ## Commands
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
-qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG or SVG image
+qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -98,27 +144,45 @@ Once a layout exists, a new table is placed next to the tables it's related to,
 
 ## CI
 
+**GitHub Action:** checks the schema and builds the diagram. On pull requests it also posts one schema-diff comment, updated on every push, and highlights the changes in the diagram artifact.
+
+```yaml
+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.5
+        with:
+          path: erd/                 # schema file(s) or folder(s)
+          output: site/index.html
+```
+
+| Input | Default | |
+|---|---|---|
+| `path` | (required) | schema files or folders |
+| `output` | `erd/index.html` | HTML diagram path |
+| `check` / `strict` | `true` / `false` | fail on errors / also on QuickDBD-compatibility warnings |
+| `comment` | `true` | post the diff comment on PRs |
+| `select` | | dbt-style selector for the diagram |
+| `qdbd-version` | `latest` | PyPI version |
+
+Outputs are `html`, `changed` and `diff-file`.
+
+**Publishing:** to publish the diagram on GitHub Pages, add `actions/upload-pages-artifact` + `actions/deploy-pages` after it. See [`.github/workflows/erd.yml`](.github/workflows/erd.yml), which publishes this repo's demo.
+
 **pre-commit:**
 
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.0
+    rev: v0.1.5
     hooks:
       - id: qdbd-check
-        files: ^schema/.*\.txt$   # point at your schema files
-```
-
-**GitHub Actions:**
-
-```yaml
-- uses: actions/setup-python@v5
-  with: { python-version: "3.12" }
-- run: pip install quickdbd-cli
-- run: qdbd check schema/
-- run: qdbd build schema/ -o site/schema.html
-- uses: actions/upload-artifact@v4
-  with: { name: schema-diagram, path: site/schema.html }
+        files: ^erd/.*\.txt$   # point at your schema files
 ```
 
 **GitLab CI:**
@@ -128,10 +192,10 @@ erd:
   image: python:3.12
   script:
     - pip install quickdbd-cli
-    - qdbd check schema/
-    - qdbd build schema/ -o public/schema.html
+    - qdbd check erd/
+    - qdbd build erd/ -o public/index.html
   artifacts:
-    paths: [public/schema.html]
+    paths: [public/index.html]
 ```
 
 ## Development

{quickdbd_cli-0.1.3 → quickdbd_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"
@@ -25,6 +25,7 @@ dependencies = [
 
 [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"

quickdbd_cli-0.1.5/src/quickdbd_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.5"