docs(website): fill the six Reference stubs with worked examples + output
Expand columns, relationships, indexes, constraints, inserting-and-editing- data, and querying-and-inspecting from syntax-only stubs into full pages, each with worked examples on the library schema and real captured app output (structure boxes, relationship diagrams, data tables, show-lists, query plans, cascade summaries). All output captured verbatim from the app — never hand-drawn. Both simple- and advanced-mode forms shown where both apply; advanced syntax verified against tests/source. STYLE.md: record the output-block convention (plain unlabelled fence, captured from a throwaway harness, not hand-drawn). Verified: pnpm build clean (24 pages); no forbidden terms; internal links and heading anchors resolve.
This commit is contained in:
claude@clouddev1
@@ -1,17 +1,140 @@
|
||||
---
|
||||
title: Relationships
|
||||
description: Declare and remove foreign-key relationships between tables.
|
||||
description: Declare, view, and remove foreign-key relationships between tables.
|
||||
sidebar:
|
||||
order: 4
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
A relationship is a foreign key linking a **child** table to a **parent**'s
|
||||
primary key. In the [example library](/getting-started/example-library/) each
|
||||
book is written by one author, so `books` (the child) points at `authors` (the
|
||||
parent):
|
||||
|
||||
A relationship is a foreign key from a child table to a parent's primary
|
||||
key. In simple mode:
|
||||
```rdbms
|
||||
add 1:n relationship as books_author from authors.author_id to books.author_id on delete cascade
|
||||
```
|
||||
|
||||
You name the relationship with `as <name>` (here `books_author`), then give the
|
||||
parent endpoint `from authors.author_id` and the child endpoint
|
||||
`to books.author_id`. The `1:n` reads "one author, many books".
|
||||
|
||||
## Viewing a relationship
|
||||
|
||||
`show relationship` draws the two tables and the link between them:
|
||||
|
||||
```rdbms
|
||||
show relationship books_author
|
||||
```
|
||||
|
||||
```
|
||||
┌───────────────────────┐ ┌───────────────────────────┐
|
||||
│ books │ │ authors │
|
||||
├──────────────┬────────┤ ├──────────────────┬────────┤
|
||||
│ book_id (PK) │ serial │ ┌──────1▶│ author_id (PK) ● │ serial │
|
||||
│ title │ text │ │ │ name │ text │
|
||||
│ author_id ● │ int │n────────┘ │ birth_year │ int │
|
||||
│ published │ int │ └──────────────────┴────────┘
|
||||
│ isbn │ text │
|
||||
└──────────────┴────────┘
|
||||
on delete cascade · on update no action
|
||||
```
|
||||
|
||||
Read the diagram like this:
|
||||
|
||||
- The **child** (the table holding the foreign key) is on the **left**; the
|
||||
**parent** is on the **right**.
|
||||
- A filled dot **●** marks each column that takes part in the link.
|
||||
- The connector runs **`n` … `1`** — many child rows to one parent row — and
|
||||
the **▶** arrowhead points at the parent key.
|
||||
- The line beneath records the referential actions (below).
|
||||
|
||||
A table's own `show table` includes a compact **Relationships** section that
|
||||
summarises every link it takes part in:
|
||||
|
||||
```rdbms
|
||||
show table books
|
||||
```
|
||||
|
||||
```
|
||||
books
|
||||
┌───────────┬────────┬─────────────┐
|
||||
│ Name │ Type │ Constraints │
|
||||
├───────────┼────────┼─────────────┤
|
||||
│ book_id │ serial │ PK │
|
||||
│ title │ text │ NOT NULL │
|
||||
│ author_id │ int │ │
|
||||
│ published │ int │ │
|
||||
│ isbn │ text │ UNIQUE │
|
||||
└───────────┴────────┴─────────────┘
|
||||
Relationships
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ books │ │ authors │
|
||||
├─────────────┤ ├─────────────┤
|
||||
│ author_id ● │n───────────────1▶│ author_id ● │
|
||||
└─────────────┘ └─────────────┘
|
||||
on delete cascade · on update no action
|
||||
```
|
||||
|
||||
For a one-line summary of every relationship in the project, use `show
|
||||
relationships` (see [Querying & inspecting](/reference/querying-and-inspecting/)).
|
||||
|
||||
## Referential actions
|
||||
|
||||
`on delete` and `on update` decide what happens to the child rows when a parent
|
||||
row is deleted or its key changes. The action is one of:
|
||||
|
||||
| Action | Effect on the children |
|
||||
|---|---|
|
||||
| `cascade` | The children are deleted / updated to match. |
|
||||
| `set null` | The children's foreign-key column is set to empty. |
|
||||
| `restrict` | The change is refused while children still reference the row. |
|
||||
|
||||
With `on delete cascade`, deleting an author removes that author's books too,
|
||||
and the result reports each affected relationship:
|
||||
|
||||
```rdbms
|
||||
delete from authors where author_id = 3
|
||||
```
|
||||
|
||||
```
|
||||
1 row(s) deleted
|
||||
related: 1 row(s) deleted in `books` for relationship `books_author` (on delete cascade)
|
||||
```
|
||||
|
||||
## Creating the child column at the same time
|
||||
|
||||
If the child column does not exist yet, add `--create-fk` and the playground
|
||||
creates it for you with the right type:
|
||||
|
||||
```rdbms
|
||||
add 1:n relationship as loans_member from members.member_id to loans.member_id --create-fk
|
||||
```
|
||||
|
||||
## Compound keys
|
||||
|
||||
To reference a parent's [compound primary key](/reference/tables/#compound-primary-keys),
|
||||
list the columns on each side, matched in order:
|
||||
|
||||
```rdbms-syntax
|
||||
add 1:n relationship from <Parent>.(<a>, <b>) to <Child>.(<x>, <y>)
|
||||
```
|
||||
|
||||
## Removing a relationship
|
||||
|
||||
```rdbms
|
||||
drop relationship books_author
|
||||
```
|
||||
|
||||
## In advanced mode
|
||||
|
||||
Relationships are ordinary foreign keys, declared with `FOREIGN KEY …
|
||||
REFERENCES` either inline at `CREATE TABLE` or added later with `ALTER TABLE`:
|
||||
|
||||
```sql
|
||||
alter table books add foreign key (author_id) references authors (author_id) on delete cascade
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
```rdbms-syntax
|
||||
add 1:n relationship [as <Name>]
|
||||
@@ -21,18 +144,5 @@ add 1:n relationship [as <Name>]
|
||||
drop relationship <Name>
|
||||
```
|
||||
|
||||
`<action>` is `cascade`, `set null`, or `restrict`. `--create-fk` adds the
|
||||
child column if it doesn't exist yet.
|
||||
|
||||
**Compound keys.** To reference a parent's compound primary key, list the
|
||||
columns on each side, matched in order:
|
||||
|
||||
```rdbms-syntax
|
||||
add 1:n relationship from <Parent>.(<a>, <b>) to <Child>.(<x>, <y>)
|
||||
```
|
||||
|
||||
In advanced mode, relationships are declared with `FOREIGN KEY … REFERENCES`
|
||||
in `CREATE TABLE` or `ALTER TABLE`.
|
||||
|
||||
See also [Indexes](/reference/indexes/) and [Types](/reference/types/) (why a
|
||||
foreign-key column's type can differ from the key it references).
|
||||
|
||||
Reference in New Issue
Block a user