quickdbd-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/.gitignore

@@ -222,3 +222,4 @@ __marimo__/
 .superpowers/
 site/
 jaffle-erd/
+graphify-out/

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.3.2
+Version: 0.3.3
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://qdbd.dev/
 Project-URL: Documentation, https://qdbd.dev/guide/
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
   </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"><b>Interactive ER diagrams from QuickDBD text, DBML or a dbt project, readable at 200+ tables</b></p>
 
 <p align="center">
   <a href="https://pypi.org/project/quickdbd-cli/"><img src="https://img.shields.io/pypi/v/quickdbd-cli?label=PyPI" alt="PyPI version"></a>
@@ -89,7 +89,7 @@ qdbd is not affiliated with QuickDBD or dbdiagram.io. It reads the same text syn
 - **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.
+- **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. To propose a column change, tag the column `# @tag: added` or `# @tag: removed` and it's drawn green or red ([column tags](https://qdbd.dev/tags/#columns)).
 - **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor, or in your browser on localhost. Export, share, compare with git, convert to and from DBML, and dbt import from the sidebar or 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/)).
 - **AI agents**: `qdbd mcp` gives Claude, Copilot and Cursor your schema as tools: tables and columns, join paths as SQL (composite keys included), checks for their edits and diffs against `main` ([docs](https://qdbd.dev/mcp/)).
 - **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.
@@ -186,7 +186,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.11
+      - uses: MarkPhamm/quickdbd-cli@v0.3.3
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -198,7 +198,7 @@ dbt projects, GitHub Pages, pre-commit and GitLab CI are covered in [CI and Auto
 
 ```text
 dbt project ──qdbd import dbt──┐
-                               ├──▶ schema/*.txt   (QuickDBD syntax, in git)
+                               ├──▶ schema/*.txt, *.dbml   (QuickDBD syntax or DBML, in git)
 hand-written / pasted ─────────┘           │
                                            ├──▶ qdbd check   validation, QuickDBD's error messages  ──▶ CI gate
                                            ├──▶ qdbd serve   live editor, drag to arrange           ──▶ schema.layout.json
@@ -240,7 +240,7 @@ qdbd build schema/ -o erd.html
 
 | | qdbd | QuickDBD |
 |---|---|---|
-| Text syntax | QuickDBD's | QuickDBD's |
+| Text syntax | QuickDBD's or DBML | 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 |

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/README.md

@@ -5,7 +5,7 @@
   </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"><b>Interactive ER diagrams from QuickDBD text, DBML or a dbt project, readable at 200+ tables</b></p>
 
 <p align="center">
   <a href="https://pypi.org/project/quickdbd-cli/"><img src="https://img.shields.io/pypi/v/quickdbd-cli?label=PyPI" alt="PyPI version"></a>
@@ -51,7 +51,7 @@ qdbd is not affiliated with QuickDBD or dbdiagram.io. It reads the same text syn
 - **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.
+- **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. To propose a column change, tag the column `# @tag: added` or `# @tag: removed` and it's drawn green or red ([column tags](https://qdbd.dev/tags/#columns)).
 - **VS Code extension**: highlighting, errors as you type, outline, F12 across files, and the diagram beside the editor, following your cursor, or in your browser on localhost. Export, share, compare with git, convert to and from DBML, and dbt import from the sidebar or 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/)).
 - **AI agents**: `qdbd mcp` gives Claude, Copilot and Cursor your schema as tools: tables and columns, join paths as SQL (composite keys included), checks for their edits and diffs against `main` ([docs](https://qdbd.dev/mcp/)).
 - **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.
@@ -148,7 +148,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.11
+      - uses: MarkPhamm/quickdbd-cli@v0.3.3
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -160,7 +160,7 @@ dbt projects, GitHub Pages, pre-commit and GitLab CI are covered in [CI and Auto
 
 ```text
 dbt project ──qdbd import dbt──┐
-                               ├──▶ schema/*.txt   (QuickDBD syntax, in git)
+                               ├──▶ schema/*.txt, *.dbml   (QuickDBD syntax or DBML, in git)
 hand-written / pasted ─────────┘           │
                                            ├──▶ qdbd check   validation, QuickDBD's error messages  ──▶ CI gate
                                            ├──▶ qdbd serve   live editor, drag to arrange           ──▶ schema.layout.json
@@ -202,7 +202,7 @@ qdbd build schema/ -o erd.html
 
 | | qdbd | QuickDBD |
 |---|---|---|
-| Text syntax | QuickDBD's | QuickDBD's |
+| Text syntax | QuickDBD's or DBML | 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 |

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.3.2"
+version = "0.3.3"
 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.3.3/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/agent.py

@@ -638,12 +638,6 @@ def diff_schema(ws: Workspace, args: dict) -> Result:
     return Result("\n".join(clip(_header(c) + text.splitlines(), "lines")))
 
 
-def _svg_size(svg: str) -> tuple[float, float]:
-    w = re.search(r'\bwidth="([\d.]+)', svg)
-    h = re.search(r'\bheight="([\d.]+)', svg)
-    return (float(w.group(1)) if w else 1000.0, float(h.group(1)) if h else 1000.0)
-
-
 def render_diagram(ws: Workspace, args: dict) -> Result:
     c = ws.compile(ws.target(args.get("project")))
     tables = selected(c, args.get("select"))
@@ -679,7 +673,7 @@ def render_diagram(ws: Workspace, args: dict) -> Result:
             raise ToolError("the layout took too long; narrow with `select` or `focus`") from None
         pos = {k: [v[0], v[1]] for k, v in laid.items()}
         svg = export.render_svg(c.model, pos, only=ids, mode=mode, embed_font=False)
-        scale = min(2.0, IMAGE_SIDE / max(_svg_size(svg)))
+        scale = min(2.0, IMAGE_SIDE / max(export.svg_size(svg)))
         if scale >= MIN_SCALE[mode]:
             png = export.svg_to_png(svg, scale)
             names = ", ".join(t["name"] for t in tables[:40]) + (", …" if n > 40 else "")

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/assets/style.css

@@ -82,6 +82,7 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 #stage { position: relative; flex: 1; overflow: hidden; }
 #canvas { width: 100%; height: 100%; display: block; cursor: grab; touch-action: none; user-select: none; }
 #canvas.panning { cursor: grabbing; }
+#canvas.lod .t text { display: none; } /* big diagram, zoomed out: see LOD_TABLES in viewer.js */
 
 /* diagram colours: CSS beats the SVG presentation attributes, so the page can theme them */
 .tb { fill: var(--t-body); stroke: var(--t-border); }

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/assets/viewer.js

@@ -40,9 +40,13 @@
     applyFocus();
   }
 
+  // Zoomed out on a big diagram, table text is unreadable but repainting it made every zoom step take ~150 ms
+  // at 1000 tables, so it is hidden there. Smaller diagrams always show it.
+  var LOD_TABLES = 300, LOD_ZOOM = 0.3;
   function applyView() {
     var v = S.view;
     vp.setAttribute("transform", "translate(" + v.x + "," + v.y + ") scale(" + v.k + ")");
+    svg.classList.toggle("lod", v.k < LOD_ZOOM && S.vm.tables.length > LOD_TABLES);
     zoomval.textContent = Math.round(v.k * 100) + "%";
     drawViewportRect();
     scheduleHash();
@@ -806,7 +810,7 @@
     try {
       if (p.has("m")) setMode(p.get("m"));
       if (p.has("r")) setRegions(p.get("r") === "1");
-      applyFilter(p.get("f") || "", true);
+      if ((p.get("f") || "") !== S.filter) applyFilter(p.get("f") || "", true); // else already rendered
       var name = p.get("t"), id = null;
       if (name) S.model.tables.forEach(function (t) { if (t.name === name) id = t.id; });
       select(id && S.shown[id] ? id : null);

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/cli.py

@@ -216,7 +216,11 @@ def cmd_export(args) -> int:
     if fmt == "svg":
         out.write_text(svg, encoding="utf-8")
     else:
-        out.write_bytes(export.svg_to_png(svg, args.scale))
+        scale = export.png_scale(svg, args.scale)
+        if scale < args.scale:
+            note = f"--scale lowered to {scale:.2f} to keep the PNG within {export.MAX_PNG_SIDE} px"
+            print(f"note: {note}", file=sys.stderr)
+        out.write_bytes(export.svg_to_png(svg, scale))
     print(f"Wrote {out} ({len(only) if only else len(model['tables'])} tables)")
     return 0
 
@@ -532,7 +536,7 @@ def build_parser() -> argparse.ArgumentParser:
             action="append",
             metavar="SELECTOR",
             help="dbt-style: name glob, +name (and what it references), name+ (and what references it), "
-            "N+name+N (hops), group:/file:/col: methods, a,b intersects (repeatable)",
+            "N+name+N (hops), group:/file:/col:/tag: methods, a,b intersects (repeatable)",
         )
         sp.add_argument("--exclude", action="append", metavar="SELECTOR", help="drop tables matching (repeatable)")
 

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/export.py

@@ -3,12 +3,16 @@
 from __future__ import annotations
 
 import base64
+import re
 from functools import cache
 from importlib import resources
 
 from . import layout
 from .jsrt import runtime
 
+# A 200-table diagram at scale 2 is 17506x15274 px: 15 s to encode, and too big for many image viewers.
+MAX_PNG_SIDE = 16384
+
 
 def _asset_bytes(name: str) -> bytes:
     return resources.files("quickdbd_cli").joinpath(f"assets/{name}").read_bytes()
@@ -85,6 +89,17 @@ def focus_positions(model: dict, positions: dict, ids: list[str]) -> dict:
     return {k: [v[0], v[1]] for k, v in pos.items()}
 
 
+def svg_size(svg: str) -> tuple[float, float]:
+    w = re.search(r'\bwidth="([\d.]+)', svg)
+    h = re.search(r'\bheight="([\d.]+)', svg)
+    return (float(w.group(1)) if w else 1000.0, float(h.group(1)) if h else 1000.0)
+
+
+def png_scale(svg: str, scale: float) -> float:
+    """``scale``, lowered so the PNG's longest side stays within MAX_PNG_SIDE pixels."""
+    return min(scale, MAX_PNG_SIDE / max(svg_size(svg)))
+
+
 def svg_to_png(svg: str, scale: float = 2.0) -> bytes:
     import resvg_py
 

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/src/quickdbd_cli/layout.py

@@ -32,6 +32,10 @@ OVERLAP_OPTIONS = {
     "elk.spacing.nodeNode": "40",
     "elk.randomSeed": "1",
 }
+# Overlap removal takes most of a big layout (25 of 37 s at 1000 tables). Above BIG_LAYOUT tables its
+# iterations are capped, and the few tables it leaves overlapping are moved by `_separate`.
+BIG_LAYOUT = 300
+BIG_OVERLAP_OPTIONS = {**OVERLAP_OPTIONS, "org.eclipse.elk.overlapRemoval.maxIterations": "8"}
 
 MARGIN = 30
 Positions = dict[str, tuple[int, int]]
@@ -64,9 +68,10 @@ def elk_layout(tables: list[dict], rels: list[dict], timeout_sec: float | None =
     }
     first = rt.call_async("qdbdElkLayout", graph, timeout_sec=timeout_sec)
     first = _landscape(tables, {k: (v[0], v[1]) for k, v in first.items()})
+    big = len(tables) > BIG_LAYOUT
     graph = {
         "id": "root",
-        "layoutOptions": OVERLAP_OPTIONS,
+        "layoutOptions": BIG_OVERLAP_OPTIONS if big else OVERLAP_OPTIONS,
         "children": [
             {"id": t["id"], "width": t["w"], "height": t["h"], "x": first[t["id"]][0], "y": first[t["id"]][1]}
             for t in tables
@@ -74,6 +79,8 @@ def elk_layout(tables: list[dict], rels: list[dict], timeout_sec: float | None =
         "edges": [],
     }
     raw = rt.call_async("qdbdElkLayout", graph, timeout_sec=timeout_sec)
+    if big:
+        raw = _separate(tables, raw)
     min_x = min(v[0] for v in raw.values())
     min_y = min(v[1] for v in raw.values())
     return {k: (int(v[0] - min_x), int(v[1] - min_y)) for k, v in raw.items()}
@@ -155,6 +162,18 @@ def _free_spot(cx: float, cy: float, w: float, h: float, rects, step: int = 30)
     return int(round(x0)), int(round(y0))
 
 
+def _separate(tables: list[dict], pos: dict) -> dict:
+    """Move each table that overlaps an earlier one to the nearest free spot."""
+    out, rects = {}, []
+    for t in tables:
+        x, y = pos[t["id"]]
+        if _overlaps(x, y, t["w"], t["h"], rects):
+            x, y = _free_spot(x + t["w"] / 2, y + t["h"] / 2, t["w"], t["h"], rects)
+        out[t["id"]] = (x, y)
+        rects.append((x, y, t["w"], t["h"]))
+    return out
+
+
 def place_missing(tables: list[dict], rels: list[dict], positions: Positions) -> Positions:
     """Positions for every table. Existing positions never move.
 

{quickdbd_cli-0.3.2 → quickdbd_cli-0.3.3}/tests/test_pipeline.py

@@ -57,6 +57,16 @@ def test_elk_layout_deterministic_and_non_overlapping():
     assert not any(_overlap(r1, r2) for i, r1 in enumerate(rects) for r2 in rects[i + 1 :])
 
 
+def test_big_layout_caps_overlap_removal_and_still_separates(monkeypatch):
+    monkeypatch.setattr(layout, "BIG_LAYOUT", 100)  # take the >BIG_LAYOUT path on the 200-table schema
+    m = model_json(Project.open([SYNTH]).compile())
+    a = layout.elk_layout(m["tables"], m["rels"])
+    assert a == layout.elk_layout(m["tables"], m["rels"]) and len(a) == 200
+    by = {t["id"]: t for t in m["tables"]}
+    rects = [(x, y, by[k]["w"], by[k]["h"]) for k, (x, y) in a.items()]
+    assert not any(_overlap(r1, r2) for i, r1 in enumerate(rects) for r2 in rects[i + 1 :])
+
+
 def test_place_missing_keeps_existing_and_avoids_overlap():
     m = model_json(compile_text(SMALL + "\nLine\n-\nId PK int\nOrderId int FK >- Order.OrderId\n"))
     fixed = {"Customer": (0, 0), "Order": (400, 0)}
@@ -114,6 +124,16 @@ def test_png_export(tmp_path):
     assert out.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
 
 
+def test_png_export_caps_size(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr(export, "MAX_PNG_SIDE", 300)
+    out = tmp_path / "c.png"
+    assert main(["export", str(SAMPLE), "-o", str(out)]) == 0
+    head = out.read_bytes()
+    w, h = int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
+    assert max(w, h) <= 300
+    assert "--scale lowered" in capsys.readouterr().err
+
+
 # ------------------------------------------------------------------ CLI
 
 

quickdbd_cli-0.3.2/src/quickdbd_cli/__init__.py

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