SQL Sage documentation

01Requirements

• SQL Server Management Studio 22 (Windows, x64 or Arm64).
• Claude Code or Codex CLI installed and signed in — that's how SQL Sage reaches the AI on your own account. Install links are in the panel and on the home page. (Advanced: you can instead set your own Anthropic API key — BYOK.)
• Administrator rights to install (it writes to Program Files, standard for SSMS extensions).

02Install (2 minutes)

1. Download SqlSageSetup.exe.
2. Close SSMS.
3. Run the installer and approve the UAC prompt.
4. Open SSMS again — the SQL Sage panel opens automatically (or use View → Other Windows → SQL Sage).

03Sign in (keyless)

In the panel's status bar, pick a provider and sign in:

• Claude — via Claude Code. Click Sign in with Claude; finish in the console window that opens, then Refresh.
• OpenAI — via Codex CLI. Click Sign in with OpenAI.
• Advanced (own key) — paste an Anthropic API key (stored encrypted with DPAPI, never in plaintext).

On the two keyless channels SQL Sage never sees, stores, or transmits your credentials — it only asks the CLI whether you're signed in. An own key is the exception: it is stored on your machine, DPAPI-encrypted, as above. Pick a model from the dropdown; your history is kept when you switch provider or model.

04Everyday use

Chat in the context of your connection

The chat is locked to one server and database, shown at the top at all times, so answers know which engine, version and database they're about. Pin the chat to a specific query window (📌) when you work across several servers.

Right-click actions

Select T-SQL in a query window, right-click → Ask SQL Sage ▸ Explain / Fix / Optimize / Document (or press Ctrl+Alt+Shift+E/F/O/D). The chat opens with your SQL already in context — no copy-paste. The same actions are also under the Tools menu.

Slash commands

/explain, /optimize, /fix, /doc act on the attached query; /querystore reports regressed and expensive queries; /format formats locally with zero tokens; /help lists them.

SQL block toolbar

Every SQL block the assistant writes carries a READ / WRITE / DDL badge and one-click Copy · Insert · New query · Run · Format. Insert is never Run — putting text in your editor and executing it are two different buttons.

Read from your results (opt-in)

Off by default. Enable Include results in the panel settings, then right-click → Explain copied results (send exactly what you copied from the grid) or Attach query results (re-run). The first send per session asks for explicit consent showing the row/column count and that data will leave your machine.

05Diagnostics & health

Just ask in plain language — SQL Sage runs the right server-side check itself (authored, deterministic queries; the model interprets the numbers, it doesn't invent them):

• “Scan this database / is it healthy?” → a one-shot health check: backups, failed Agent jobs, missing indexes, fragmentation, stale statistics, memory pressure, risky options.
• “Do I have backups / what's my RPO?” → per-database last full/diff/log with a risk flag.
• “Why is it slow?” → wait stats, live blocking, deadlock history, Query Store regressions, execution plan (estimated and actual).
• “What depends on this view/table?” → impact analysis before you ALTER or DROP.
• “Who can access this / what are their permissions?” → role & permission audit with nested roles expanded.
• “Explain Msg 8134” → the real message from sys.messages, then the cause and fix.

Every fix (reindex, UPDATE STATISTICS, CREATE INDEX, ALTER DATABASE) is presented as a script for you to review and run — never executed automatically.

06Safety & privacy

• Read-only by default. Statements are classified by the same parser SSMS uses (ScriptDom). SELECT runs read-only; DML and DDL require a confirmation dialog showing the exact SQL before anything executes — every time.
• Your data stays yours. Schema metadata and your query text go to the model; query result rows never do, unless you opt in per session. Server and database names can be masked.
• Local audit. Every operation performed or blocked is appended to a local JSONL log under %LOCALAPPDATA%\SqlSage\audit\. Local-only, no network egress. Toggle it in settings.
• No token custody. Sign-in lives in Claude Code / Codex on your machine; secrets are never in plaintext, the registry, or version control.

Full details in the Privacy Policy.

07Skills

SQL Sage ships reusable expert playbooks (deadlock-triage, blocking-triage, index-tuning, query-regression, db-health-review). They use the open Anthropic Agent Skills format (SKILL.md), and SQL Sage also reads your personal ~/.claude/skills folder — the same one GitHub Copilot in SSMS and Claude Code use, so a skill you write works across all three. Drop a SKILL.md in %USERPROFILE%\.claude\skills\<name>\ and it appears automatically.

08Troubleshooting

“Windows protected your PC” / SmartScreen on install

The installer isn't code-signed yet, so SmartScreen warns. Click More info → Run anyway. You can verify the download came from sqlsage.lumasoft.pl. Code signing is in progress.

“Failed to start Claude CLI” / provider unavailable

Install and sign in to Claude Code (or Codex) first — SQL Sage reaches the AI through it. Use the install links in the panel, then click Refresh. If it was working and stopped, your CLI session may have expired — sign in again.

The assistant doesn't know my server/database

Make sure a query window is connected and active, or pin the chat to it (📌). The connection bar at the top of the panel always shows which server/database the answers use.

The panel didn't open

Open it from View → Other Windows → SQL Sage. If it's missing, restart SSMS once after installing so it merges the extension.

Right-click actions aren't in the menu

Restart SSMS once after an update so the menu re-merges. The actions are also under the Tools menu.

Trial / licence

Every install starts a 30-day free trial with all features, no credit card. Licence checks fail safe (a temporary network issue won't lock you out during the grace period).

Still stuck? See the FAQ on the home page.

09Update & uninstall

Update: the panel checks for new versions and shows a dismissible banner; download and run the latest installer (it replaces the previous build). Uninstall: close SSMS, then remove “SQL Sage” from Windows Apps & features (or re-run the installer's uninstall). Your local settings and audit log live under %LOCALAPPDATA%\SqlSage.

Download SQL Sage