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:
@@ -1,17 +1,99 @@
|
||||
---
|
||||
title: Constraints
|
||||
description: NOT NULL, UNIQUE, DEFAULT, and CHECK constraints on columns.
|
||||
description: NOT NULL, UNIQUE, DEFAULT, and CHECK constraints that keep data valid.
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
Constraints are rules the database enforces on a column's values, so invalid
|
||||
data can never be stored in the first place. There are four:
|
||||
|
||||
Constraints keep your data valid. Declare them in the column spec at
|
||||
`create table` / `add column` time, or change them on an existing column:
|
||||
| Constraint | Rule |
|
||||
|---|---|
|
||||
| `not null` | The column must always have a value. |
|
||||
| `unique` | No two rows may share a value (empty values aside). |
|
||||
| `default <value>` | The value to use when an `insert` omits the column. |
|
||||
| `check (<expr>)` | Every value must satisfy a condition you write. |
|
||||
|
||||
## Adding constraints
|
||||
|
||||
You can add a constraint to an existing column at any time. In the
|
||||
[example library](/getting-started/example-library/), a book's publication year
|
||||
should be positive, and a sensible fallback is useful when it is unknown:
|
||||
|
||||
```rdbms
|
||||
add constraint default 2000 to books.published
|
||||
add constraint check (published > 1400) to books.published
|
||||
```
|
||||
|
||||
Constraints show up in the column's **Constraints** cell in `show table`:
|
||||
|
||||
```rdbms
|
||||
show table books
|
||||
```
|
||||
|
||||
```
|
||||
books
|
||||
┌───────────┬────────┬──────────────────────────────────────────┐
|
||||
│ Name │ Type │ Constraints │
|
||||
├───────────┼────────┼──────────────────────────────────────────┤
|
||||
│ book_id │ serial │ PK │
|
||||
│ title │ text │ NOT NULL │
|
||||
│ author_id │ int │ │
|
||||
│ published │ int │ DEFAULT 2000, CHECK ("published" > 1400) │
|
||||
│ isbn │ text │ UNIQUE │
|
||||
└───────────┴────────┴──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Here `title` is `NOT NULL` and `isbn` is `UNIQUE` — both were declared when the
|
||||
table was built (see below). `PK` marks the primary key, which is fixed at
|
||||
creation time ([Tables](/reference/tables/)).
|
||||
|
||||
## Declaring constraints when you build the table
|
||||
|
||||
Constraints can also be part of a column's spec from the start. In advanced
|
||||
mode they sit inline in `CREATE TABLE`:
|
||||
|
||||
```sql
|
||||
create table books (
|
||||
book_id serial primary key,
|
||||
title text not null,
|
||||
author_id int,
|
||||
published int default 2000 check (published > 1400),
|
||||
isbn text unique
|
||||
)
|
||||
```
|
||||
|
||||
## Adding a constraint to existing data
|
||||
|
||||
When you add a constraint to a column that already holds rows, the playground
|
||||
checks the current data first. If any row would break the new rule — a `null`
|
||||
where you are adding `not null`, a duplicate where you are adding `unique`, or a
|
||||
value that fails a `check` — the change is **refused** and the offending rows
|
||||
are listed, so you can fix the data and try again. Nothing is changed until the
|
||||
constraint can hold for every row.
|
||||
|
||||
## Removing a constraint
|
||||
|
||||
Name the kind to drop it (there is at most one of each kind per column):
|
||||
|
||||
```rdbms
|
||||
drop constraint check from books.published
|
||||
drop constraint default from books.published
|
||||
```
|
||||
|
||||
## In advanced mode
|
||||
|
||||
A table-level `check` or `unique` can be added and dropped with `ALTER TABLE`;
|
||||
a named constraint can then be dropped by that name:
|
||||
|
||||
```sql
|
||||
alter table books add constraint published_range check (published > 1400)
|
||||
alter table books add unique (title, author_id)
|
||||
alter table books drop constraint published_range
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
```rdbms-syntax
|
||||
add constraint not null to <Table>.<col>
|
||||
@@ -21,10 +103,5 @@ add constraint check (<expr>) to <Table>.<col>
|
||||
drop constraint (not null | unique | default | check) from <Table>.<col>
|
||||
```
|
||||
|
||||
Adding a constraint to a column that already has rows is checked first — if
|
||||
existing data would violate it, the change is refused and the offending rows
|
||||
are shown.
|
||||
|
||||
In advanced mode these are the standard column- and table-level constraints
|
||||
in `CREATE TABLE` / `ALTER TABLE`. The primary key is fixed at creation (see
|
||||
[Tables](/reference/tables/)).
|
||||
See also [Columns](/reference/columns/), [Types](/reference/types/), and
|
||||
[Inserting & editing data](/reference/inserting-and-editing-data/).
|
||||
|
||||
Reference in New Issue
Block a user