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

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 CLI 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.

Explain a failed query

When a query fails, a single line appears at the top of that window — “SQL Sage: the query failed — Msg 207: Invalid column name …” — with an Explain error button (or right-click → Ask SQL Sage ▸ Explain last error). SQL Sage first checks the error against your database's catalog and shows what it can prove — for example “No column named 'CustomerNme' in dbo.Customers; closest existing column: dbo.Customers.CustomerName”, the foreign key behind a conflict, or the key columns of a duplicate — then the AI explains the cause and returns a fixed query. Values the server quotes in a message (a duplicate key, a value that failed to convert) are withheld before anything is shown or sent. On SQL Sage Free the catalog check works too; the AI explanation needs a license. No line in the window? Copy the error from the Messages tab and use Explain last error.

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. The queries SQL Sage runs or blocks — the AI's reads, the writes and DDL you confirm or cancel, Prove-It runs, and the F5 guard's warnings — are appended to a local, hash-chained JSONL log under %LOCALAPPDATA%\SqlSage\audit\, with server, database, login, classification, the SQL and the row count. Local-only, no network egress. On by default; switch it off with Audit SQL in the panel. Not logged: schema look-ups (table lists, column definitions), a few read-only diagnostics (wait stats, plan-cache top queries, active requests, deadlock history) and repository reads; the health check and Incident Mode are logged by name, without their SQL.
• 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 is Authenticode-signed and timestamped by LUMA SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ; SmartScreen may still warn while the newly published file builds download reputation. Click More info and check that Publisher shows that name (an unsigned file would read Unknown publisher), then Run anyway. To check the file itself, compare Get-FileHash SqlSageSetup.exe -Algorithm SHA256 with the SHA-256 published in the download section.

“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; its Download button opens the latest signed installer — close SSMS first, then run it (it replaces the previous build, and asks you to close SSMS if it is still running). Nothing is installed silently; switch the check off with Check for updates in the panel. Uninstall:

1. Close SSMS.
2. Open Windows Settings → Apps → Installed apps (Windows 10: Apps & features), find SQL Sage for SSMS 22 (publisher LumaSoft) and choose Uninstall. The same uninstaller is also at C:\Program Files\Microsoft SQL Server Management Studio 22\Release\Common7\IDE\Extensions\SqlSage\unins000.exe.
3. The uninstaller removes the extension files and refreshes SSMS's extension registration, so SSMS no longer loads SQL Sage.

Your own data is not deleted: settings, chat sessions, the audit log and the licence/trial files stay under %LOCALAPPDATA%\SqlSage. Delete that folder if you want them gone (it also removes your stored licence key).

AI usage not included: SQL Sage needs your own AI access (Claude Code on a paid Claude plan, the Codex CLI with a ChatGPT account, or your own Anthropic API key). See pricing

Download SQL Sage