feat: add "Using the playground" section + Reference skeleton
Restructure the docs into five top-level sections, splitting the application you drive from the database language you build with. - New "Using the playground" section: command-line options; the assistive editor (completion, highlighting, [ERR]/[WRN] indicator, hints, in-line editing); the output pane (scrolling); projects (save/load/new/rebuild); undo/redo & history; export & import; clipboard; getting help. Grounded in the in-app help/usage and ADR-0003/0022/0027. - Reference: seed the remaining topic pages (Columns, Relationships, Indexes, Constraints, Inserting & editing data, Querying & inspecting) with real syntax synopses; worked examples to follow. - Surface the assistive editor on the landing page and in Getting started; restore cross-links now that targets exist. Plan + STYLE updated to the five-section structure. 24 pages, build green, links resolve, content clean; planned features carry "planned" callouts.
This commit is contained in:
claude@clouddev1
@@ -69,5 +69,5 @@ export
|
||||
|
||||
The zip contains the readable files (`project.yaml` and `data/`) but **not**
|
||||
the derived database or your private `history.log`. The recipient opens it
|
||||
and the playground rebuilds the database for them. Exporting and
|
||||
importing has its own reference page.
|
||||
and the playground rebuilds the database for them. [Exporting and
|
||||
importing](/using-the-playground/export-and-import/) has its own page.
|
||||
|
||||
@@ -11,7 +11,9 @@ playground starts.
|
||||
|
||||
When you launch `rdbms-playground` with no arguments, it opens a fresh
|
||||
temporary project for you. Type commands into the input field at the bottom
|
||||
and press <kbd>Enter</kbd> to run them.
|
||||
and press <kbd>Enter</kbd> to run them. As you type, the field completes
|
||||
commands with <kbd>Tab</kbd> and flags mistakes before you run — see
|
||||
[The assistive editor](/using-the-playground/the-assistive-editor/).
|
||||
|
||||
## Create a table
|
||||
|
||||
@@ -57,4 +59,5 @@ That is the whole loop: **create → add columns → insert → show**. From her
|
||||
|
||||
- Build the full example database in [Build the library](/guides/build-the-library/).
|
||||
- Learn how [simple and advanced modes](/getting-started/modes/) differ.
|
||||
- Let the editor help you: [completion, highlighting, and live error flags](/using-the-playground/the-assistive-editor/).
|
||||
- Look up any command in the [Reference](/reference/types/).
|
||||
|
||||
@@ -38,6 +38,10 @@ SQL.
|
||||
Ask the playground to explain any query and it renders the database's
|
||||
plan as an annotated tree — so indexes and scans stop being a mystery.
|
||||
</Card>
|
||||
<Card title="Helpful as you type" icon="pencil">
|
||||
The input field completes commands with <kbd>Tab</kbd>, highlights
|
||||
syntax, flags mistakes before you run them, and hints what comes next.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## Start here
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Columns
|
||||
description: Add, remove, rename, and change the type of a table's columns.
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
|
||||
After a table exists, you add and change its columns. In simple mode:
|
||||
|
||||
```rdbms-syntax
|
||||
add column [to] [table] <Table>: <Name> (<Type>)
|
||||
rename column [in] [table] <Table>: <Old> to <New>
|
||||
change column [in] [table] <Table>: <Name> (<Type>) [--force-conversion | --dont-convert]
|
||||
drop column [from] [table] <Table>: <Name> [--cascade]
|
||||
```
|
||||
|
||||
Changing a column to `serial` or `shortid` fills existing rows with generated
|
||||
values. A primary-key column, or one involved in a relationship, is refused
|
||||
until you remove the relationship first.
|
||||
|
||||
In advanced mode the same operations are `ALTER TABLE … ADD/DROP/RENAME
|
||||
COLUMN` and `ALTER TABLE … ALTER COLUMN … TYPE`.
|
||||
|
||||
See also [Types](/reference/types/) and [Constraints](/reference/constraints/).
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Constraints
|
||||
description: NOT NULL, UNIQUE, DEFAULT, and CHECK constraints on columns.
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
|
||||
Constraints keep your data valid. Declare them in the column spec at
|
||||
`create table` / `add column` time, or change them on an existing column:
|
||||
|
||||
```rdbms-syntax
|
||||
add constraint not null to <Table>.<col>
|
||||
add constraint unique to <Table>.<col>
|
||||
add constraint default <value> to <Table>.<col>
|
||||
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/)).
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Indexes
|
||||
description: Create and drop indexes to speed up lookups.
|
||||
sidebar:
|
||||
order: 5
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
|
||||
An index speeds up lookups on one or more columns. In simple mode:
|
||||
|
||||
```rdbms-syntax
|
||||
add index [as <Name>] on <Table> (<col>[, ...])
|
||||
drop index <Name>
|
||||
drop index on <Table> (<col>[, ...])
|
||||
```
|
||||
|
||||
In advanced mode, `CREATE [UNIQUE] INDEX … ON <Table> (…)` and `DROP INDEX`.
|
||||
Unique indexes are available on the advanced surface.
|
||||
|
||||
To see how an index changes the way a query runs, use
|
||||
[Query plans](/reference/querying-and-inspecting/).
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Inserting & editing data
|
||||
description: Add, change, and remove rows.
|
||||
sidebar:
|
||||
order: 7
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
|
||||
```rdbms-syntax
|
||||
insert into <Table> [(<col>[, ...])] [values] (<value>[, ...])
|
||||
update <Table> set <col>=<value>[, ...] (where <col>=<value> | --all-rows)
|
||||
delete from <Table> (where <col>=<value> | --all-rows)
|
||||
```
|
||||
|
||||
`update` and `delete` require a `where` clause; to act on every row you must
|
||||
opt in explicitly with `--all-rows`. Auto-generated columns (`serial`,
|
||||
`shortid`) fill themselves in, so you can leave them out of an `insert`. After
|
||||
a write, the affected rows are shown automatically.
|
||||
|
||||
`where` accepts more than simple equality — `and` / `or` / `not`,
|
||||
comparisons, `like`, `is null`, `in`, and `between`. See
|
||||
[Querying & inspecting](/reference/querying-and-inspecting/).
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Querying & inspecting
|
||||
description: View rows and schema, run SQL queries, and explain how a query runs.
|
||||
sidebar:
|
||||
order: 8
|
||||
---
|
||||
|
||||
:::note[In progress]
|
||||
The syntax below is complete and accurate; worked examples on the library
|
||||
schema are being added.
|
||||
:::
|
||||
|
||||
## Viewing rows and schema (simple mode)
|
||||
|
||||
```rdbms-syntax
|
||||
show data <Table> [where <expr>] [limit <n>]
|
||||
show table <Table>
|
||||
show tables
|
||||
show relationships
|
||||
show indexes
|
||||
show relationship <Name>
|
||||
show index <Name>
|
||||
```
|
||||
|
||||
## Querying (advanced mode)
|
||||
|
||||
Advanced mode runs full SQL `select`, including joins, `group by`, `order
|
||||
by`, set operations, and `with` (CTEs):
|
||||
|
||||
```rdbms-syntax
|
||||
select (* | <expr> [as <alias>][, ...]) from <Table> [where <expr>] [order by <expr> [asc|desc][, ...]] [limit <n>]
|
||||
```
|
||||
|
||||
## Query plans
|
||||
|
||||
Prefix a query with `explain` to see how the database would run it, rendered
|
||||
as an annotated tree — without running it (so it is safe even over `update`
|
||||
or `delete`):
|
||||
|
||||
```rdbms-syntax
|
||||
explain show data <Table> [where <expr>]
|
||||
explain <select | with | insert | update | delete …> (advanced mode)
|
||||
```
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Relationships
|
||||
description: Declare 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 from a child table to a parent's primary
|
||||
key. In simple mode:
|
||||
|
||||
```rdbms-syntax
|
||||
add 1:n relationship [as <Name>]
|
||||
from <Parent>.<col> to <Child>.<col>
|
||||
[on delete <action>] [on update <action>]
|
||||
[--create-fk]
|
||||
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).
|
||||
@@ -6,8 +6,8 @@ sidebar:
|
||||
---
|
||||
|
||||
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.
|
||||
tables; changing a table's columns after it exists is covered in
|
||||
[Columns](/reference/columns/).
|
||||
|
||||
## Create a table (simple mode)
|
||||
|
||||
@@ -62,7 +62,8 @@ create table authors (
|
||||
```
|
||||
|
||||
The advanced form also accepts table-level constraints and inline foreign
|
||||
keys — see the Constraints and Relationships references.
|
||||
keys — see [Constraints](/reference/constraints/) and
|
||||
[Relationships](/reference/relationships/).
|
||||
|
||||
**Syntax**
|
||||
|
||||
|
||||
@@ -59,8 +59,8 @@ filled with freshly generated values in the same step.
|
||||
A foreign key stores a plain looked-up value, not a new generated one. So a
|
||||
column that references a `serial` primary key is itself an `int`, and one
|
||||
that references a `shortid` is a `text`. The playground handles this for you
|
||||
when you declare a relationship; it is worth knowing why the child column's
|
||||
type differs from the parent key's.
|
||||
when you declare a [relationship](/reference/relationships/); it is worth
|
||||
knowing why the child column's type differs from the parent key's.
|
||||
|
||||
## Type names in advanced mode
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Command-line options
|
||||
description: How to start the playground, open a project, and the flags you can pass.
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
Start the playground with no arguments and it opens a fresh, automatically
|
||||
named temporary project so you can begin straight away:
|
||||
|
||||
```sh
|
||||
rdbms-playground
|
||||
```
|
||||
|
||||
To open an existing project, give its path:
|
||||
|
||||
```sh
|
||||
rdbms-playground path/to/project
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Effect |
|
||||
|---|---|
|
||||
| `--resume` | Reopen the most recently used project. Errors if there is none; cannot be combined with a project path. |
|
||||
| `--data-dir <PATH>` | Use `PATH` as the data root instead of the OS-standard location for this run. |
|
||||
| `--mode <simple\|advanced>` | Start in this input mode, overriding the project's stored mode (precedence: `--mode` > stored > simple). |
|
||||
| `--theme <light\|dark>` | 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/)). |
|
||||
| `--log-file <PATH>` | Write diagnostic logging to `PATH`. |
|
||||
| `-h`, `--help` | Print the usage banner and exit. |
|
||||
|
||||
## Examples
|
||||
|
||||
```sh
|
||||
# Reopen wherever you left off, in advanced mode
|
||||
rdbms-playground --resume --mode advanced
|
||||
|
||||
# Keep a course's projects in one folder
|
||||
rdbms-playground --data-dir ~/db-course
|
||||
```
|
||||
|
||||
Where projects are stored, and what a project contains, is covered in
|
||||
[Projects and storage](/concepts/projects-and-storage/).
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: Copy to clipboard
|
||||
description: Copy the output panel to your system clipboard.
|
||||
sidebar:
|
||||
order: 7
|
||||
---
|
||||
|
||||
Copy what's in the output pane to your system clipboard — handy for pasting a
|
||||
result or an error into a question or a note.
|
||||
|
||||
```rdbms
|
||||
copy
|
||||
```
|
||||
Copy the whole output pane. (`copy all` does the same.)
|
||||
|
||||
```rdbms
|
||||
copy last
|
||||
```
|
||||
Copy just the most recent command's output.
|
||||
|
||||
The text is copied exactly as shown in the pane. Copying works over SSH as
|
||||
well as locally.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Export & import
|
||||
description: Package a project to share it, and unpack one you've received.
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
## Export
|
||||
|
||||
```rdbms
|
||||
export
|
||||
```
|
||||
|
||||
Packages the project as a single zip. The zip contains the readable files
|
||||
(`project.yaml` and `data/`) but **not** the working database (the recipient
|
||||
rebuilds it on open) or your private `history.log`. Pass a path to choose
|
||||
where it goes:
|
||||
|
||||
```rdbms
|
||||
export path/to/exercise.zip
|
||||
```
|
||||
|
||||
## Import
|
||||
|
||||
```rdbms
|
||||
import path/to/exercise.zip
|
||||
```
|
||||
|
||||
Unpacks a zip into a new project and switches to it; the database is rebuilt
|
||||
from the readable files. Add `as <name>` to choose the target name:
|
||||
|
||||
```rdbms
|
||||
import path/to/exercise.zip as my-copy
|
||||
```
|
||||
|
||||
## Sharing recipes
|
||||
|
||||
Because a project is plain text plus CSV, sharing it is easy:
|
||||
|
||||
- **Git** — each project includes a `.gitignore` that excludes the working
|
||||
database, so a project commits cleanly and diffs sensibly.
|
||||
- **Email / file transfer** — send the exported zip; the recipient imports it.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Getting help
|
||||
description: Built-in help — a command list, per-command detail, and the type reference.
|
||||
sidebar:
|
||||
order: 8
|
||||
---
|
||||
|
||||
The playground has help built in, so you rarely need to leave it.
|
||||
|
||||
```rdbms
|
||||
help
|
||||
```
|
||||
Lists the supported commands, with the grammar reference and the type list.
|
||||
|
||||
```rdbms
|
||||
help insert
|
||||
```
|
||||
`help <command>` shows detail for one command (every command sharing that
|
||||
entry word). Try `help create`, `help add`, `help show`, and so on.
|
||||
|
||||
```rdbms
|
||||
help types
|
||||
```
|
||||
Shows the type reference on its own.
|
||||
|
||||
Outside the app, run `rdbms-playground --help` for the
|
||||
[command-line options](/using-the-playground/command-line-options/).
|
||||
|
||||
:::note[Planned]
|
||||
A `hint` command for contextual help on the current input or the last error
|
||||
is planned and not yet available — but the input already shows hints as you
|
||||
type (see [The assistive editor](/using-the-playground/the-assistive-editor/)).
|
||||
:::
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Projects — save, load, new, rebuild
|
||||
description: The app-level commands for managing projects.
|
||||
sidebar:
|
||||
order: 4
|
||||
---
|
||||
|
||||
A project is where your work lives. The playground saves it continuously as
|
||||
you go (see [Projects and storage](/concepts/projects-and-storage/) for the
|
||||
model), so these commands are about *switching* and *managing* projects, not
|
||||
a manual "save your changes" step.
|
||||
|
||||
```rdbms
|
||||
save
|
||||
```
|
||||
Give the current temporary project a permanent name. (On a project that is
|
||||
already named, `save` reports that it is already auto-saved — use `save as`.)
|
||||
|
||||
```rdbms
|
||||
save as
|
||||
```
|
||||
Copy the current project to a new name or location and switch to it.
|
||||
|
||||
```rdbms
|
||||
new
|
||||
```
|
||||
Close the current project and start a fresh temporary one.
|
||||
|
||||
```rdbms
|
||||
load
|
||||
```
|
||||
Open the project picker — a list of your projects, newest first, with
|
||||
`[TEMP]` markers; you can also browse to a path.
|
||||
|
||||
```rdbms
|
||||
rebuild
|
||||
```
|
||||
Rebuild the working database from the readable files (`project.yaml` +
|
||||
`data/`), after a confirmation. Useful if the database is ever missing or out
|
||||
of date.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: The assistive editor
|
||||
description: The input field helps as you type — completion, highlighting, a validity indicator, and hints.
|
||||
sidebar:
|
||||
order: 2
|
||||
---
|
||||
|
||||
You type commands into the input field at the bottom of the screen, and it
|
||||
helps you as you go. None of this gets in your way — it is all advisory.
|
||||
|
||||
## Completion
|
||||
|
||||
Press <kbd>Tab</kbd> to complete what you are typing. Completion knows about
|
||||
the commands, the keywords for the current position, your **table, column,
|
||||
index, and relationship names**, and — in advanced mode — common SQL
|
||||
function names. It is the fastest way to discover what is available without
|
||||
leaving the keyboard.
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
As you type, the input is coloured live: keywords, identifiers, column
|
||||
**types**, and SQL function names each get their own colour, so a command's
|
||||
shape is visible before you run it.
|
||||
|
||||
## The validity indicator
|
||||
|
||||
A small marker appears at the right-hand edge of the input line and tells
|
||||
you, *before you submit*, whether the command would run:
|
||||
|
||||
- **`[ERR]`** — the command will fail as written (for example, an unknown
|
||||
table or column, or a value that doesn't match a column's type).
|
||||
- **`[WRN]`** — the command will run, but something looks suspect (for
|
||||
example, comparing a number column with a text pattern).
|
||||
|
||||
It is purely advisory — it never blocks you from submitting.
|
||||
|
||||
## Hints
|
||||
|
||||
A hint line below the input offers contextual guidance — the next token that
|
||||
would fit, the type expected at the current position, and help with the most
|
||||
recent error. When the input is empty it reminds you that <kbd>Tab</kbd>
|
||||
lists options and `help` lists commands.
|
||||
|
||||
## Editing the line
|
||||
|
||||
Move and edit within the line with the usual keys: <kbd>←</kbd>/<kbd>→</kbd>
|
||||
by character, <kbd>Home</kbd>/<kbd>End</kbd> to the ends, and
|
||||
<kbd>Delete</kbd>/<kbd>Backspace</kbd> to remove characters. Your
|
||||
project-scoped command history is available with <kbd>↑</kbd>/<kbd>↓</kbd>.
|
||||
|
||||
:::note[Planned]
|
||||
Multi-line entry and extra readline-style shortcuts (Ctrl-A/E/W/K/U) are
|
||||
planned and not yet available.
|
||||
:::
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
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 <kbd>PageUp</kbd> and <kbd>PageDown</kbd> 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.
|
||||
:::
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Undo, redo & history
|
||||
description: Step back from any change, and replay a recorded session.
|
||||
sidebar:
|
||||
order: 5
|
||||
---
|
||||
|
||||
Every change you make is safe to undo — the playground snapshots the whole
|
||||
project before each one.
|
||||
|
||||
## Undo and redo
|
||||
|
||||
```rdbms
|
||||
undo
|
||||
```
|
||||
|
||||
```rdbms
|
||||
redo
|
||||
```
|
||||
|
||||
Each asks you to confirm, naming the exact command being undone or
|
||||
re-applied. Redo is available until you make a new change. (How snapshots
|
||||
work is explained in [Concepts](/concepts/projects-and-storage/).)
|
||||
|
||||
Starting with `--no-undo` turns this off for the session — no snapshot is
|
||||
taken before each change, and `undo`/`redo` report that undo is off.
|
||||
|
||||
## History and replay
|
||||
|
||||
Every command you run is recorded, in order, in the project's `history.log`.
|
||||
You can re-run a saved sequence of commands from a file:
|
||||
|
||||
```rdbms
|
||||
replay path/to/commands
|
||||
```
|
||||
|
||||
Replay runs each non-blank, non-`#`-comment line, stopping at the first error
|
||||
(relative paths resolve under the project directory). It re-applies the
|
||||
schema- and data-changing commands and skips app-level ones.
|
||||
Reference in New Issue
Block a user