Skip to content

docs(skills): document fork re-attach behavior and add fork-before-risky-changes workflow #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eddietejeda merged 4 commits into from
Jul 16, 2026
Merged

docs(skills): document fork re-attach behavior and add fork-before-risky-changes workflow #229

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5f78374
docs(skills): document fork connection re-attach, active-db side effe…
eddietejeda Jul 16, 2026
0392d57
docs(skills): reference source database by id in fork workflow; docum…
eddietejeda Jul 16, 2026
93db544
docs(skills): database selection is always by id — names and catalogs…
eddietejeda Jul 16, 2026
c63bb38
docs(skills): fork workflow — capture the fork id too; delete by fork id
eddietejeda Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions skills/hotdata/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ hotdata databases tables delete <table> [--database <id_or_name>] [--schema publ

- `list` — all managed databases in the workspace. Active database is marked with `*` under the DEFAULT column; CREATED shows when each database was made.
- `create` — creates a new managed database. `--name` is an optional human-readable display name. `--catalog` sets the SQL alias used in queries (`SELECT … FROM <catalog>.schema.table`); must be `[a-z_][a-z0-9_]*`. `--expires-at` accepts relative durations (`24h`, `7d`, `90m`) or an RFC 3339 timestamp; omitting means no expiry. Repeat `--table` to declare tables up front.
- `fork` — creates a new managed database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass `<id_or_name>` (id, catalog, or name) to fork another. `--name` defaults to `<source>-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked — older parquet-backed databases return an error.
- `set` — saves `<id_or_name>` as the active database. Subsequent `databases tables` and `context` commands use it automatically.
- `fork` — creates a new managed database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass `<id_or_name>` (id, catalog, or name) to fork another. `--name` defaults to `<source>-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; connection catalogs attached to the source are **re-attached** to the fork, but indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked — older parquet-backed databases return an error.
- `set` — saves `<id_or_name>` as the active database. Subsequent `databases tables` and `context` commands use it automatically. Note that a successful `fork` also updates this: the fork becomes the active database.
- `unset` — clears the active database from config.
- `<id_or_name>` — inspect one database (id, catalog, name, expires_at).
- `delete` — removes the managed database; clears the active-database config if it matched.
Expand Down
12 changes: 12 additions & 0 deletions skills/hotdata/references/WORKFLOWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,18 @@ A `hotdata query` runs inside **one** managed database; its scope sees that data

For **Chain** materializations into managed databases, see **`hotdata-analytics`**.

### Workflow: fork before risky changes

Before destructive experimentation (bulk replaces, schema rework, testing a load pipeline), fork the database and experiment on the copy — the source stays untouched and the two diverge freely:

```bash
hotdata databases set sales # source to protect
hotdata databases fork --expires-at 24h # deep copy; becomes the active database
hotdata databases load --catalog sales --table orders --file ./risky.parquet # hits the fork
```

The fork answers to the same catalog alias as its source, so experimental SQL runs unchanged. Attached connections are re-attached to the fork; indexes are not carried over. When done, keep the fork (`databases set` back to the source) or `databases delete` it. Only DuckLake-backed databases can be forked — see `fork` in the main skill for details.

@claude claude Bot Jul 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

databases set resolves by database id, not a catalog alias. The Set subcommand's arg is documented as "Database id" (src/commands/databases.rs:123-126), and set → get_database performs a direct GET /v1/databases/{id} with no catalog/name resolution (src/commands/databases.rs:1467-1493, 410-412). Every other doc example uses hotdata databases set <id> — this new workflow is the only place that passes a catalog alias (set sales).

Two concrete problems:

  1. Opening line — hotdata databases set sales uses the catalog alias sales, but set expects an id, so this likely errors with no database with id 'sales'.

  2. Cleanup line 145 — "keep the fork (databases set back to the source)" is unreachable as written. After the fork, the source and the fork both answer to catalog sales (the fork inherits the source's catalog — src/commands/databases.rs:570-572), so there is no unambiguous alias for the source. Even client-side catalog resolution errors here (resolve_database → "multiple databases have catalog 'sales' — use the database id instead", src/commands/databases.rs:457-466). The agent has no source id to fall back to because the whole workflow deliberately used the alias.

Suggested fix: capture the source id up front (e.g. from databases <id_or_name> / databases list) and use ids for set, or make the workflow reference the source by id explicitly in the cleanup step. This keeps the guidance executable for an agent following it verbatim.

@eddietejeda eddietejeda Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 0392d57 — confirmed against the source that set is id-only (set -> get_database, direct GET with no catalog/name fallback) while fork/delete/inspect resolve via resolve_database. The workflow now captures the source id up front (databases list), uses it for databases set, and calls out explicitly that after the fork the shared catalog alias makes the id the only unambiguous handle on the source. Also corrected the pre-existing set <id_or_name> usage in SKILL.md to set <id> since it's the same defect class.


---

## Model
Expand Down
Loading