@quatronic/qore 0.1.7 → 0.1.8

package/README.md

@@ -55,8 +55,9 @@ Outside a repository, with a projects folder set (see `qore init`), the
 order is: the project you are standing in; else `[project]` /
 `--project <ref>` (`app`, `app/module`, `tenant/app` or `tenant/app/module`,
 matched against your local checkouts); else an interactive pick. `qore dev`
-takes the reference as an argument (`qore dev <app>`); `qore dev`, `qore env
-pull`, `qore run` and `qore status` take `--project`. `qore run --project`
+and `qore db erd` take the reference as an argument (`qore dev <app>`); `qore
+dev`, `qore db erd`, `qore env pull`, `qore run` and `qore status` take
+`--project`. `qore run --project`
 only chooses which module's secrets are used; the command still runs in the
 current directory. `qore env pull --project` writes into the located module,
 and a relative `--target` then resolves against that project directory, not
@@ -284,6 +285,73 @@ qore doctor
   names only the first failing check. A check that throws still lets the
   rest run; it just becomes a `fail` with that error attached.
 
+#### `qore db erd`
+
+Opens this module's data model — tables, columns, keys and the relations
+between them — in your browser, read live from the module's **local**
+Postgres:
+
+```sh
+qore db erd
+qore db erd shop               # from anywhere (see qore init); no ref → a pick
+qore db erd --no-open          # just print the URL
+qore db erd --port 4100
+qore db erd --json > model.json
+```
+
+- **Context + trust**, like `qore run`: the same `--module`/`--app`
+  resolution and the same trust-on-first-use prompt (`--yes` to skip it).
+- **In a workspace root** it shows the whole app; **in a module checkout of
+  a workspace** it asks whether you want the whole app or only that module
+  (without a terminal, or with `--module`, it stays the module).
+- **Where the database comes from:** `DATABASE_URL` in the module's env file
+  (`.env.local` for a frontend module, otherwise `.env`; or the `envFile`
+  named in `.qore.json`); when that file is missing or has no (or a blank)
+  `DATABASE_URL`, it is fetched from the portal for this run only — never
+  written. A module with no `DATABASE_URL` in either has no database to show.
+  The URL is whatever the env file holds, or what the portal's local-env
+  endpoint returns (the local development database).
+- **Read-only.** The session is opened with `default_transaction_read_only`
+  on; the viewer has no write route; only structure is read — never rows.
+- **Local only.** The server listens on `127.0.0.1` on a free port (or
+  `--port`) and refuses requests whose `Host` is not `127.0.0.1:<port>` or
+  `localhost:<port>`. Stop it with Ctrl+C (exit code 130).
+- **Fresh on every load.** Each page load opens a new connection and
+  introspects again, so after a migration — or a database reset or restart —
+  a refresh is enough.
+- **The viewer** is qore's own, bundled with the CLI and fully offline.
+  Tables are listed in a palette on the left: drag one onto the canvas, or
+  click it, to place it, and use `+ N related` to pull in the tables it
+  references or is referenced by. Switch between Keys only and All columns,
+  Tidy up to re-layout, Fit to frame everything. `/` searches, `Delete`
+  removes the selected table, `R` adds its related tables, `Esc` deselects.
+  The URL hash is the canvas: a link only opens again on the same port, so
+  share it with a fixed `--port`, or copy just the `#…` part. The reload
+  button in the top strip re-reads the database without losing the canvas.
+  Light or dark follows the system, with a toggle.
+- **A whole app.** In an app's workspace root (the folder with
+  `qore.workspace.json`, no `--module`) the canvas shows every module's
+  database at once: one lane per database (modules that share a database
+  share a lane), ordered so that what others build on sits left. Foreign keys
+  stay inside a lane; a reference that crosses databases cannot be a foreign
+  key, so it is declared as a comment on the column that holds the id:
+  `COMMENT ON COLUMN app.favourite_spots.spot_id IS '-> api:public.spots.id'`
+  (the `module:` part is optional, free text may follow). The viewer draws it
+  as a dashed cable and names the owning lane in the detail pane. A module
+  without a database has no lane; a database that is down leaves the others
+  on the canvas, with the error in its lane head.
+- `--json` prints `{"ok":true,"data":{"context","source","model"}}`, where
+  `data.model` is the database model the viewer loads and `data.source` is
+  `env-file` or `portal`, and starts nothing;
+  combining it with `--port` or `--no-open` is a usage error (exit 2). In a
+  workspace root it is `{"ok":true,"data":{"context","databases","model"}}`:
+  `context.module` is `null`, `context.modules` lists every module with its
+  lane, `databases` holds one entry per lane with its source, and the model
+  carries `database` on every table plus `databases` and `refs`. It needs every
+  database to be reachable.
+- Not reachable: `QORE_SERVICE_UNHEALTHY` naming the port and the fix
+  (`qore dev` / `pnpm db:up`); a taken (or reserved) `--port`: `QORE_PORT_IN_USE`.
+
 #### `.qore.json`
 
 An optional file at the repository root that configures `qore env pull`