claude@clouddev1
10655e46de
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.
5.5 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Relationships | Declare, view, and remove foreign-key relationships between tables. |
|
A relationship is a foreign key linking a child table to a parent's
primary key. In the example library each
book is written by one author, so books (the child) points at authors (the
parent):
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:
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:
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).
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:
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:
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, list the columns on each side, matched in order:
add 1:n relationship from <Parent>.(<a>, <b>) to <Child>.(<x>, <y>)
Removing a relationship
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:
alter table books add foreign key (author_id) references authors (author_id) on delete cascade
Syntax
add 1:n relationship [as <Name>]
from <Parent>.<col> to <Child>.<col>
[on delete <action>] [on update <action>]
[--create-fk]
drop relationship <Name>
See also Indexes and Types (why a foreign-key column's type can differ from the key it references).