From ea7aea64ac0be569b2d4d77e1c2c71d78df5e48f Mon Sep 17 00:00:00 2001 From: Eddie Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Sat, 27 Jun 2026 22:32:08 -0700 Subject: [PATCH] docs(skills): correct databases-run token claims (revert over-restriction) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit E2E testing against the live API revealed my earlier "fix" was wrong. The token minted by `databases run` decodes to: source: database_token, permissions: [read, write], workspaces: [], database: and in practice performs reads, create-database, create-index, delete-database, and uploads with zero 403s. The `database_api_token` + "create databases / run queries / upload data only" allow-list in sdk.rs/databases.rs refers to a *different* credential (a database-scoped API key), which I incorrectly conflated into this section. The original wording was accurate; restore it (with a small env-pickup note). Validated E2E: auth/workspaces/connections/databases/tables/indexes/ embedding-providers/results/queries/jobs/usage/context/search/query (+status exit codes 0/1/2) and the full create→load→query→index→search→run lifecycle all behave as the skills document. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/hotdata/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index 8c4c284..aa74109 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -200,7 +200,7 @@ hotdata databases tables delete [--database ] [--schema publ - `tables list` — lists tables with `TABLE` (`..
`), `SYNCED`, `LAST_SYNC`. Uses active database when `--database` is omitted. - `tables load` — uploads a local parquet file (`--file`), a remote parquet URL (`--url`), or a pre-staged upload (`--upload-id`) and publishes with **replace** mode. - `tables delete` — drops a table from the managed database. -- `run` — mints a database-scoped JWT (via `POST /v1/auth/database`) and execs `` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected. Pass a database id as a group positional (`hotdata databases run ...`) or via `--database `; omit both to auto-create a scratch database using `--name` / `--schema` / `--table` / `--expires-at`. Use this to launch an agent or child process whose API access is scoped to a single database. The minted credential is a **database API token** (`source: database_api_token`, verifiable via `auth status`): it can only **create databases, run queries, and upload data**. Workspace-level operations — e.g. `databases list`/`show`, `connections`, `attach`/`detach`, listing other workspaces — return `403` and require a standard API key. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated. +- `run` — mints a database-scoped JWT (via `POST /v1/auth/database`) and execs `` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected. Pass a database id as a group positional (`hotdata databases run ...`) or via `--database `; omit both to auto-create a scratch database using `--name` / `--schema` / `--table` / `--expires-at`. Use this to launch an agent or child process whose API access is scoped to a single database. The minted JWT carries `database`, `workspaces`, `permissions:["read","write"]`, and `source:"database_token"` — read+write within the token's workspace, with that database as the default query scope. The child `hotdata` (or any tool) picks the token up from `HOTDATA_DATABASE_TOKEN`. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated. - `attach` — attaches a **connection** as a queryable catalog on a managed database, so the connection's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the connection's name). This is how you query connection tables and **join across sources** — see [Querying across connections](#querying-across-connections-attach). - `detach` — removes an attached connection catalog. Accepts the connection name/id **or** the alias you attached it under. Defaults to the active database. - `create --attach [=]` — attach one or more connections at creation time (repeatable), e.g. `--attach github --attach salesdb=sales`.