diff --git a/website/src/content/docs/guides/build-the-library.md b/website/src/content/docs/guides/build-the-library.md index 094dec3..b749854 100644 --- a/website/src/content/docs/guides/build-the-library.md +++ b/website/src/content/docs/guides/build-the-library.md @@ -102,6 +102,15 @@ add 1:n relationship as loans_book from books.book_id to loans.book_id on delete add 1:n relationship as loans_member from members.member_id to loans.member_id on delete cascade ``` +:::note +We build the bridge by hand here because `loans` carries its own columns +(`loaned_on`, `returned_on`) — it records *when* each borrowing happened, not +just *that* it did. For a pure link with no extra columns, the +`create m:n relationship` command builds the junction table and both +relationships in one step — see +[Many-to-many relationships](/reference/relationships/#many-to-many-relationships). +::: + You can confirm all three relationships at once: ```rdbms diff --git a/website/src/content/docs/reference/relationships.mdx b/website/src/content/docs/reference/relationships.mdx index ae528b9..635b37d 100644 --- a/website/src/content/docs/reference/relationships.mdx +++ b/website/src/content/docs/reference/relationships.mdx @@ -123,6 +123,47 @@ list the columns on each side, matched in order: add 1:n relationship from .(, ) to .(, ) ``` +## Many-to-many relationships + +When two tables relate **many-to-many** — a student takes many courses, and a +course has many students — you model it with a **junction table** (also called +a bridge table) that holds a foreign key to each side. `create m:n +relationship` builds that junction for you in one step: + +```rdbms +create m:n relationship from Students to Courses +``` + +Assuming each parent has a primary key `id`, this creates a table named +`Students_Courses` with: + +- one foreign-key column per primary-key column of each parent — + `Students_id` and `Courses_id`, typed to match the keys they reference; +- a **compound primary key** over those columns, so the same pair can never be + linked twice; +- two `1:n` relationships (junction → `Students`, junction → `Courses`), each + with `on delete cascade` and `on update cascade` — delete a student or a + course and its link rows go with it. + +The junction is an ordinary table afterwards: `rename table`, `drop table`, +`insert`, or `add column` all work on it. To choose the name yourself, add +`as `: + +```rdbms +create m:n relationship from Students to Courses as Enrollments +``` + +A few rules keep it predictable: + +- Both parents need a primary key — that is what the junction references. +- The two tables must be different; there is no self-referential shorthand. + To link a table to itself, build the junction by hand. +- The generated foreign keys always cascade. If you need different + [referential actions](#referential-actions), or extra columns on the link + from the start (a loan date, say), build the junction by hand instead — a + `create table` plus two `add 1:n relationship` commands, as the + [library guide](/guides/build-the-library/) does for its `loans` table. + ## Removing a relationship ```rdbms @@ -145,6 +186,7 @@ add 1:n relationship [as ] from . to . [on delete ] [on update ] [--create-fk] +create m:n relationship from to [as ] drop relationship ``` diff --git a/website/src/content/docs/using-the-playground/command-line-options.md b/website/src/content/docs/using-the-playground/command-line-options.md index f43d243..764cd84 100644 --- a/website/src/content/docs/using-the-playground/command-line-options.md +++ b/website/src/content/docs/using-the-playground/command-line-options.md @@ -27,6 +27,7 @@ rdbms-playground path/to/project | `--mode ` | Start in this input mode, overriding the project's stored mode (precedence: `--mode` > stored > simple). | | `--theme ` | Force a theme instead of auto-detecting from the terminal. | | `--no-undo` | Disable the undo machinery for this run — no snapshot is taken before each change (see [Undo, redo & history](/using-the-playground/undo-and-history/)). | +| `--demo` | Turn on demonstration mode — a teaching aid that briefly shows an on-screen badge for keys that otherwise leave no visible mark (Tab, Enter, the arrows, and the like). Useful for screencasts and for demonstrating the playground to a class. Off by default. | | `--log-file ` | Write diagnostic logging to `PATH`. | | `-h`, `--help` | Print the usage banner and exit. | diff --git a/website/src/content/docs/using-the-playground/the-assistive-editor.mdx b/website/src/content/docs/using-the-playground/the-assistive-editor.mdx index e2b110e..6f78abd 100644 --- a/website/src/content/docs/using-the-playground/the-assistive-editor.mdx +++ b/website/src/content/docs/using-the-playground/the-assistive-editor.mdx @@ -52,6 +52,10 @@ by character, Home/End to the ends, and Delete/Backspace to remove characters. Your project-scoped command history is available with ↑/↓. +A long command does not get cut off: the line scrolls sideways to keep the +cursor in view, and on a tall terminal the input field uses two rows so you +can see more of it at once. + :::note[Planned] Multi-line entry and extra readline-style shortcuts (Ctrl-A/E/W/K/U) are planned and not yet available. diff --git a/website/src/content/docs/using-the-playground/the-output-pane.md b/website/src/content/docs/using-the-playground/the-output-pane.md deleted file mode 100644 index 3ce4a74..0000000 --- a/website/src/content/docs/using-the-playground/the-output-pane.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: The output pane -description: Where results appear, and how to scroll back through them. -sidebar: - order: 3 ---- - -Results appear in the output pane: the structure of a table after you change -it, the rows from `show data` and after writes (as aligned, box-drawn -tables), query plans, and command outcomes marked with a ✓ or ✗. - -## Scrolling - -Use PageUp and PageDown to scroll back through earlier -output. New output snaps the view back to the most recent entry, so you never -lose your place when you run something. - -:::note[Planned] -A fuller session journal — a scrollable, richly rendered log of the whole -session that you can save as Markdown — and multiple result tabs are planned -and not yet available. -::: diff --git a/website/src/content/docs/using-the-playground/the-output-pane.mdx b/website/src/content/docs/using-the-playground/the-output-pane.mdx new file mode 100644 index 0000000..ab87077 --- /dev/null +++ b/website/src/content/docs/using-the-playground/the-output-pane.mdx @@ -0,0 +1,41 @@ +--- +title: The output pane +description: Where results appear, the schema sidebar, and how to scroll back through them. +sidebar: + order: 3 +--- + +import Demo from '../../../components/Demo.astro'; + +Results appear in the output pane: the structure of a table after you change +it, the rows from `show data` and after writes (as aligned, box-drawn +tables), query plans, and command outcomes marked with a ✓ or ✗. + +## Scrolling + +Use PageUp and PageDown to scroll back through earlier +output. New output snaps the view back to the most recent entry, so you never +lose your place when you run something. + +## The schema sidebar + +On a wide terminal a sidebar runs down the left-hand side, listing your +**tables** and **relationships** so the shape of your database is always in +view. It shows and hides itself automatically with the terminal width — on a +narrow window it stays out of the way and the output pane gets the full width. + +Press Ctrl-O to bring the sidebar up at any size and step through +it: the first press focuses the **Tables** panel, the next focuses +**Relationships**, and once more returns you to the input field +(Esc leaves it directly). While a panel is focused it widens to +show more detail and is marked with a coloured border; +↑/↓ scroll it a line at a time and +PageUp/PageDown a page at a time. + + + +:::note[Planned] +A fuller session journal — a scrollable, richly rendered log of the whole +session that you can save as Markdown — and multiple result tabs are planned +and not yet available. +:::