# AddisDB setup for coding agents

AddisDB is a database client (desktop app, CLI, VS Code extension) built to
prevent accidental damage to production databases. These instructions are for
you, the coding agent. Follow them in order.

## 1. Confirm with the user first

Tell the user you will install:

- the `addisdb` CLI (to `~/.addisdb/bin`, no admin rights),
- the AddisDB desktop app (skipped automatically over SSH or with no display),
- the AddisDB VS Code extension (only if VS Code, Cursor or Windsurf is installed),
- an MCP server entry so you can use AddisDB's database tools.

Ask them to confirm. If they want to see the plan first, run the installer with
`--dry-run` (PowerShell: `-DryRun`) and show them the output.

## 2. Install

macOS / Linux:

```sh
curl -fsSL https://www.addisdb.com/install.sh | sh -s -- --yes --agent <your-name>
```

Windows (PowerShell):

```powershell
& ([scriptblock]::Create((irm https://www.addisdb.com/install.ps1))) -Yes -Agent <your-name>
```

Use `claude-code`, `codex`, `cursor`, `vscode` or `windsurf` for `<your-name>`.
Other options: `--no-desktop`, `--no-vscode` (PowerShell: `-NoDesktop`, `-NoVscode`).

The last line of output is JSON. Report what it says to the user: what was
installed, what was already current, and anything skipped and why.

Re-running the same command is safe. It updates what is out of date and skips
what is current, so "update AddisDB" is the same instruction.

## 3. Verify

```sh
addisdb --version
addisdb agent status
```

If `addisdb` isn't found, use the full path `~/.addisdb/bin/addisdb`
(Windows: `%LOCALAPPDATA%\AddisDB\bin\addisdb.exe`). You may need to restart
your session to load the new MCP server.

## 4. If registration failed, register manually

- Claude Code: `claude mcp add --scope user addisdb -- ~/.addisdb/bin/addisdb mcp`
- Codex: add to `~/.codex/config.toml`:
  `[mcp_servers.addisdb]` with `command = "<path to addisdb>"` and `args = ["mcp"]`
- Cursor: add `"addisdb": {"command": "<path to addisdb>", "args": ["mcp"]}`
  under `mcpServers` in `~/.cursor/mcp.json`
- VS Code: `code --add-mcp '{"name":"addisdb","command":"<path to addisdb>","args":["mcp"]}'`

Or re-run `addisdb agent setup --agent <your-name>`, which prints the exact
manual step if it can't do it for you.

## 5. Connections

Never ask the user to paste database passwords, tokens or connection strings to
you. If a connection is missing, call `addisdb_open` with
`view: "new_connection"` and ask them to add it in the app, then refer to it by
the name `addisdb_list_connections` returns.

## 6. Using AddisDB while you work

Call `addisdb_status` first when unsure: it says which surfaces are open and
what the user allows you to do.

Reads (work with only the CLI, including over SSH; read-only sessions):

- `addisdb_list_connections`: saved connections, with engine and environment tag (prod, staging, …).
- `addisdb_schema`: tables, columns and keys. Filter with `schema` / `tables` on big databases.
- `addisdb_query`: run read-only SQL. Results are capped (200 rows by default).
- `addisdb_explain`: the query plan, without running the query.
- `addisdb_preview_migration`: the risks in migration SQL, with severities. Nothing is executed.
- `addisdb_inspect`: databases on the server, an object's definition, what a table drop would affect, exact counts, cost estimates, how the safety layer classifies SQL, a connection test, the server's users.
- `addisdb_monitor`: live sessions, server metrics, the costliest statements, local database servers.
- `addisdb_compare`: one read-only query across several connections, diffed.
- `addisdb_orm`: a Drizzle or Prisma project's schema, pending migrations and drift.
- `addisdb_workflow`: the user's saved automations (list, show, validate).
- `addisdb_mock_data`: plan mock data and review past runs.
- `addisdb_data_map`: which columns hold personal, health or payment data.

Changes (each one waits for the user to click Approve; nothing runs otherwise):

- `addisdb_apply_migration`: any SQL that changes data or schema.
- `addisdb_drop_table` / `addisdb_restore_table`: drop with a safety copy, and undo it.
- `addisdb_import_csv`, `addisdb_export`, `addisdb_backup`: move data in and out.
- `addisdb_generate_mock_data` / `addisdb_clear_mock_data`: tracked test rows.
- `addisdb_sandbox`: a disposable copy of a database to try a migration on. Making the copy is approved; SQL on the copy runs freely.
- `addisdb_kill_query`, `addisdb_run_workflow`, `addisdb_local_server`, `addisdb_create_database`.

Mock data and the AI steps of a workflow need a model partway through. The user
does not need an AI key for that: when no AI provider is set up in AddisDB, the
tool pauses and returns an `aiRequest` with the prompt, and you answer it with
`addisdb_ai_reply`. The tool then carries on.

Surface tools (put things in front of the user; `surface` is `desktop`, `vscode`
or `terminal`, and a surface that isn't open is launched):

- `addisdb_open`: bring AddisDB forward on a view (data, schema, monitor, profiler, migrations, history, settings and more), optionally with a connection in focus. `new_connection` asks the user to add a database.
- `addisdb_show_query`: SQL in a new editor tab marked as yours; `run: true` runs it (read-only SQL only).
- `addisdb_show_table`: a table's data, optionally with a WHERE `filter`.
- `addisdb_show_erd`: the ER diagram, showing only the `tables` you name.
- `addisdb_show_object`, `addisdb_show_migration`: a view or function's definition; migration SQL in the Migrations view (shown, not run).
- `addisdb_get_view`: what the user has open (view, connection, tab, SQL, table). Use it for "this query".
- `addisdb_ui`: list, select and close editor tabs (only ones you opened), connect and disconnect.

The desktop app has every view. VS Code and the terminal UI have fewer and say
so; pass `surface: "desktop"` when one can't show something.

Rules:

- When you query, inspect or change a database, offer once per task:
  "Want to see this in AddisDB?" If yes, or if the user says "show me in
  AddisDB", use the surface tools.
- Before any schema change, call `addisdb_preview_migration` and show the user
  the risks. Then `addisdb_apply_migration`. If the user denies a change, stop:
  don't retry, and don't reach it another way (another tool, a shell client).
- The user sets the rules in AddisDB (Settings, Coding agents): whether you may
  be used at all, whether reads need their approval too, and whether changes
  are possible. A tool that says something is switched off means ask the user,
  not try another route.
- Prefer narrow queries (`WHERE`, `LIMIT`, named columns) over `SELECT *`.
- Columns the user marked sensitive come back as `[masked]`, and schemas flag
  them with `"masked": true`. If a query uses one, every value in that result
  is withheld, and the `privacy` field says which column to leave out. Tools
  that can't mask what they return (export, compare, backup, activity) refuse a
  database with locks. Never try to recover masked values; if the user needs
  them, they can unmask the column in AddisDB (AI Privacy) or with
  `addisdb ai-policy unmask`.
- While you're connected, AddisDB shows a banner with your name and a Stop
  button. Stop abandons whatever you had running. If a tool says the user
  pressed Stop, stop using AddisDB until they ask you to continue.
- AddisDB is free for databases on the user's own machine. If a tool says a
  remote database needs a paid plan, tell the user that; don't retry.
- Without MCP, the same surface calls exist as commands: `addisdb open --view
  monitor --connection staging`, `addisdb show query --connection staging
  "select 1" --run`, `addisdb show table`, `addisdb show erd`, `addisdb show view`.

## 7. Make it stick (optional)

To have agents in a repo offer AddisDB unasked, the user can run
`addisdb agent snippet --write` (adds a section to `AGENTS.md`), or
`--format cursor` / `--format claude-skill`.

## Troubleshooting

- `addisdb: command not found`: open a new shell, or add `~/.addisdb/bin` to PATH.
- Headless or SSH session: the desktop app is skipped; the CLI and the
  read tools still work, but the surface tools and every change say no display
  is available (there is nowhere for the user to approve).
- "Coding agents are switched off": the user turned agents off in AddisDB
  (Settings, Coding agents). Ask them; don't work around it.
- `addisdb agent status` shows `registered, but … doesn't exist`: run
  `addisdb agent setup --agent <your-name>` again.