quickdbd-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{quickdbd_cli-0.1.2 → quickdbd_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -44,32 +44,96 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
+**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+
 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
+  - 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.
 - **CI-friendly:** builds are deterministic, and errors are `file:line: error: …` with exit code 1.
 
+## From a dbt project
+
+```bash
+dbt docs generate                                   # optional: adds real column types (catalog.json)
+qdbd import dbt target/manifest.json -o erd/        # one .txt per folder (staging, marts, sources, ...)
+qdbd build erd/ -o erd.html
+```
+
+- **Tables:** models, seeds and snapshots of your project, plus sources.
+- **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
+- **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
+- **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **Options:**
+  - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
+  - `--package all` includes installed packages
+  - `--no-sources` drops sources
+  - `-o schema.txt` writes a single file
+
+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 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
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -102,27 +166,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.4
+        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.4
     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:**
@@ -132,10 +214,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.4/README.md

@@ -0,0 +1,222 @@
+# quickdbd-cli (`qdbd`)
+
+Compile [QuickDBD](https://www.quickdatabasediagrams.com)-syntax schema files into **interactive HTML ER diagrams**, with no table limit, from the command line. Built to stay readable at 200+ tables.
+
+```
+Customer
+-
+CustomerId PK int
+Name string
+
+Order
+-
+OrderId PK int
+CustomerId int FK >- Customer.CustomerId
+```
+
+```bash
+pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
+qdbd build schema.txt -o schema.html
+```
+
+**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+
+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:**
+  - 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, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - 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.
+- **CI-friendly:** builds are deterministic, and errors are `file:line: error: …` with exit code 1.
+
+## From a dbt project
+
+```bash
+dbt docs generate                                   # optional: adds real column types (catalog.json)
+qdbd import dbt target/manifest.json -o erd/        # one .txt per folder (staging, marts, sources, ...)
+qdbd build erd/ -o erd.html
+```
+
+- **Tables:** models, seeds and snapshots of your project, plus sources.
+- **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
+- **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
+- **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **Options:**
+  - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
+  - `--package all` includes installed packages
+  - `--no-sources` drops sources
+  - `-o schema.txt` writes a single file
+
+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 serve  PATH... [--port 8765]              # live editor + drag-to-arrange
+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
+```
+
+`PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
+
+### Table positions
+
+The first build auto-arranges the tables. In `qdbd serve`, drag tables where you want them. Positions are saved to a sidecar file you can commit:
+
+- `schema.txt` → `schema.layout.json`
+- a folder → `<folder>/qdbd.layout.json`
+- override either with `--layout FILE`
+
+Once a layout exists, a new table is placed next to the tables it's related to, and nothing else moves. Run `qdbd layout PATH --reset` to re-arrange everything from scratch. A pasted schema's QuickDBD `[layout]` section is used for any table the sidecar doesn't cover.
+
+`qdbd build` never writes the sidecar, so CI builds leave the working tree clean.
+
+### Differences from QuickDBD
+
+`qdbd` accepts a few things QuickDBD rejects, and prints a warning for each one:
+
+- tab characters
+- `decimal(10, 2)` (a space inside a type)
+- an explicit `NOT NULL`
+- indented table names
+- `[layout]` entries for unknown tables
+
+`qdbd check --strict` turns these warnings into errors, so a file that passes is guaranteed to paste into QuickDBD.
+
+`default=` values keep their case, where QuickDBD lowercases them.
+
+## 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.4
+        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.4
+    hooks:
+      - id: qdbd-check
+        files: ^erd/.*\.txt$   # point at your schema files
+```
+
+**GitLab CI:**
+
+```yaml
+erd:
+  image: python:3.12
+  script:
+    - pip install quickdbd-cli
+    - qdbd check erd/
+    - qdbd build erd/ -o public/index.html
+  artifacts:
+    paths: [public/index.html]
+```
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest
+python scripts/gen_schema.py        # regenerate examples/synthetic (200 tables)
+python scripts/gen_font_metrics.py  # regenerate font width table
+```
+
+Design notes: `docs/superpowers/specs/2026-10-17-qdbd-design.md`.
+
+### Releasing
+
+Put PyPI credentials in `.env` (gitignored):
+
+```
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-...
+```
+
+Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `PATH="$PWD/.venv/bin:$PATH" scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
+
+## License
+
+Apache-2.0. Bundled third-party files are listed in [NOTICE](NOTICE).

{quickdbd_cli-0.1.2 → quickdbd_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"

quickdbd_cli-0.1.4/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.1.2 → quickdbd_cli-0.1.4}/src/quickdbd_cli/assets/render.js

@@ -18,6 +18,8 @@
     badgeBg: "#eef1f5",
     badgeText: "#7a8899",
     edge: "#b8bcc2",
+    added: "#2e7d32",
+    changed: "#d48806",
   };
   var FONT = "Inter, 'Helvetica Neue', Helvetica, Arial, sans-serif";
 
@@ -76,7 +78,12 @@
     var st = model.style, w = g.w, h = g.h, out = [];
     out.push('<g class="t" data-id="' + esc(t.id) + '" transform="translate(' + n(p[0]) + "," + n(p[1]) + ')">');
     out.push('<rect class="tb" width="' + w + '" height="' + h + '" rx="2" fill="' + C.body + '" stroke="' + C.border + '"/>');
-    out.push('<path class="th" d="M0 2a2 2 0 0 1 2-2h' + (w - 4) + "a2 2 0 0 1 2 2v" + (st.headerH - 2) + "h-" + w + 'z" fill="' + C.header + '"/>');
+    var state = t.diff && t.diff.state, hcol = state === "added" ? C.added : state === "changed" ? C.changed : C.header;
+    out.push('<path class="th" d="M0 2a2 2 0 0 1 2-2h' + (w - 4) + "a2 2 0 0 1 2 2v" + (st.headerH - 2) + "h-" + w + 'z" fill="' + hcol + '"/>');
+    if (state) {
+      out.push('<text x="' + (w - st.padX) + '" y="' + n(st.headerH / 2 + 4) + '" text-anchor="end" fill="#fff" font-family="' + FONT +
+        '" font-size="10" font-weight="bold">' + (state === "added" ? "NEW" : "CHANGED") + "</text>");
+    }
     out.push('<text x="' + st.padX + '" y="' + n(st.headerH / 2 + st.headerSize * 0.36) + '" fill="' + C.headerText +
       '" font-family="' + FONT + '" font-size="' + st.headerSize + '">' + esc(t.name) + "</text>");
     if (docMarks && t.doc) {
@@ -88,6 +95,8 @@
       var color = c.pk ? C.pk : c.fk ? C.fk : C.text;
       out.push('<g class="r" data-c="' + esc(c.id) + '">');
       out.push('<rect class="rb" y="' + y + '" width="' + w + '" height="' + st.rowH + '" fill="' + C.body + '" fill-opacity="0"/>');
+      var cstate = t.diff && t.diff.cols && t.diff.cols[c.id];
+      if (cstate) out.push('<rect y="' + (y + 3) + '" width="3" height="' + (st.rowH - 6) + '" fill="' + C[cstate] + '"/>');
       out.push('<text x="' + st.padX + '" y="' + base + '" fill="' + color + '" font-family="' + FONT + '" font-size="' +
         st.rowSize + '"' + weight + ">" + esc(c.name) + "</text>");
       if (docMarks && c.doc) out.push(docMark(st.padX, cy + st.rowSize * 0.36 + 2.5, c.nameW, color));
@@ -99,7 +108,7 @@
           '" font-family="' + FONT + '" font-size="' + st.badgeSize + '">' + esc(b.t) + "</text>");
         bx += b.w + st.badgeGap;
       });
-      if (c.pk) out.push(keyIcon(w - st.padX - c.typeW - st.keyW + 1, cy));
+      if (c.pk) out.push(keyIcon(w - st.padX - c.typeW - st.keyW, cy));
       out.push('<text x="' + (w - st.padX) + '" y="' + base + '" text-anchor="end" fill="' + C.type + '" font-family="' + FONT +
         '" font-size="' + st.rowSize + '">' + esc(c.type) + "</text>");
       out.push("</g>");
@@ -225,7 +234,153 @@
     return out;
   }
 
+  /* ------------------------------------------------------------------ draw.io export
+   * mxGraph XML using draw.io's own Entity Relation table shapes, so tables stay editable
+   * (rows can be added, lines re-attached) and crow's-foot arrows are draw.io's ER arrows. */
+  var DRAWIO_ARROW = { one: "ERmandOne", many: "ERmany", zeroOne: "ERzeroToOne", zeroMany: "ERzeroToMany" };
+  function renderDrawio(model, pos, opts) {
+    opts = opts || {};
+    var mode = opts.mode || "full", m = subset(model, opts.only), geo = geometry(m, mode);
+    var KEYW = 44, ROWH = 26, HEADH = 32, cells = [], rowId = {}, n = 2;
+    function id() { return "q" + n++; }
+    function cell(attrs, geom) {
+      var a = Object.keys(attrs).map(function (k) { return k + '="' + esc(attrs[k]) + '"'; }).join(" ");
+      return "<mxCell " + a + ">" + geom + "</mxCell>";
+    }
+    function g(x, y, w, h) {
+      return '<mxGeometry x="' + n2(x) + '" y="' + n2(y) + '" width="' + n2(w) + '" height="' + n2(h) + '" as="geometry"/>';
+    }
+    function n2(v) { return Math.round(v); }
+    var b = bounds(m, pos, mode);
+    m.tables.forEach(function (t) {
+      var p = pos[t.id];
+      if (!p) return;
+      var tg = geo[t.id], w = tg.w + KEYW, tid = id();
+      rowId[t.id] = { _table: tid };
+      cells.push(cell({
+        id: tid, value: t.name, vertex: "1", parent: "1",
+        style: "shape=table;startSize=" + HEADH + ";container=1;collapsible=1;childLayout=tableLayout;fixedRows=1;rowLines=0;" +
+          "fontStyle=1;align=left;spacingLeft=10;resizeLast=1;html=0;whiteSpace=wrap;fillColor=#2b5797;fontColor=#ffffff;" +
+          "strokeColor=#dfe3e8;swimlaneFillColor=#ffffff;fontSize=14;",
+      }, g(p[0] - b[0] + 40, p[1] - b[1] + 40, w, HEADH + Math.max(tg.cols.length, 0) * ROWH)));
+      tg.cols.forEach(function (c, i) {
+        var rid = id(), key = c.pk && c.fk ? "PK,FK" : c.pk ? "PK" : c.fk ? "FK" : "";
+        rowId[t.id][c.id] = rid;
+        cells.push(cell({
+          id: rid, value: "", vertex: "1", parent: tid,
+          style: "shape=tableRow;horizontal=0;startSize=0;swimlaneHead=0;swimlaneBody=0;fillColor=none;collapsible=0;" +
+            "dropTarget=0;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;top=0;left=0;right=0;bottom=0;",
+        }, g(0, HEADH + i * ROWH, w, ROWH)));
+        var base = "shape=partialRectangle;connectable=0;fillColor=none;top=0;left=0;bottom=0;right=0;overflow=hidden;html=0;";
+        var flags = c.badges.map(function (x) { return x.t; }).join(" ");
+        cells.push(cell({ id: id(), value: key, vertex: "1", parent: rid, style: base + "fontStyle=1;fontColor=#2b5797;align=center;fontSize=11;" },
+          g(0, 0, KEYW, ROWH)));
+        cells.push(cell({
+          id: id(), value: c.name + (flags ? "  [" + flags + "]" : "") + (c.type ? " : " + c.type : ""), vertex: "1", parent: rid,
+          style: base + "align=left;spacingLeft=6;fontSize=12;" + (c.pk ? "fontStyle=5;" : c.fk ? "fontStyle=1;" : ""),
+        }, g(KEYW, 0, w - KEYW, ROWH)));
+      });
+    });
+    m.rels.forEach(function (r) {
+      var ra = rowId[r.a.t], rb = rowId[r.b.t];
+      if (!ra || !rb) return;
+      var src = ra[r.a.c] || ra._table, dst = rb[r.b.c] || rb._table;
+      cells.push(cell({
+        id: id(), value: "", edge: "1", parent: "1", source: src, target: dst,
+        style: "edgeStyle=entityRelationEdgeStyle;fontSize=12;html=0;endFill=0;startFill=0;strokeColor=#9aa0a6;" +
+          "startArrow=" + DRAWIO_ARROW[r.a.card] + ";endArrow=" + DRAWIO_ARROW[r.b.card] + ";",
+      }, '<mxGeometry relative="1" as="geometry"/>'));
+    });
+    return '<mxfile host="qdbd" type="device"><diagram id="erd" name="' + esc(opts.title || "ERD") + '">' +
+      '<mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" ' +
+      'page="0" pageScale="1" math="0" shadow="0"><root><mxCell id="0"/><mxCell id="1" parent="0"/>' +
+      cells.join("") + "</root></mxGraphModel></diagram></mxfile>";
+  }
+
+  /* ------------------------------------------------------------------ selectors (dbt-style, over relationships)
+   * Space-separated atoms are unioned; a comma inside an atom intersects (a,b); a leading ! excludes.
+   * Atom: [N]+  method:pattern  +[N]
+   *   method: name (default; also matches aliases), group, file, col
+   *   pattern: glob with * and ?
+   *   +x   x plus the tables it references (parents), any depth; 2+x limits to 2 hops
+   *   x+   x plus the tables referencing it (children); x+1 limits to 1 hop
+   */
+  function globRe(p) {
+    return new RegExp("^" + p.replace(/[.^$|()[\]{}\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$", "i");
+  }
+  function edges(model) {
+    var up = {}, down = {};
+    model.rels.forEach(function (r) {
+      var aMany = r.a.card === "many" || r.a.card === "zeroMany", bMany = r.b.card === "many" || r.b.card === "zeroMany";
+      var aIsChild = aMany || !bMany, child = aIsChild ? r.a.t : r.b.t, parent = aIsChild ? r.b.t : r.a.t;
+      if (child === parent) return;
+      (up[child] = up[child] || []).push(parent);
+      (down[parent] = down[parent] || []).push(child);
+    });
+    return { up: up, down: down };
+  }
+  function walk(start, adj, depth, into) {
+    var frontier = start, d = 0;
+    while (frontier.length && d < depth) {
+      var next = [];
+      frontier.forEach(function (id) {
+        (adj[id] || []).forEach(function (o) { if (!into[o]) { into[o] = true; next.push(o); } });
+      });
+      frontier = next;
+      d++;
+    }
+  }
+  function atomSet(model, atom, g) {
+    var m = /^(\d*\+)?(.*?)(\+\d*)?$/.exec(atom), up = m[1], body = m[2], down = m[3];
+    var method = "name", pat = body, i = body.indexOf(":");
+    if (i > 0) { method = body.slice(0, i).toLowerCase(); pat = body.slice(i + 1); }
+    var re = globRe(pat || "*"), out = {}, base = [];
+    model.tables.forEach(function (t) {
+      var ok;
+      if (method === "name") ok = re.test(t.name) || t.aliases.some(function (a) { return re.test(a); });
+      else if (method === "group") ok = re.test(t.group || "") || (t.group || "").toLowerCase().indexOf(pat.toLowerCase() + "/") === 0;
+      else if (method === "file") ok = re.test(t.file || "") || re.test((t.file || "").split("/").pop());
+      else if (method === "col" || method === "column") ok = t.cols.some(function (c) { return re.test(c.name); });
+      else if (method === "diff" || method === "state") {
+        var ds = t.diff && t.diff.state, want = pat.toLowerCase();
+        ok = !!ds && (want === "modified" || want === "*" || want === ds || (want === "new" && ds === "added"));
+      }
+      else throw new Error("unknown selector method '" + method + "' (use name, group, file, col, diff)");
+      if (ok) { out[t.id] = true; base.push(t.id); }
+    });
+    function hops(op, before) {
+      var n = before ? op.slice(0, -1) : op.slice(1);
+      return n ? parseInt(n, 10) : Infinity;
+    }
+    if (up) walk(base, g.up, hops(up, true), out);
+    if (down) walk(base, g.down, hops(down, false), out);
+    return out;
+  }
+  /* Returns the ids matching `expr`, in model order, or null when expr is blank (= everything). */
+  function select(model, expr) {
+    var tokens = String(expr || "").trim().split(/\s+/).filter(Boolean);
+    if (!tokens.length) return null;
+    var g = edges(model), inc = null, exc = {};
+    tokens.forEach(function (tok) {
+      var neg = tok.charAt(0) === "!";
+      if (neg) tok = tok.slice(1);
+      var parts = tok.split(",").filter(Boolean), set = null;
+      parts.forEach(function (p) {
+        var s = atomSet(model, p, g);
+        if (set === null) set = s;
+        else { var k = {}; Object.keys(set).forEach(function (id) { if (s[id]) k[id] = true; }); set = k; }
+      });
+      set = set || {};
+      if (neg) Object.keys(set).forEach(function (id) { exc[id] = true; });
+      else { inc = inc || {}; Object.keys(set).forEach(function (id) { inc[id] = true; }); }
+    });
+    return model.tables.filter(function (t) { return (inc === null || inc[t.id]) && !exc[t.id]; }).map(function (t) { return t.id; });
+  }
+
   root.qdbd = {
+    renderDrawio: renderDrawio,
+    select: select,
+    subset: subset,
     colors: C,
     geometry: geometry,
     renderTable: renderTable,
@@ -237,5 +392,7 @@
     esc: esc,
   };
   root.qdbdRenderSvg = renderSvg;
+  root.qdbdSelect = select;
+  root.qdbdRenderDrawio = renderDrawio;
   root.qdbdNeighbourhood = neighbourhood;
 })(typeof window !== "undefined" ? window : globalThis);