Database layout

The first path argument to eelgrass run / serve / studio / compact is a database directory: the durable engine of record on disk.

What's in the directory

In plain language:

Piece	Role
Pages	Versioned data (and Meta tree) slots under pages/ segment files
WAL	Write-ahead log under wal/. Durability ack before pages are checkpointed.
Meta	Catalog + collection roots + page locators (superblock bootstrap + Meta B-tree)

You do not edit these files by hand. Studio does not open them either. Only eelgrass serve (or run / compact) does.

Typical tree after open:

mydb/
  pages/          # .wps segments (data + Meta pages)
  wal/            # WAL segment files

Open or create

Passing a path that does not exist yet creates the directory structure on open (pages/, wal/, then Meta as the first durable writes land). Reopening the same path recovers: read superblock → Meta roots → replay WAL past the checkpoint.

CLI entry points: CLI. HTTP clients talk to a running serve. They do not touch the directory directly (HTTP API).

Incompatible Meta: recreate

After an incompatible Meta format change, open fails loudly (for example legacy Meta without the current superblock). There is no silent in-place migrate. Recreate the directory: move or delete the old db_dir, then open fresh.

A panicking request on serve that points at missing tree pages may also mean Meta/tenant integrity is broken. Reseed the DB rather than hoping partial state is fine.

Export / import

Not yet. Status lists export/import packaging under what's next. Until that ships, treat the whole db_dir as the backup/move unit. Copy or archive the directory while the process is stopped, or accept that a live copy may be inconsistent.

See Status and the ops hub Operations.