@metabase/rde 0.1.7 → 0.1.9

package/README.md

@@ -54,12 +54,12 @@ The git step reads `–` until a license with remote sync is active; it is check
 | --- | --- |
 | Check this machine | Platform, Node version, git, and a reachable Docker daemon or a Java 21+ runtime |
 | Install the Metabase CLI | `@metabase/cli` (`mb`) at the `alpha-fix-transform-test-ee-path` dist-tag, with the package manager that installed `rde` |
-| Install the rde and data-app skills | The data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`) from `metabase/metabase/skills#master`, then the `rde` and `rde-data-apps` skills from the `rde-generic-skills` branch of `metabase/agent-skills` (the rde skill hands an explicit app request to `rde-data-apps`, which hands the build to the data-app skills), for the coding agents you pick at a terminal, from the ones found on this machine (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf) plus OpenCode, which is always offered: picked while missing, it is installed first (`opencode-ai` with the package manager that installed `rde`). Without a terminal, or with `--yes`, every agent found gets the skills; `--agents` picks a set ahead of time (`opencode` in it is installed when missing), `--skip-agents` none; `RDE_SKILL_SOURCE` installs the two rde skills from another URL or a local checkout of `metabase/agent-skills` |
+| Install the rde and data-app skills | The data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`) from `metabase/metabase/skills#master`, then the `rde` and `rde-data-apps` skills from the `rde-generic-skills` branch of `metabase/agent-skills` (the rde skill hands an explicit app request to `rde-data-apps`, which hands the build to the data-app skills), for the coding agents you pick at a terminal, from the ones found on this machine (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf). When none is found, the step is skipped and says how to add the skills once an agent is installed; `rde` installs no agent. Without a terminal, or with `--yes`, every agent found gets the skills; `--agents` picks a set ahead of time (the skills are installed for them whether or not they are on the machine yet), `--skip-agents` none; `RDE_SKILL_SOURCE` installs the two rde skills from another URL or a local checkout of `metabase/agent-skills` |
 | Install Metabase | **Docker** when it is available: pulls `metabase/metabase-enterprise-head:latest` (or `--image`) and creates the container. **Jar** otherwise, or with `--runtime jar`: downloads the latest enterprise release (or the tag or `.jar` path given as `--jar`) into `~/.rde/jars/` and runs it with your Java. Either way on port 3100, or the first free port above it, or `--port` |
 | Start Metabase | Starts the container or the jar and waits for `/api/health`, showing Metabase's own progress |
 | Create the admin user | `admin@metabase.local` with a generated password that `rde credentials` shows, or your own with `--admin prompted`, see [Credentials](#credentials) |
 | Connect the Metabase CLI | Creates an API key named `rde` and logs `mb` in with it under the profile `default`, so plain `mb` uses the instance; when `default` already points at another Metabase it asks first, see [The `mb` profile](#the-mb-profile); a key Metabase rejects is replaced |
-| Connect a sample database | Runs Metabase's Postgres sample data (`metabase/qa-databases:postgres-sample-15`) in a container named `rde-sampledb-default` on the first free port from 15432, connects it as `Sample Database`, and switches transforms on. It replaces the H2 sample database Metabase would otherwise bundle, which cannot be a transform target. Needs Docker, so a jar instance on a machine without Docker keeps the H2 one instead |
+| Connect a sample database | Runs Metabase's Postgres sample data (`metabase/qa-databases:postgres-sample-15`) in a container named `rde-sampledb-default` on the first free port from 15432 (or one Docker picks, when another program or a concurrent `rde init` takes that port first), connects it as `Sample Database`, and switches transforms on. It replaces the H2 sample database Metabase would otherwise bundle, which cannot be a transform target. Needs Docker, so a jar instance on a machine without Docker keeps the H2 one instead |
 | Activate your license | Optional. Paste a token, or press Enter to skip; remote sync needs one with the `remote-sync` feature |
 | Connect your databases | At a terminal, until you connect one of your own or skip it: paste a connection string (Enter skips), review, test, add; repeat. `--database` names them ahead of time; with `--yes` or without a terminal nothing is asked. `rde db add` starts from the engine list, where the fields can also be filled one by one |
 | Connect a git repository | Only with a license. Initializes or reuses a repository and points Metabase's remote sync at it |
@@ -89,7 +89,7 @@ The second run on the same machine detects every step as done and prints the sum
 │  Metabase CLI: mb <command>                                                        │
 │  Databases:                                                                        │
 │    Sample Database (postgres, sync complete)                                       │
-│    warehouse (postgres, sync complete)                                             │
+│    warehouse (postgres, syncing; `rde status` shows when it finishes)              │
 │  Sample database: psql "postgres://metabase:metasample123@localhost:15432/sample"  │
 │  Remote sync: not configured (no license)                                          │
 │  rde skill: installed for Claude Code                                              │
@@ -102,7 +102,7 @@ The second run on the same machine detects every step as done and prints the sum
 └  rde init finished
 ```
 
-Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. A step that fails ends the run with exit code 1 (2 for a missing answer) and a last line naming the step and the command that resumes there: `rde init stopped at "Connect a sample database": <reason>. Resume with rde init --from sample-database.` `rde init --from license` re-runs from a step on, `rde init --only databases` runs one step.
+Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. A step that fails ends the run with exit code 1 (2 for a missing answer) and a last line naming the step and the command that resumes there: `rde init stopped at "Connect a sample database": <reason>. Resume with rde init --from sample-database.` `rde init --from license` re-runs from a step on (a later step that does not apply, such as the git step without a license that has remote sync, stays skipped), `rde init --only databases` runs one step.
 
 ## The sample database
 
@@ -167,7 +167,7 @@ Docker is used whenever it is available: the image is self-contained, and the co
 | `rde credentials` | The Metabase URL, admin email, and password; `--json` for scripts and agents; `--api-key` for the API key alone |
 | `rde logs` | The container's log, or the jar's `metabase.log`; `-f` keeps streaming |
 | `rde open` | Opens the instance in the browser |
-| `rde db add` | The database wizard: pick the engine, paste a connection string or fill the fields, review, test, add |
+| `rde db add` | The database wizard: pick the engine, paste a connection string or fill the fields, review, test, add. `rde db add --url <connection string> [--name <display name>]` asks nothing: it reads the engine from the string (`--engine` for one that fits several), tests it and adds it, which is how a script or a coding agent connects a database without a terminal; `--url -` reads the string from stdin |
 | `rde db list` | The connected databases; `--json` for scripts; a bare `rde db` does the same |
 | `rde doctor` | One table of checks with a fix hint per failure; `--fix` re-runs the init steps behind them; `--json` for scripts and the rde skill (every row's `id`, `status`, `detail`, `hint`, and `fix`: the `rde` command that repairs it, or null when you have to act); exit 1 while anything fails |
 | `rde upgrade` | Moves the instance to a newer Metabase after backing up its data; see [Upgrading](#upgrading) |
@@ -191,17 +191,17 @@ mb git-sync status
 
 ## The git repository
 
-With a license that includes remote sync, the last step connects a git repository. You choose where the working directory lives (here, a new directory, or an existing repository) and where Metabase pushes:
+With a license that includes remote sync, the last step connects a git repository. You choose where Metabase pushes, then where the working directory lives (here, another directory, or an existing repository):
 
 - **Local remote inside `~/.rde`** (default): a bare repository at `instances/default/data/content.git`, mounted into the container and reached as `file:///rde/content.git`. No account, no token. Your working directory gets it as `origin` (or as `rde-remote` when `origin` already points elsewhere).
-- **Hosted remote**: a GitHub, GitLab, or Bitbucket `https://` URL plus a token with read and write access. `rde` tests the connection through Metabase before saving anything.
+- **Hosted remote**: a GitHub, GitLab, or Bitbucket `https://` URL plus a token with read and write access. `rde` tests the connection through Metabase before saving anything, then clones the repository into the working directory (an existing repository gets the URL as `origin` instead); an empty hosted repository gets the first commit pushed to it. The token is handed to Metabase and, for the clone and that first push, to git in its environment; it never lands in the clone's config, the remote URL, or a credential helper, so a later `git pull` uses your own git credentials.
 
 A fresh repository gets a first commit with a `README.md` and a `.gitignore` that keeps out what a data app built in it must not push: `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `.vite/`, the rde skill's `.scratch/`, and `.DS_Store` (a data app's built `dist/` stays tracked, since that bundle is what Metabase serves); a `.gitignore` already there keeps its lines and gets the missing ones, and a repository that already has commits is left as it is. A repository that already holds Metabase content is imported on the spot. Afterwards:
 
 ```sh
 cd <your working directory>
 mb git-sync status
-mb git-sync export -m "what changed"
+mb git-sync export -b <branch> -m "what changed"   # init prints it with your branch
 git pull   # after an export, to see the YAML files
 ```
 
@@ -219,14 +219,14 @@ rde init --skip-license \
 
 | Flag | Answers |
 | --- | --- |
-| `--agents claude-code,codex` / `--skip-agents` | Which agents get the skill, instead of asking at a terminal or taking the ones found on the machine; a missing `opencode` is installed |
+| `--agents claude-code,codex` / `--skip-agents` | Which agents get the skill, instead of asking at a terminal or taking the ones found on the machine |
 | `--runtime docker\|jar`, `--image`, `--jar`, `--port` | How Metabase runs, the Docker image or the jar (`latest`, a release tag, or a `.jar` path), and the host port, instead of Docker when available, `metabase/metabase-enterprise-head:latest`, the latest release, and the first free port from 3100; `--image` implies `docker` and `--jar` implies `jar`; the sample database always runs in Docker |
 | `--admin generated\|prompted`, `--admin-email`, `--admin-password` | The admin user, `generated` unless given; an email or password implies `prompted` |
 | `--license-token` / `--skip-license` | The license |
 | `--database <engine>=<connection string>` (repeatable) / `--skip-databases` | Your own databases; `--skip-databases` connects none of them, and the sample database is still connected |
 | `--git-dir`, `--git-remote local\|hosted`, `--git-url`, `--git-token` / `--skip-git` | The content repository; a remote or URL without `--git-dir` means the current directory |
 | `--mb-profile default\|rde` | The `mb` profile when `default` already points at another Metabase; `default` (replace it) unless given |
-| `--yes` | Every confirmation, and the recommended choice of a question (replacing `default`); skips the question about your own databases, and the sample database is still connected |
+| `--yes` | Every confirmation, and the recommended choice of a question (replacing `default`); skips the question about your own databases, and the sample database is still connected. A driver's toggle (SSL, an SSH tunnel) is a setting, not a confirmation, and keeps the driver's default |
 
 A secret flag (`--admin-password`, `--license-token`, `--git-token`) takes `-` to read one line from stdin, the way `mb auth login` takes its key, or a literal `$VAR` (single-quoted, so the shell leaves it alone) to read the environment; either keeps the value out of your shell history and process listings. Only one flag can read stdin.
 
@@ -253,11 +253,11 @@ rde init --license-token '$RDE_LICENSE_TOKEN' …
 }
 ```
 
-`"runtime"` takes `"kind": "docker"` or `"jar"`, which `"image"` and `"jar"` imply on their own (`"runtime": { "jar": "latest" }` runs the latest release with Java). `"license": { "token": null }` skips the license, `"databases": []` connects none, `"git-sync": { "location": "skip" }` leaves the repository for later. A database is pasted as a `uri` or entered with `fields`, keyed by the driver's field names as the admin form shows them; a file field takes a path. Anything a `fields` entry leaves out is asked in the terminal, or named in the error without one.
+`"runtime"` takes `"kind": "docker"` or `"jar"`, which `"image"` and `"jar"` imply on their own (`"runtime": { "jar": "latest" }` runs the latest release with Java). `"license": { "token": null }` skips the license, `"databases": []` connects none, `"git-sync": { "location": "skip" }` leaves the repository for later. A database is pasted as a `uri` or entered with `fields`, keyed by the driver's field names as the admin form shows them; a file field takes a path. Anything a `fields` entry leaves out is asked in the terminal, or named in the error without one. A field that engine does not ask with the others given, such as one behind the admin form's advanced options, is named in a warning and ignored.
 
 ### Recording a run
 
-`rde init --print-answers <file>` writes, once an interactive run finishes, the answers file that reproduces it: the prompts as they were answered, plus any override given by a flag. Secrets are written as references, never as values: `$RDE_ADMIN_PASSWORD`, `$RDE_LICENSE_TOKEN`, `$RDE_GIT_TOKEN`, `$RDE_DATABASE_<n>_URI` for a connection string carrying a password, and `$RDE_DATABASE_<n>_<FIELD>` for a secret field. Set those variables and run `rde init --answers <file>` on the next machine.
+`rde init --print-answers <file>` writes, once an interactive run finishes, the answers file that reproduces it: the prompts as they were answered, each database as it was added (its connection string if used as pasted, otherwise its fields), plus any override given by a flag. Secrets are written as references, never as values: `$RDE_ADMIN_PASSWORD`, `$RDE_LICENSE_TOKEN`, `$RDE_GIT_TOKEN`, `$RDE_DATABASE_<n>_URI` for a connection string carrying a password, and `$RDE_DATABASE_<n>_<FIELD>` for a secret field (a password, or an SSH private key). Set those variables and run `rde init --answers <file>` on the next machine.
 
 ## Upgrading
 
@@ -367,4 +367,12 @@ bun run build && bun run e2e:up && bun run test:e2e
 bun run e2e:down
 ```
 
+With the database stack up, the lane also connects one container per engine Metabase supports and Docker can run (Postgres, MySQL, MariaDB, ClickHouse, SQL Server, Oracle, Trino, MongoDB), each in its URL and JDBC forms, without a terminal, and waits for its first sync. These cases live in `tests/e2e/databases.e2e.test.ts`, which sets up its own instance and has one `describe` block per service in `tests/e2e/databases.compose.yml`, so `-t` picks the engines to run. CI (`.github/workflows/test.yml`) runs the unit gate, the main lane, and one job per database service, in parallel, on every pull request.
+
+```sh
+bun run e2e:databases:up mysql mongo              # any of the services; Oracle and SQL Server are large
+bun run test:e2e:databases -t '^(mysql|mongo) '   # or no -t for every service
+bun run e2e:databases:down
+```
+
 With `MB_PREMIUM_EMBEDDING_TOKEN` in the environment the lane also activates the license and connects a local git remote; without it that test is reported as skipped.