From f9da88644b3faefab4dd5fce37e46c92ed710ad7 Mon Sep 17 00:00:00 2001 From: Ignacio Van Droogenbroeck Date: Sun, 31 May 2026 20:53:19 -0300 Subject: [PATCH] docs(cli): add db + measurement sections (arcctl PR3 surface) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion docs for arcctl PR3 (https://github.com/Basekick-Labs/arcctl/pull/2) which adds `arcctl db {list,show,create,drop}` and `arcctl measurement list`. New pages - docs/cli/db.md — list / show / create / drop with the layered safety story for drop (client- side y/N prompt + server delete.enabled + admin token + reserved-name blocklist + ?confirm=true) - docs/cli/measurement.md — list measurements within a database, with the precedence rule for --database vs connection default_database Index update - docs/cli/index.md — status table reflects PR3 shipped; "Next" links to both new pages Build verified locally with `npm run build` — no new broken links or anchors introduced. Co-Authored-By: Claude Opus 4.7 --- docs/cli/db.md | 136 ++++++++++++++++++++++++++++++++++++++++ docs/cli/index.md | 5 +- docs/cli/measurement.md | 116 ++++++++++++++++++++++++++++++++++ 3 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/cli/db.md create mode 100644 docs/cli/measurement.md diff --git a/docs/cli/db.md b/docs/cli/db.md new file mode 100644 index 0000000..fc11c47 --- /dev/null +++ b/docs/cli/db.md @@ -0,0 +1,136 @@ +--- +sidebar_position: 5 +--- + +# Database Administration + +`arcctl db` manages databases on an Arc cluster. The subcommands map directly onto Arc's `/api/v1/databases` endpoints. + +## Quick reference + +```bash +# List every database the active token can see +arcctl db list + +# Inspect one database (info + its measurements) +arcctl db show production + +# Create an empty database +arcctl db create metrics + +# Drop a database and ALL its files (prompts y/N; use --yes to skip) +arcctl db drop old_metrics +``` + +## `db list` + +```bash +arcctl db list +arcctl db list -o json | jq '.databases[] | select(.measurement_count > 0)' +arcctl db list -o csv > inventory.csv +``` + +Output formats: `table` (default), `json`, `csv`. Rows are sorted by name across every format so JSON / CSV / table agree on row order. + +Empty server (no databases) renders `(no databases)` so you know the call ran. + +## `db show ` + +```bash +$ arcctl db show production +Database: production +Measurements: 4 + +┌─────────────┬───────┐ +│ MEASUREMENT │ FILES │ +├─────────────┼───────┤ +│ cpu │ │ +│ disk │ │ +│ mem │ │ +│ net │ │ +└─────────────┴───────┘ +``` + +Combines `GET /api/v1/databases/:name` with `GET /api/v1/databases/:name/measurements`. JSON output (`-o json`) composes them into one object: + +```json +{ + "database": { "name": "production", "measurement_count": 4 }, + "measurements": [{ "name": "cpu" }, { "name": "disk" }, ...], + "count": 4 +} +``` + +`-o csv` emits only the measurements list — the database header isn't tabular-shaped. + +If either API call fails, `arcctl` exits with that error and prints nothing — better to fail loud than render half a view. + +## `db create ` + +```bash +$ arcctl db create metrics +Created database "metrics" (created_at: 2026-05-31T23:39:58Z) +``` + +Server-side validation: + +- Name must start with a letter and contain only alphanumeric, underscore (`_`), or hyphen (`-`) characters, max 64. +- Names `system`, `internal`, `_internal` are reserved. +- Creating a database that already exists returns HTTP 409. + +The server's error messages surface verbatim, so a rejected create gives an actionable hint: + +```bash +$ arcctl db create 1bad +Error: arc: Invalid database name: must start with a letter and contain only alphanumeric characters, underscores, or hyphens (max 64 characters) (HTTP 400) +``` + +## `db drop ` + +**Destructive.** Drops a database and **all** of its files. + +```bash +# Interactive: prompts y/N +$ arcctl db drop old_metrics +Delete database "old_metrics" and ALL its files? [y/N] y +Deleted database "old_metrics" + +# Scripted: --yes skips the prompt +$ arcctl db drop --yes ci_scratch +Deleted database "ci_scratch" +``` + +Layered safety. arcctl gates the call client-side; Arc gates it server-side: + +1. **Client-side prompt** — default is N. Pass `--yes` (or `-y`) to skip; anything other than `y` / `yes` (case-insensitive) aborts. +2. **Server requires `delete.enabled=true`** in `arc.toml`. If not set, the server returns HTTP 403 with the verbatim message `"Delete operations are disabled. Set delete.enabled=true in arc.toml to enable."` — arcctl surfaces it as-is. +3. **Server requires admin token.** A read- or write-only token gets HTTP 403 from the server, surfaced verbatim. +4. **Server blocks reserved names** (`system`, `internal`, `_internal`). HTTP 403, surfaced verbatim. +5. **Server requires `?confirm=true`** on the request URL. arcctl always sends it; no operator-visible knob. + +`arcctl` never bypasses any of these. If a drop fails, the message will tell you why. + +## Connection overrides + +All `db` subcommands accept the same connection flags as `query` and `write`: + +```bash +# Named profile +arcctl db list --connection prod + +# Ad-hoc (no profile) +arcctl db list --endpoint https://arc.x.example.com --token YOUR-TOKEN + +# CI-friendly env vars +ARC_CONNECTION=prod arcctl db list +ARC_ENDPOINT=https://... ARC_TOKEN=... arcctl db list +``` + +See [Connection management](/arc/cli/connections#precedence) for the full precedence rules. + +## Exit codes + +| Code | Meaning | +|---|---| +| 0 | Success (including `Aborted.` on a declined `db drop` prompt) | +| 1 | Any failure: bad flags, network error, server error, missing connection | diff --git a/docs/cli/index.md b/docs/cli/index.md index c430a2f..42bfcfc 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -34,7 +34,8 @@ Operating Arc without arcctl means: |---|---| | v0.1.0 (PR1) | `config` subcommand tree, multi-connection store at `~/.arcctl/config.toml` | | v0.2.0 (PR2) | `query`, `write` — table / JSON / CSV / Arrow IPC output, stdin / file input | -| v0.3.0+ | `db`, `import`, `auth`, `cluster` subcommands (in development) | +| v0.3.0 (PR3) | `db {list,show,create,drop}`, `measurement list` | +| v0.4.0+ | `import`, `auth`, `cluster` subcommands (in development) | | v1.0.0 | release workflow + Homebrew tap + multi-arch Docker | ## Compatibility @@ -59,3 +60,5 @@ Requires Go 1.25+. - [Connection management](/arc/cli/connections) — adding, switching, and overriding connection profiles - [Querying](/arc/cli/query) — running SQL with table / JSON / CSV / Arrow output - [Writing line protocol](/arc/cli/write) — stdin and file ingestion with precision control +- [Database administration](/arc/cli/db) — list / show / create / drop databases +- [Measurement listing](/arc/cli/measurement) — list measurements within a database diff --git a/docs/cli/measurement.md b/docs/cli/measurement.md new file mode 100644 index 0000000..d4acc0b --- /dev/null +++ b/docs/cli/measurement.md @@ -0,0 +1,116 @@ +--- +sidebar_position: 6 +--- + +# Measurement Listing + +`arcctl measurement list` shows the measurements inside one database. It's a thin wrapper over `GET /api/v1/databases/:name/measurements` — the same data as `arcctl db show `, but presented measurement-first. + +Use `arcctl db show` when you want database metadata plus its measurements. Use `arcctl measurement list` when measurements are the primary thing you care about (scripts, CI, alerts). + +## Quick reference + +```bash +# Use the active connection's default_database +arcctl measurement list + +# Explicit database +arcctl measurement list --database metrics + +# Pipe to jq +arcctl measurement list --database logs -o json | jq '.measurements[].name' + +# Save to CSV (includes the database column for downstream joins) +arcctl measurement list --database production -o csv > production-measurements.csv +``` + +## Database selection + +The database name comes from one of three places, in this precedence: + +1. `--database NAME` flag +2. Active connection's `default_database` (set via `arcctl config create --default-database NAME`) +3. *(nothing else)* + +If neither is set, the command exits with a clear error before any network call: + +```bash +$ arcctl measurement list +Error: no database specified (pass --database or set default_database on the active connection) +``` + +## Output formats + +### Table (default) + +```bash +$ arcctl measurement list --database production +┌─────────────┬───────┐ +│ MEASUREMENT │ FILES │ +├─────────────┼───────┤ +│ cpu │ │ +│ disk │ │ +│ mem │ │ +│ net │ │ +└─────────────┴───────┘ +``` + +Rows sorted alphabetically. `FILES` is empty when the server omits the field (older Arc versions or when file counts haven't been computed). + +Empty database: `(no measurements in database "X")` so you know the call ran. + +### JSON + +```bash +$ arcctl measurement list --database production -o json +{ + "database": "production", + "measurements": [ + { "name": "cpu" }, + { "name": "disk" }, + { "name": "mem" }, + { "name": "net" } + ], + "count": 4 +} +``` + +Server-reported `count` is passed through verbatim — not re-derived from `len(measurements)` — so a future Arc server that paginates results will not silently disagree with itself. + +### CSV + +```bash +$ arcctl measurement list --database production -o csv +database,measurement,file_count +production,cpu, +production,disk, +production,mem, +production,net, +``` + +The CSV includes a leading `database` column so you can concatenate output across multiple `arcctl measurement list` calls without losing context: + +```bash +for db in production staging logs; do + arcctl measurement list --database "$db" -o csv --no-header +done > all-measurements.csv +``` + +## Connection overrides + +Same flags as every other arcctl command: + +```bash +arcctl measurement list -c prod --database metrics +arcctl measurement list --endpoint https://arc.x.example.com --token YOUR-TOKEN --database logs +ARC_CONNECTION=prod arcctl measurement list --database metrics +``` + +See [Connection management](/arc/cli/connections#precedence). + +## Exit codes + +| Code | Meaning | +|---|---| +| 0 | Success (including 0 measurements) | +| 1 | Any failure: missing database, network error, server error, missing connection |