---
name: mysql-client-setup
description: "Configure mysql-client connection discovery for this project — record the command that prints the database's connection URL, write .claude/mysql-client.local.md, and add it to .gitignore. Read-only against the host and database; runs nothing privileged and never connects."
---

Resolve `../..` from this SKILL.md's directory to the absolute plugin root. Substitute that path for `<plugin-root>` in the instructions and commands below; do not assume a plugin-root shell variable is set. Keep the working directory at the consuming project root.

In Codex, select `$mysql-client:mysql-client-setup` or `$mysql-client:mysql-client-doctor`. In Claude Code, the equivalent commands are `/mysql-client:setup` and `/mysql-client:doctor`.

You are running `mysql-client-setup`: an interactive configurator. You will write **only** `.claude/mysql-client.local.md` and (if needed) a line in `.gitignore`. You will **not** run the project's `connection_cmd`, **not** connect to any database, and **not** dispatch the `mysql-investigator` agent.

First read the shared checklist at `<plugin-root>/setup-checklist.md` — it defines checks 1–6 and the remediation text. Use that text verbatim on failures.

## Flow

### 1. Prerequisite
Run check 1 (`mysql` client installed). If it fails, print its remediation text and **stop** — tell the user to re-run `mysql-client-setup` once the client is installed.

### 2. Existing settings file?
Run check 2. If `.claude/mysql-client.local.md` already exists, do **not** read it — `connection_cmd` may be a literal `echo 'mysql://user:pw@host/db'`, and reading it would put the password in the transcript. Probe it silently instead:

```bash
grep -oE '^connection_cmd: *[^ ]+' .claude/mysql-client.local.md
```

It prints `connection_cmd: <first token>` when the field is set, and nothing (exit 1) when it isn't.

Report only that `connection_cmd` is set and its first token (`make`, `vault`, `aws`, `echo`, …), never the whole line. Then ask the user: *Keep as-is* / *Reconfigure (overwrite)* / *Abort*. Stop on Keep or Abort.

### 3. Where does the connection URL come from?
The one setting, `connection_cmd`, is a command whose stdout is a `mysql://` (or `mariadb://`) URL. Ask the user — "Where does this project's MySQL connection URL come from?":

- **Build target** — "A make / just / npm / task target that prints the URL, e.g. `make infra-mysql-url`."
- **Secret store** — "A secret manager that holds the URL — Vault, AWS Secrets Manager, 1Password, SOPS."
- **Literal URL** — "You have the URL string itself; it gets wrapped in `echo`."
- **Other** — "Any other command whose stdout is the URL."

### 4. Assemble `connection_cmd`
Open `<plugin-root>/skills/mysql-client/references/local-settings.md` and show the user the example matching their answer. Ask for the specifics — the target name, secret path, the URL string, etc. — and assemble the final `connection_cmd`. Restate it and confirm before writing.

Enforce while assembling:

- The command's **stdout must be a single `mysql://` or `mariadb://` URL** — nothing else. No INI body, no log lines. For a build target, make sure the recipe is silent and add `--no-print-directory` (or the tool's equivalent) so only the URL is printed.
- Record the command **verbatim** — exactly as the user runs it to get their URL, concrete environment values and all (`ENV=dev`, `AWS_PROFILE=…`). Don't parametrize it or invent env-var placeholders. The settings file is gitignored, per-developer, and re-read every turn, so pointing at a different environment later is just editing this one line.
- Don't worry about the password in the URL — the plugin pipes the URL straight through its bundled converter into a mode-600 file in a private per-user directory, deleted after each turn; it never reaches a command line or the transcript.

### 5. Write `.claude/mysql-client.local.md`
Create the `.claude/` directory if needed. Single-line command:

```markdown
---
# Generated by mysql-client-setup. Edits take effect immediately — no restart.
# connection_cmd stdout must be a mysql:// or mariadb:// URL.
connection_cmd: <value>
---

# Project DB notes (for humans — not read by the plugin)

What this points at, which secret store, who to ping when it breaks.
```

Multi-line command — use a YAML block scalar:

```markdown
---
connection_cmd: |
  <line 1>
  <line 2>
---

# Project DB notes (for humans — not read by the plugin)
```

### 6. `.gitignore`
Run check 6. If `.gitignore` doesn't already cover the settings file, append `.claude/*.local.md` (create `.gitignore` if absent). If already covered, say so and change nothing.

### 7. Summary
Print the path written and the *shape* of the command (its first token) — not the assembled `connection_cmd`, which may embed the URL and its password. End with: "Done. The skill re-reads this file every turn — no restart needed. Run `mysql-client-doctor` to verify the URL resolves and the connection actually works."