# IndyKnow multi-database quickstart — `connections.json`

Connect IndyKnow to **many databases at once** (up to 26 per profile), group them into named **profiles** — whole environments you switch between with one sentence — and never paste a password into a chat. This is the five-minute guide.

## How to think about profiles

- **A profile is an environment.** Name profiles after environments you actually have — `prod`, `staging`, `local-work`, `customer-acme` — not after individual databases.
- **Each letter is one database.** Inside a profile, slots **`A`–`Z`** each hold one database (up to 26). A database is either **cloud** (an IndySoft environment id) or **local** (your own SQL Server).
- **Two ways to target a database.** A bare letter (`db: A`) hits a slot in the **active** profile; a compound **`profile/slot`** (`db: "staging/A"`) reaches a database in **any** profile without switching — ideal for comparing or migrating across environments.
- **Read-only by default; cloud is never writable.** Local databases start read-only; set `"readOnly": false` on a slot to allow writes. A cloud database is **always** read-only. A cross-environment write is deliberate — confirm the target first.
- **Avoid `/` in a profile name.** It still works (the last `/` splits profile from slot, so `acme/thing/A` resolves), but it reads confusingly — prefer plain names.

## The easiest setup: just ask Claude

You don't need to create anything by hand. In Claude Desktop, say:

> **"Set up a connections.json for me."**

IndyKnow writes a starter file into the right folder and tells you where it landed. Even better, describe what you actually want and it writes the whole thing in one shot:

> **"Set up a connections.json with two profiles: `local-work` with my localhost `ScalesDev` database as A, and `customer-acme` with their cloud environment `<env-id>` on A and my `AcmeRestore` database on B, writable."**

Claude collects the *non-secret* details (profile names, servers, databases, logins, environment ids) and IndyKnow writes the file. **It will never ask for a password** — that part stays yours (see below).

Prefer a file to start from? Download **[connections.template.json](connections.template.json)**, save it as `connections.json` in your IndyKnow folder, and edit the placeholders:

| OS | Folder |
|---|---|
| Windows | `%APPDATA%\IndyKnow\` |
| macOS | `~/Library/Application Support/IndyKnow/` |
| Linux | `~/.config/indyknow/` |

> **Claude Desktop from the Microsoft Store?** Packaged (Store) installs are sandboxed: Windows quietly keeps this file at `%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\IndyKnow\` instead, and the `%APPDATA%\IndyKnow` folder looks **empty** in Explorer even though IndyKnow is working fine. Two rules keep this painless. First, **don't place a file into `%APPDATA%\IndyKnow` by hand** if IndyKnow already created one — Windows would keep using the LocalCache copy and silently ignore yours, and a plaintext password in your copy would never get scrubbed. Second, **don't go path-hunting at all**: just say *"open my connections file"* and it opens in Notepad at its true location, wherever that is. IndyKnow always reports the file's real path.

## Add your passwords (the one manual step)

Every **local** database in the file has an empty password line:

```json
"password": "",
```

Open the file — the zero-navigation way is to say **"open my connections file"**, which opens it in Notepad (macOS: your default text editor) at its true location — **type each password between the quotes**, save. That's it — on your next IndyKnow tool call:

1. IndyKnow **encrypts the password into its local store** — an AES-256-GCM encrypted file, keyed to *your machine*. The password never travels through the chat and never leaves your computer.
2. The file is **rewritten with `"@stored"`** in place of the password, so no plaintext lingers on disk.

Until you add a password, `whoami` marks that database **NEEDS PASSWORD** — nothing breaks, it just can't connect yet.

> **Why can't Claude type the password for me?** Anything you say in a chat is sent to the AI service. The whole design exists so your SQL password never makes that trip. Claude writes everything *except* the secret and marks exactly where it goes.

### Updating (rotating) a password

Open the file, replace `"@stored"` with the **new** password, save. Next tool call: re-encrypted, re-scrubbed back to `"@stored"`. Same flow as the first time.

## Restart Claude Desktop once after setup

Claude Desktop takes a snapshot of IndyKnow's tools **when it launches**. Creating your `connections.json` mid-session means two things don't appear until you restart:

- the **`db` parameter** — per-call database targeting ("query B") on the SQL tools
- the multi-database primer that makes Claude proactively aware of your setup

So: **finish your setup, then fully quit and reopen Claude Desktop once** (system tray → Quit — not just closing the window). You do **not** need to restart after ordinary edits, profile switches, or password changes — the file is hot-reloaded on every tool call, and `whoami` always shows the live state.

## Talking to Claude about your databases

Everything is plain English — you never need tool names:

| You say | What happens |
|---|---|
| *"whoami"* | The live picture: active profile, every database, which is default, what still needs a password. |
| *"use the customer-acme profile"* | Switches the whole set (every database in that profile). Persists across restarts. |
| *"query the EQUIPMENT table in database B"* | One call against slot B in the active profile — no switching needed. |
| *"compare EQUIPMENT in prod/A and staging/A"* | Reaches slots in other profiles via `profile/slot` — no switch, one call each. |
| *"switch my default to B"* | Omitted-db queries now hit B. |
| *"add a staging profile with env `<id>` on A"* | Claude edits the file for you — picked up on the next call. |
| *"compare the GAGES schema between A and B"* | Claude queries each side and reasons over both (no cross-DB joins — separate servers). |

## Good to know

- **Cloud databases are always read-only.** Local ones are read-only by default; set `"readOnly": false` per slot to allow writes (DDL stays blocked everywhere).
- **Broken edit? No harm.** A file that doesn't parse is ignored with a warning and your last working setup keeps running. Delete the file entirely and IndyKnow falls back to your extension Settings.
- **Sharing is safe.** Passwords are `"@stored"` and the encrypted store is keyed to your machine — hand a teammate your file and they just add *their own* passwords once.
- **"The licensing service doesn't recognize environment…"** on a cloud database means the `envId` in your file is wrong, or that environment isn't licensed / has no SQL connection provisioned yet — double-check the id (run `whoami` for the live slot map) or ask your IndySoft admin. **"Could not reach the licensing service…"** is the opposite case: an IndySoft-side outage, not a problem with your file.
- Avoid `;` inside a password — a SQL connection string can't represent it (IndyKnow warns if it sees one).