feat(databases): add --catalog flag to databases create (#125)

* feat(databases): add --catalog flag to databases create

Maps to the default_catalog field on POST /v1/databases, separating
the human-readable --name from the SQL catalog alias used in queries.

Also fixes config tests that failed when HOTDATA_API_KEY was set in the
environment by unsetting it inside the with_temp_config_dir test helper.

* fix(databases): correct expires_at doc — omitting always means no expiry

* fix(databases): add default_catalog to Database struct; use catalog in all output

- Add `default_catalog` field to `Database` struct so `databases show`
  and table commands use the correct SQL alias instead of falling back
  to the display name
- Use default_catalog (falling back to name, then "default") in
  databases show sql_prefix, tables list full_name, tables load, and
  tables delete output
- Fix --catalog arg doc: remove stale 24h expiry claim
- Update README and skills/hotdata/SKILL.md to document --name as
  display name and --catalog as the SQL alias, with corrected examples

---------

Co-authored-by: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com>

Author: eddietejeda

README.md

@@ -130,14 +130,14 @@ hotdata connections create --name "my-conn" --type postgres --config '{"host":".
 
 ## Databases
 
-Managed databases are Hotdata-owned catalogs you create and populate yourself (no remote source to sync). Query them with SQL as `database_name.schema.table` — the database name is the connection name.
+Managed databases are Hotdata-owned catalogs you create and populate yourself (no remote source to sync). Query them with SQL as `<catalog>.schema.table`.
 
 ```sh
 hotdata databases list [-w <id>] [-o table|json|yaml]
-hotdata databases create --name <name> [--table <table> ...] [--schema public] [-o table|json|yaml]
+hotdata databases create [--name <display_name>] [--catalog <alias>] [--table <table> ...] [--schema public] [--expires-at <duration|timestamp>] [-o table|json|yaml]
 hotdata databases <name_or_id> [-o table|json|yaml]
 hotdata databases delete <name_or_id>
-hotdata databases run [--database <id>] [--description <label>] [--schema public] [--table <table> ...] [--expires-at <duration|timestamp>] <cmd> [args...]
+hotdata databases run [--database <id>] [--name <label>] [--schema public] [--table <table> ...] [--expires-at <duration|timestamp>] <cmd> [args...]
 hotdata databases <id> run <cmd> [args...]
 
 hotdata databases tables list <database> [--schema <name>] [-o table|json|yaml]
@@ -146,15 +146,15 @@ hotdata databases tables load <database> <table> --upload-id <id> [--schema publ
 hotdata databases tables delete <database> <table> [--schema public]
 ```
 
-- `create` registers a managed connection (`source_type: managed`) with no external credentials. Use `--table` to declare tables up front (required before `tables load` on the current API).
+- `create` registers a managed connection with no external credentials. `--name` is a human-readable display name; `--catalog` sets the SQL alias used in queries (`SELECT … FROM <catalog>.schema.table`) and must be `[a-z_][a-z0-9_]*`. Use `--table` to declare tables up front (required before `tables load` on the current API).
 - `tables load` uploads a **parquet** file (or uses a staged `upload_id` from `POST /v1/files`) and publishes it as the table generation (`replace` mode).
-- `run` mints a database-scoped JWT and execs `<cmd>` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected into its environment. Pass a database id (group-positional `<id>` like `sandbox run`, or `--database <id>`) to scope an existing database; omit both to auto-create a scratch one using `--description` / `--schema` / `--table` / `--expires-at`. Useful for launching an agent or child process whose API access is restricted to a single database.
+- `run` mints a database-scoped JWT and execs `<cmd>` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected into its environment. Pass a database id (group-positional `<id>` like `sandbox run`, or `--database <id>`) to scope an existing database; omit both to auto-create a scratch one using `--name` / `--schema` / `--table` / `--expires-at`. Useful for launching an agent or child process whose API access is restricted to a single database.
 - For CSV/JSON uploads without a managed database, use `hotdata datasets create` instead (`datasets.main.*`).
 
 Example:
 
 ```sh
-hotdata databases create --name sales --table orders
+hotdata databases create --name "Sales reporting" --catalog sales --table orders
 hotdata databases tables load sales orders --file ./orders.parquet
 hotdata query "SELECT count(*) FROM sales.public.orders"
 ```

skills/hotdata/SKILL.md

@@ -187,39 +187,39 @@ hotdata connections create \
 
 ```
 hotdata databases list [--workspace-id <workspace_id>] [--output table|json|yaml]
-hotdata databases create [--name <catalog_name>] [--table <table> ...] [--schema public] [--expires-at <duration|timestamp>] [--workspace-id <workspace_id>] [--output table|json|yaml]
-hotdata databases set <id_or_description>
-hotdata databases <id_or_description> [--workspace-id <workspace_id>] [--output table|json|yaml]
-hotdata databases delete <id_or_description> [--workspace-id <workspace_id>]
-hotdata databases run [--database <id>] [--name <catalog_name>] [--schema public] [--table <table> ...] [--expires-at <duration|timestamp>] [--workspace-id <workspace_id>] <cmd> [args...]
+hotdata databases create [--name <display_name>] [--catalog <alias>] [--table <table> ...] [--schema public] [--expires-at <duration|timestamp>] [--workspace-id <workspace_id>] [--output table|json|yaml]
+hotdata databases set <id_or_name>
+hotdata databases <id_or_name> [--workspace-id <workspace_id>] [--output table|json|yaml]
+hotdata databases delete <id_or_name> [--workspace-id <workspace_id>]
+hotdata databases run [--database <id>] [--name <label>] [--schema public] [--table <table> ...] [--expires-at <duration|timestamp>] [--workspace-id <workspace_id>] <cmd> [args...]
 hotdata databases <id> run <cmd> [args...]
 
 # Dot-notation shorthand for load: database.table or database.schema.table
 hotdata databases load <database.table> [--file ./data.parquet] [--url <url>] [--upload-id <id>] [--workspace-id <workspace_id>]
 
-hotdata databases tables list [--database <id_or_desc>] [--schema <name>] [--workspace-id <workspace_id>] [--output table|json|yaml]
-hotdata databases tables load <table> [--database <id_or_desc>] [--schema public] [--file ./data.parquet] [--url <url>] [--upload-id <id>] [--workspace-id <workspace_id>]
-hotdata databases tables delete <table> [--database <id_or_desc>] [--schema public] [--workspace-id <workspace_id>]
+hotdata databases tables list [--database <id_or_name>] [--schema <name>] [--workspace-id <workspace_id>] [--output table|json|yaml]
+hotdata databases tables load <table> [--database <id_or_name>] [--schema public] [--file ./data.parquet] [--url <url>] [--upload-id <id>] [--workspace-id <workspace_id>]
+hotdata databases tables delete <table> [--database <id_or_name>] [--schema public] [--workspace-id <workspace_id>]
 ```
 
 - `list` — all managed databases in the workspace.
-- `create` — creates a new managed database. `--name` is an optional catalog alias used in queries (`SELECT … FROM <name>.public.<table>`); must be `[a-z_][a-z0-9_]*`. `--expires-at` accepts relative durations (`24h`, `7d`, `90m`) or an RFC 3339 timestamp; defaults to `24h` when omitted. Repeat `--table` to declare tables up front.
-- `set` — saves `<id_or_description>` as the active database. Subsequent `databases tables` and `context` commands use it automatically.
-- `<id_or_description>` — inspect one database (id, description, expires_at).
+- `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.
+- `set` — saves `<id_or_name>` as the active database. Subsequent `databases tables` and `context` commands use it automatically.
+- `<id_or_name>` — inspect one database (id, catalog, name, expires_at).
 - `delete` — removes the managed database; clears the active-database config if it matched.
 - `load` — shorthand with dot notation (`database.table` or `database.schema.table`). Schema defaults to `public`.
-- `tables list` — lists tables with `TABLE` (`<database_id>.<schema>.<table>`), `SYNCED`, `LAST_SYNC`. Uses active database when `--database` is omitted.
+- `tables list` — lists tables with `TABLE` (`<catalog>.<schema>.<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 `<cmd>` 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 <id> run ...`, sandbox-style) or via `--database <id>`; 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"]`, `source:"database_token"`. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated.
 
 Example:
 
 ```
-hotdata databases create --name sales --table orders
+hotdata databases create --name "Sales reporting" --catalog sales --table orders
 hotdata databases set <returned-id>
 hotdata databases tables load orders --file ./orders.parquet
-hotdata query "SELECT count(*) FROM <database_id>.public.orders"
+hotdata query "SELECT count(*) FROM sales.public.orders"
 ```
 
 ### List Tables and Columns

src/command.rs

@@ -563,13 +563,15 @@ pub enum DatabasesCommands {
 
     /// Create a new managed database
     Create {
-        /// SQL catalog alias — becomes the catalog name in queries:
-        /// SELECT … FROM <name>.public.<table>.
-        /// Must be [a-z_][a-z0-9_]*, globally unique. When provided the
-        /// database defaults to no expiry; omit for an anonymous 24h sandbox.
+        /// Human-readable display name for the database (e.g. "Sales reporting").
         #[arg(long)]
         name: Option<String>,
 
+        /// SQL catalog alias used in queries: SELECT … FROM <catalog>.schema.table.
+        /// Must be [a-z_][a-z0-9_]*, globally unique.
+        #[arg(long)]
+        catalog: Option<String>,
+
         /// Default schema for bare `--table` entries (default: public).
         /// Use dot notation in `--table` to target a different schema directly,
         /// e.g. `--table raw.raw_orders` always goes into the "raw" schema.
@@ -583,8 +585,7 @@ pub enum DatabasesCommands {
         tables: Vec<String>,
 
         /// When the database expires. Accepts a relative duration (e.g. 24h, 7d, 90m)
-        /// or an RFC 3339 timestamp. Omitting with --name means no expiry; omitting
-        /// without --name defaults to 24h.
+        /// or an RFC 3339 timestamp. Omitting means no expiry.
         #[arg(long)]
         expires_at: Option<String>,
 

src/config.rs

@@ -354,7 +354,10 @@ pub mod test_helpers {
         let guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let tmp = tempfile::tempdir().unwrap();
         // SAFETY: tests are serialized via ENV_LOCK mutex, so no concurrent env mutation.
-        unsafe { std::env::set_var("HOTDATA_CONFIG_DIR", tmp.path()) };
+        unsafe {
+            std::env::set_var("HOTDATA_CONFIG_DIR", tmp.path());
+            std::env::remove_var("HOTDATA_API_KEY");
+        }
         (tmp, guard)
     }
 }