docs: website docs structure + first content pages

Phase D foundation. Configures the pragmatic four-section sidebar
(Getting started / Guides / Reference / Concepts) and replaces the
template example pages with grounded content built on the shared
"library" example database (authors/books/members/loans):

- Getting started: installation, first project, simple vs advanced,
  the example library.
- Reference: Types (all ten + serial/shortid + advanced aliases),
  Tables (create/drop, compound PK, advanced CREATE TABLE).
- Concepts: projects & storage (readable files, derived database,
  autosave, temp projects).
- Guides: Build the library (draft, to be refined for teaching).

Command syntax grounded in en-US.yaml usage/help, command.rs, and
types.rs (verified against tests). Records the settled doc decisions
in STYLE.md. Build green (10 pages, Pagefind); content clean of
"DSL"/engine-name.
This commit is contained in:
claude@clouddev1
2026-06-06 07:34:57 +00:00
parent cea99e8b70
commit 0fcb7b1105
13 changed files with 653 additions and 97 deletions
@@ -0,0 +1,92 @@
---
title: Tables
description: Create and drop tables in simple mode and in advanced-mode SQL, including compound primary keys.
sidebar:
order: 2
---
A table is the core building block. This page covers creating and removing
tables; changing a table's columns after it exists is covered under Columns
in the Reference.
## Create a table (simple mode)
Every table is created with its primary key. The `with pk` clause lists the
primary-key column(s):
```text
create table authors with pk author_id(serial)
```
Other columns are added afterwards with `add column`:
```text
add column to authors: name (text)
add column to authors: birth_year (int)
```
### Compound primary keys
To make the primary key span more than one column, list them, comma
separated:
```text
create table loans with pk book_id(int), member_id(int)
```
**Syntax**
```text
create table <Name> with pk <col>(<type>)[, ...]
```
## Create a table (advanced mode)
In advanced mode you write a full `CREATE TABLE` with every column and
constraint inline:
```sql
create table authors (
author_id serial primary key,
name text not null,
birth_year int
)
```
The advanced form also accepts table-level constraints and inline foreign
keys — see the Constraints and Relationships references.
**Syntax**
```text
create table [if not exists] <Name> (<col> <type> [constraints], ...)
```
## Drop a table
```text
drop table authors
```
In advanced mode you may add `if exists` so removing a table that is not
there succeeds quietly:
```sql
drop table if exists authors
```
:::caution
Dropping a table removes its rows as well. Use `undo` if you drop one by
mistake.
:::
## Renaming a table
Renaming a table is available in advanced mode:
```sql
alter table authors rename to writers
```
There is no simple-mode rename verb — switch to advanced mode (or use the
one-line `:` escape) to rename a table.