Skip to content
Back to search

PerformanceStudio

Free, open-source SQL Server execution plan analyzer — cross-platform GUI + CLI with 30 analysis rules, missing index detection, SSMS extension. Built-in MCP server for AI-assisted plan review.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/erikdarlingdata/PerformanceStudio with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/erikdarlingdata/PerformanceStudio'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/erikdarlingdata--performancestudio/badge.svg)](/listings/erikdarlingdata--performancestudio)

HTML

<a href="/listings/erikdarlingdata--performancestudio"><img src="/api/listings/erikdarlingdata--performancestudio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Analyze an existing .sqlplan file

If you already have a `.sqlplan` file (saved from SSMS, Azure Data Studio, or another tool):

# JSON output (default) — full operator tree, suitable for automation
planview analyze my_query.sqlplan

# Human-readable text output
planview analyze my_query.sqlplan --output text

# Text output, warnings and missing indexes only (skip operator tree)
planview analyze my_query.sqlplan --output text --warnings-only

Explore plans interactively (Repl pilot)

Run `planview repl` to start a long-lived plan-exploration session. Zero arguments and the existing `analyze`, `query-store`, and `credential` commands continue to use the legacy System.CommandLine graph.

planview repl
> open slow-query.sqlplan
[plan slow-query-<opaque-id>]> summary
[plan slow-query-<opaque-id>]> warnings --severity critical
[plan slow-query-<opaque-id>]> operators --top 10
[plan slow-query-<opaque-id>]> missing-indexes --json
[plan slow-query-<opaque-id>]> close

The same graph also works in one-shot and MCP modes:

planview plan open slow-query.sqlplan --json --no-logo
planview repl                         # explicit interactive alias
planview mcp serve                    # stdio MCP server generated from the graph

Bare `planview` preserves the legacy System.CommandLine behavior. Interactive exploration is entered only through `planview repl`; scripts can use explicit legacy or one-shot `plan` commands.

The pilot uses the stable `Repl` `0.11.0` release. Loaded plans live only for the lifetime of the process; `open` and `close` change only that in-memory catalog and never write the source plan. MCP `plan_open` validates and reads the same opened file handle inside client roots, accepts only `.sqlplan` files, and uses the server launch directory only when native roots are unsupported and no soft roots exist. Advertised empty roots deny access. MCP and local mode share the 16 MiB file/2-concurrent-open/32-session resource limits. See [`docs/repl-pilot.md`](docs/repl-pilot.md) for architecture, security, and compatibility notes.

Capture and analyze plans from a live server

Connect to a SQL Server instance, run queries, and capture their execution plans automatically.

**Quickest way** — pass credentials directly:

# Capture an actual execution plan (the query WILL run)
planview analyze --server sql2022 --database AdventureWorks \
    --login sa --password YourPassword \
    --query "SELECT * FROM Sales.SalesOrderHeader WHERE OrderDate > '2024-01-01'" \
    --trust-cert --output-dir ./results/

# Capture an estimated plan (safe for production — query is NOT executed)
planview analyze --server sql2022 --database AdventureWorks \
    --login sa --password YourPassword \
    --query "SELECT * FROM Sales.SalesOrderHeader" \
    --estimated --trust-cert --output-dir ./results/

**Using a .env file** — drop a `.env` in your working directory to avoid repeating connection details:

# .env
PLANVIEW_SERVER=sql2022
PLANVIEW_DATABASE=AdventureWorks
PLANVIEW_LOGIN=sa
PLANVIEW_PASSWORD=YourPassword
PLANVIEW_TRUST_CERT=true

Then just run:

planview analyze --query "SELECT * FROM Sales.SalesOrderHeader"
planview analyze ./queries/ --output-dir ./results/

CLI arguments override `.env` values when both are provided.

When the `.env` file supplies a setting, the CLI prints one line to stderr. The line names the file and those settings, and it never shows their values:

Using settings from /work/.env: PLANVIEW_SERVER, PLANVIEW_TRUST_CERT

The CLI takes a setting from the file only when the setting has an effect:

- With no server from either place, `analyze` reads the plan file offline and takes nothing from the `.env` file. - `PLANVIEW_PASSWORD` is used only with a login.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 657 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Performance Studio
  2. <p align="center">
  3. <a href="https://github.com/erikdarlingdata/PerformanceStudio/stargazers"><img src="https://img.shields.io/github/stars/erikdarlingdata/PerformanceStudio?style=for-the-badge&logo=github&color=gold&logoColor=black" alt="GitHub Stars"></a>
  4. <a href="https://github.com/erikdarlingdata/PerformanceStudio/network/members"><img src="https://img.shields.io/github/forks/erikdarlingdata/PerformanceStudio?style=for-the-badge&logo=github" alt="GitHub Forks"></a>
  5. <a href="https://github.com/erikdarlingdata/PerformanceStudio/blob/main/LICENSE"><img src="https://img.shields.io/github/license/erikdarlingdata/PerformanceStudio?style=for-the-badge" alt="License: MIT"></a>
  6. <a href="https://github.com/erikdarlingdata/PerformanceStudio/releases/latest"><img src="https://img.shields.io/github/v/release/erikdarlingdata/PerformanceStudio?style=for-the-badge" alt="Latest Release"></a>
  7. <a href="https://github.com/erikdarlingdata/PerformanceStudio/issues"><img src="https://img.shields.io/github/issues/erikdarlingdata/PerformanceStudio?style=for-the-badge" alt="Open Issues"></a>
  8. <a href="https://github.com/erikdarlingdata/PerformanceStudio/commits/main"><img src="https://img.shields.io/github/last-commit/erikdarlingdata/PerformanceStudio?style=for-the-badge" alt="Last Commit"></a>
  9. <a href="https://github.com/erikdarlingdata/PerformanceStudio/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/erikdarlingdata/PerformanceStudio/ci.yml?style=for-the-badge&label=CI" alt="CI"></a>
  10. </p>
  11. <p align="center">
  12. <a href="https://x.com/erikdarlingdata"><img src="https://img.shields.io/badge/Follow_%40ErikDarlingData-black?style=for-the-badge&logo=x&logoColor=white" alt="Follow @ErikDarlingData on X"></a>
  13. <a href="https://www.youtube.com/@ErikDarlingData"><img src="https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube Subscribe"></a>
  14. <a href="https://www.linkedin.com/in/erik-darling-data/"><img src="https://img.shields.io/badge/LinkedIn-Connect-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn Connect"></a>
  15. <a href="https://erikdarling.com"><img src="https://img.shields.io/badge/Blog-erikdarling.com-FF6B35?style=for-the-badge&logo=wordpress&logoColor=white" alt="Blog"></a>
  16. </p>
  17. A cross-platform SQL Server execution plan analyzer with built-in MCP server for AI-assisted analysis. Parses `.sqlplan` XML, identifies performance problems, suggests missing indexes, and provides actionable warnings — from the command line or a desktop GUI.
  18. Built for developers and DBAs who want fast, automated plan analysis without clicking through SSMS.
  19. ## Screenshots
  20. ### Query Editor
  21. Write queries with syntax highlighting and SQL keyword completion, connect to any SQL Server, and capture plans with one click.
  22. ![Query Editor](screenshots/Query%20Editor.png)
  23. ### Actual Execution Plan with Plan Insights
  24. Graphical plan tree with SSMS-style operator icons, cost percentages, row counts, and warning badges. The Plan Insights panel shows runtime summary, missing indexes, parameters, and wait stats at a glance.
  25. ![Actual Execution Plan](screenshots/Actual%20Execution%20Plan.png)
  26. ### Multi-Statement Navigation
  27. Navigate stored procedures and batches with multiple statements. Click any statement in the grid to jump to its plan. Plan Insights shows parameters with compiled vs runtime values.
  28. ![Navigate Stored Procedure Statements and Plans](screenshots/Navigate%20Stored%20Procedure%20Statements%20and%20Plans.png)
  29. ### Operator Tooltip and Properties
  30. Hover any operator for a grouped tooltip with costs, rows, timing, and parallelism. Click for the full properties panel, which has a filter box and folds per-thread stats into one expander per section instead of hundreds of rows.
  31. ![Operator Tooltip](screenshots/Actual%20Execution%20Plan%20With%20Warning%20Tool%20Tip.png)
  32. ![Operator Properties](screenshots/Operator%20Properties.png)
  33. ### Advice for Humans
  34. Severity-scored cards for each statement: the warnings that fired, wait stats, memory grant, and missing indexes. Copy to clipboard gives you the plain-text version to paste into a ticket.
  35. ![Advice for Humans](screenshots/Advice%20For%20Humans.png)
  36. ### Plan Comparison
  37. A real metric diff. Each statement is scored as regressed or improved, every metric carries its own delta chip, and the direction that counts as better is declared per metric rather than guessed from the sign.
  38. ![Plan Comparison](screenshots/Plan%20Comparison.png)
  39. ### Query Store Integration
  40. Fetch top queries by CPU, duration, logical reads, physical reads, writes, memory, or executions from Query Store and load their plans directly into the analyzer.
  41. ![Query Store Integration](screenshots/performance_studio_querystore_analysis_top_cpu_by_query_hash.png)
  42. ### Minimap and colored links by accuracy ratio divergence
  43. The minimap provides a high-level overview of the entire plan, allowing you to quickly navigate to areas of interest. Colored links between operators indicate accuracy ratio divergence, helping you identify where estimates are most off from actuals.
  44. ![Minimap and Colored Links](screenshots/minimap_and_planviewer_colored_actual_plan.png)
  45. ### MCP Integration
  46. Ask Claude Code to analyze loaded plans, identify warnings, suggest indexes, and compare plans — all through the built-in MCP server.
  47. ![MCP Integration](screenshots/MCP%20Integration.png)
  48. #### Compact output (GCF)
  49. Set `PLANVIEWER_OUTPUT_FORMAT=gcf` to have the MCP server return tool results as [GCF](https://gcformat.com) instead of JSON. GCF factors the repeated field names of record-heavy results (Query Store plan lists, connection and statement listings) into a single header, so a model spends roughly a third fewer tokens reading them. The substitution is opt-in and conservative: a result is re-encoded only when the wire is both smaller than the JSON and decodes back to the same value, so anything it cannot losslessly shrink is returned as the original JSON.
  50. ## What It Does
  51. Feed it a query plan and it tells you what's wrong:
  52. - **Large memory grants** — flags queries hoarding memory they don't use
  53. - **Row estimate mismatches** — finds operators where estimates are 10x+ off from actuals
  54. - **Missing indexes** — extracts SQL Server's index suggestions with ready-to-run CREATE statements
  55. - **Hash, sort, and exchange spills** — identifies operators spilling to TempDB with severity based on volume
  56. - **Parallel skew** — detects threads doing all the work while others sit idle
  57. - **Scan predicates** — warns when scans filter rows with residual predicates
  58. - **Key and RID lookups** — flags lookups back to the base table, distinguishes heaps from clustered indexes
  59. - **Late filters** — finds Filter operators discarding rows deep in the plan
  60. - **Nested loop concerns** — flags high-execution nested loops that might be better as hash joins
  61. - **Parameter sniffing** — compares compiled vs runtime parameter values
  62. - **Scalar UDFs** — warns about T-SQL and CLR scalar functions in execution paths
  63. - **Implicit conversions** — detects type mismatches, upgrades severity when a seek plan is prevented
  64. - **Anti-patterns** — OPTIMIZE FOR UNKNOWN, NOT IN with nullable columns, leading wildcards, function-wrapped predicates, and more
  65. Each warning includes severity (Info, Warning, or Critical), the operator node ID, and enough context to act on immediately.
  66. ## Prerequisites
  67. - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) (only needed to build from source — the pre-built binaries below are self-contained and require no SDK)
  68. - SQL Server instance (optional — only needed for live plan capture; file analysis works without one)
  69. - Docker (optional — macOS/Linux users can run SQL Server locally via Docker)
  70. ## Download
  71. Pre-built binaries are available on the [Releases](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest) page:
  72. | Platform | Download |
  73. |----------|----------|
  74. | Windows (x64) | [PerformanceStudio-win-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-win-x64.zip) |
  75. | macOS (Apple Silicon) | [PerformanceStudio-osx-arm64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-osx-arm64.zip) |
  76. | macOS (Intel) | [PerformanceStudio-osx-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-osx-x64.zip) |
  77. | Linux (x64) | [PerformanceStudio-linux-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-linux-x64.zip) |
  78. These are self-contained — no .NET SDK required. Extract the zip and run.
  79. **macOS note:** macOS may block the app because it isn't signed with an Apple Developer certificate. If you see a warning that the app "can't be opened," run this after extracting:
  80. ```bash
  81. xattr -cr PerformanceStudio.app
  82. ```
  83. Then open the app normally.
  84. ## Install the CLI
  85. The `planview` command is a .NET tool on nuget.org. It needs the .NET 10 runtime.
  86. ```bash
  87. dotnet tool install -g PerformanceStudio.Cli
  88. planview analyze --help
  89. ```
  90. For a CI pipeline, install into a folder and pin the version. A `dotnet-tools.json` manifest works too.
  91. ```bash
  92. dotnet tool install --tool-path ./tools PerformanceStudio.Cli --version <version>
  93. ./tools/planview analyze plan.sqlplan --compact
  94. ```
  95. To update:
  96. ```bash
  97. dotnet tool update -g PerformanceStudio.Cli
  98. ```
  99. ## Build from Source
  100. Clone and build:
  101. ```bash
  102. git clone https://github.com/erikdarlingdata/PerformanceStudio.git
  103. cd PerformanceStudio
  104. dotnet build
  105. ```
  106. To verify the build:
  107. ```bash
  108. dotnet test PlanViewer.sln
  109. dotnet run --project src/PlanViewer.Cli -- analyze --help
  110. ```
  111. ## Quick Start
  112. ### Analyze an existing .sqlplan file
  113. If you already have a `.sqlplan` file (saved from SSMS, Azure Data Studio, or another tool):
  114. ```bash
  115. # JSON output (default) — full operator tree, suitable for automation
  116. planview analyze my_query.sqlplan
  117. # Human-readable text output
  118. planview analyze my_query.sqlplan --output text
  119. # Text output, warnings and missing indexes only (skip operator tree)
  120. planview analyze my_query.sqlplan --output text --warnings-only
  121. ```
  122. ### Explore plans interactively (Repl pilot)
  123. Run `planview repl` to start a long-lived plan-exploration session. Zero arguments and the
  124. existing `analyze`, `query-store`, and `credential` commands continue to use the legacy
  125. System.CommandLine graph.
  126. ```text
  127. planview repl
  128. > open slow-query.sqlplan
  129. [plan slow-query-<opaque-id>]> summary
  130. [plan slow-query-<opaque-id>]> warnings --severity critical
  131. [plan slow-query-<opaque-id>]> operators --top 10
  132. [plan slow-query-<opaque-id>]> missing-indexes --json
  133. [plan slow-query-<opaque-id>]> close
  134. ```
  135. The same graph also works in one-shot and MCP modes:
  136. ```bash
  137. planview plan open slow-query.sqlplan --json --no-logo
  138. planview repl # explicit interactive alias
  139. planview mcp serve # stdio MCP server generated from the graph
  140. ```
  141. Bare `planview` preserves the legacy System.CommandLine behavior. Interactive exploration is
  142. entered only through `planview repl`; scripts can use explicit legacy or one-shot `plan` commands.
  143. The pilot uses the stable `Repl` `0.11.0` release. Loaded plans live only for the lifetime of
  144. the process; `open` and `close` change only that in-memory catalog and never write the
  145. source plan. MCP `plan_open` validates and reads the same opened file handle inside client
  146. roots, accepts only `.sqlplan` files, and uses the server launch directory only when native
  147. roots are unsupported and no soft roots exist. Advertised empty roots deny access. MCP and
  148. local mode share the 16 MiB file/2-concurrent-open/32-session resource limits. See
  149. [`docs/repl-pilot.md`](docs/repl-pilot.md) for architecture, security, and compatibility notes.
  150. ### Capture and analyze plans from a live server
  151. Connect to a SQL Server instance, run queries, and capture their execution plans automatically.
  152. **Quickest way** — pass credentials directly:
  153. ```bash
  154. # Capture an actual execution plan (the query WILL run)
  155. planview analyze --server sql2022 --database AdventureWorks \
  156. --login sa --password YourPassword \
  157. --query "SELECT * FROM Sales.SalesOrderHeader WHERE OrderDate > '2024-01-01'" \
  158. --trust-cert --output-dir ./results/
  159. # Capture an estimated plan (safe for production — query is NOT executed)
  160. planview analyze --server sql2022 --database AdventureWorks \
  161. --login sa --password YourPassword \
  162. --query "SELECT * FROM Sales.SalesOrderHeader" \
  163. --estimated --trust-cert --output-dir ./results/
  164. ```
  165. **Using a .env file** — drop a `.env` in your working directory to avoid repeating connection details:
  166. ```bash
  167. # .env
  168. PLANVIEW_SERVER=sql2022
  169. PLANVIEW_DATABASE=AdventureWorks
  170. PLANVIEW_LOGIN=sa
  171. PLANVIEW_PASSWORD=YourPassword
  172. PLANVIEW_TRUST_CERT=true
  173. ```
  174. Then just run:
  175. ```bash
  176. planview analyze --query "SELECT * FROM Sales.SalesOrderHeader"
  177. planview analyze ./queries/ --output-dir ./results/
  178. ```
  179. CLI arguments override `.env` values when both are provided.
  180. When the `.env` file supplies a setting, the CLI prints one line to stderr. The line names the file and those settings, and it never shows their values:
  181. ```text
  182. Using settings from /work/.env: PLANVIEW_SERVER, PLANVIEW_TRUST_CERT
  183. ```
  184. The CLI takes a setting from the file only when the setting has an effect:
  185. - With no server from either place, `analyze` reads the plan file offline and takes nothing from the `.env` file.
  186. - `PLANVIEW_PASSWORD` is used only with a login.
  187. If a `PLANVIEW_` value holds a control character, the CLI stops and names the setting. The CLI prints the server and database names later. A control character in them moves the cursor and erases text, such as the `Using settings` line.
  188. **Using the credential store** — for longer-term use, store credentials in your OS keychain:
  189. ```bash
  190. # Store credentials (once per server)
  191. planview credential add sql2022 --user sa
  192. # You'll be prompted for the password — it's stored in your OS credential store
  193. # Now connect without --login/--password
  194. planview analyze --server sql2022 --database AdventureWorks \
  195. --query "SELECT * FROM Sales.SalesOrderHeader" \
  196. --trust-cert --output-dir ./results/
  197. ```
  198. **Batch processing** a folder of .sql files:
  199. ```bash
  200. planview analyze ./queries/ --server sql2022 --database StackOverflow2013 \
  201. --login sa --password YourPassword \
  202. --trust-cert --output-dir ./results/
  203. ```
  204. Batch mode produces three files per query:
  205. - `query_name.sqlplan` — the raw execution plan XML (openable in SSMS or the Performance Studio GUI)
  206. - `query_name.analysis.json` — structured analysis with warnings, missing indexes, and operator tree
  207. - `query_name.analysis.txt` — human-readable text report
  208. ### Manage credentials
  209. ```bash
  210. planview credential add my-server --user sa # prompts for password
  211. planview credential add my-server --user sa -p pwd # non-interactive
  212. planview credential list # show stored credentials
  213. planview credential remove my-server # delete credential
  214. ```
  215. Credentials are stored in the OS credential store: Windows Credential Manager on Windows, Apple Keychain on macOS. Nothing is written to disk in plaintext. Linux has no credential store, so `planview credential` exits with an error there. Pass `--login` and `--password-stdin`, or put `PLANVIEW_LOGIN` and `PLANVIEW_PASSWORD` in a `.env` file.
  216. ## Example Output
  217. These examples were generated against StackOverflow2013 on SQL Server 2022. Source queries are in [`examples/queries/`](examples/queries/), plans and analysis in [`examples/output/`](examples/output/).
  218. ### Text output (`--output text`)
  219. ```
  220. Plan: 04_comment_heavy_posts.sqlplan
  221. SQL Server: 1.564 (build 16.0.4222.2)
  222. Statements: 1
  223. --- Statement 1: SELECT ---
  224. Query: SELECT p.Id, p.Title, p.Score, COUNT(c.Id) AS CommentCount
  225. FROM dbo.Posts AS p JOIN dbo.Comments AS c ON c.PostId = p.Id
  226. WHERE p.PostTypeId = 1 GROUP BY p.Id, p.Title, p.Score
  227. HAVING COUNT(c.Id) > 20 ORDER BY CommentCount DESC
  228. Estimated cost: 4069.8700
  229. DOP: 8
  230. Runtime: 4551ms elapsed, 15049ms CPU
  231. Memory grant: 8,022,664 KB granted, 2,514,944 KB used
  232. Warnings:
  233. [Critical] Large Memory Grant: Query granted 7835 MB of memory.
  234. Operator warnings:
  235. [Critical] Parallelism (Node 0): Estimated 1 rows, actual 2,889 (2889x underestimated).
  236. [Critical] Sort (Node 1): Estimated 1 rows, actual 2,889 (2889x underestimated).
  237. [Warning] Sort (Node 1): Thread 1 processed 100% of rows. Work is heavily skewed.
  238. [Warning] Filter (Node 2): Filter discards rows late in the plan.
  239. Missing indexes:
  240. StackOverflow2013.dbo.Posts (impact: 74%)
  241. CREATE NONCLUSTERED INDEX [IX_Posts_PostTypeId]
  242. ON dbo.Posts (PostTypeId) INCLUDE (Score, Title)
  243. StackOverflow2013.dbo.Comments (impact: 19%)
  244. CREATE NONCLUSTERED INDEX [IX_Comments_PostId]
  245. ON dbo.Comments (PostId)
  246. === Summary ===
  247. Warnings: 8 (4 critical)
  248. Missing indexes: 2
  249. Actual stats: yes
  250. Warning types: Filter Operator, Large Memory Grant, Parallel Skew,
  251. Row Estimate Mismatch, Scan With Predicate
  252. ```
  253. ### JSON output (default)
  254. The default JSON output includes the full operator tree, making it suitable for CI pipelines, LLM consumption, or further processing. See [`examples/output/`](examples/output/) for complete examples.
  255. ### Batch processing
  256. ```
  257. $ planview analyze ./examples/queries/ --server sql2022 \
  258. --database StackOverflow2013 --trust-cert --output-dir ./results/
  259. Capturing actual plans from sql2022/StackOverflow2013
  260. [1/5] 01_top_users_by_posts ... OK (1.8s)
  261. [2/5] 02_recent_questions ... OK (0.8s)
  262. [3/5] 03_unanswered_high_score ... OK (0.7s)
  263. [4/5] 04_comment_heavy_posts ... OK (4.7s)
  264. [5/5] 05_user_vote_summary ... OK (4.3s)
  265. Processed 5 files: 5 succeeded, 0 failed
  266. Output: ./results/
  267. ```
  268. ## Desktop GUI
  269. The Avalonia-based GUI renders execution plans visually with the same operator icons as SSMS. Open `.sqlplan` files via File > Open or drag-and-drop.
  270. Features:
  271. - Graphical plan tree with cost percentages and row counts
  272. - Warning badge on root node showing total warning count
  273. - Plan Insights panel — three-column view with runtime summary, missing indexes, and wait stats visualization
  274. - Zoom and pan (mouse wheel + middle-click drag)
  275. - Minimap for quick navigation of large plans
  276. - Color-coded links between operators based on accuracy ratio divergence (estimates vs actuals)
  277. - Click any operator to see full properties (30 sections)
  278. - Statement grid with sortable columns (cost, rows, DOP, warnings)
  279. - Tooltips on hover with key operator metrics
  280. - **Advice for Humans** — one-click text analysis report you can read or share
  281. - **Advice for Robots** — one-click JSON export designed for LLMs and automation
  282. - **Plan Comparison** — compare two plans side-by-side (cost, runtime, I/O, memory, wait stats)
  283. - **Copy Repro Script** — extracts parameters, SET options, and query text into a runnable `sp_executesql` script
  284. - **Get Actual Plan** — connect to a server and re-execute the query to capture runtime stats
  285. - **Query Store Analysis** — connect to a server and analyze top queries by CPU, duration, or reads
  286. - **Query History** — view a history of executed queries with their plans along the timeline and metrics from query store
  287. - **MCP Server** — built-in Model Context Protocol server for AI-assisted plan analysis (opt-in)
  288. - Dark theme
  289. ```bash
  290. dotnet run --project src/PlanViewer.App
  291. ```
  292. ## SSMS Extension
  293. A VSIX extension that adds **"Open in Performance Studio"** to the execution plan right-click context menu in SSMS 18-22.
  294. ### How it works
  295. 1. Right-click on any execution plan in SSMS
  296. 2. Click "Open in Performance Studio"
  297. 3. The extension extracts the plan XML via reflection and saves it to a temp file
  298. 4. Performance Studio opens with the plan loaded
  299. ### Installation
  300. 1. Download `PlanViewer.Ssms.vsix` and `InstallSsmsExtension.exe` from the [latest release](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest)
  301. 2. Place them in the same folder
  302. 3. Double-click `InstallSsmsExtension.exe` and approve the UAC prompt
  303. 4. The installer auto-detects SSMS 21 and/or SSMS 22 and installs into both
  304. 5. Restart SSMS to activate the extension
  305. Release builds are signed. A signed installer installs only a `PlanViewer.Ssms.vsix` that has the same signature, so use the two files from the same release. You can also double-click `PlanViewer.Ssms.vsix` to install the extension without the installer.
  306. ### First run
  307. On first use, if Performance Studio isn't found automatically, the extension will prompt you to locate `PlanViewer.App.exe`. The path is saved to the registry (`HKCU\SOFTWARE\DarlingData\SQLPerformanceStudio\InstallPath`) so you only need to do this once.
  308. The extension searches for the app in this order:
  309. 1. Registry key (set automatically after first browse)
  310. 2. Common install locations: `%LOCALAPPDATA%\PerformanceStudio\current\` (the release installer's folder), then older install folders under `%LOCALAPPDATA%\Programs\` and `Program Files`
  311. 3. System PATH
  312. ## MCP Server (LLM Integration)
  313. The desktop GUI includes an embedded [Model Context Protocol](https://modelcontextprotocol.io) server that exposes loaded execution plans and Query Store data to LLM clients like Claude Code and Cursor.
  314. ### Setup
  315. 1. Enable the MCP server in `~/.planview/settings.json`:
  316. ```json
  317. {
  318. "mcp_enabled": true,
  319. "mcp_port": 5152
  320. }
  321. ```
  322. 2. Register with Claude Code:
  323. ```
  324. claude mcp add --transport http --scope user performance-studio http://localhost:5152/
  325. ```
  326. 3. Open a new Claude Code session and ask questions like:
  327. - "What plans are loaded in the application?"
  328. - "Analyze the execution plan and tell me what's wrong"
  329. - "Are there any missing index suggestions?"
  330. - "Compare these two plans — which is better?"
  331. - "Fetch the top 10 queries by CPU from Query Store"
  332. ### Available Tools
  333. 13 tools for plan analysis and Query Store data:
  334. | Category | Tools |
  335. |---|---|
  336. | Discovery | `list_plans`, `get_connections` |
  337. | Plan Analysis | `analyze_plan`, `get_plan_summary`, `get_plan_warnings`, `get_missing_indexes`, `get_plan_parameters`, `get_expensive_operators`, `get_plan_xml`, `compare_plans`, `get_repro_script` |
  338. | Query Store | `check_query_store`, `get_query_store_top` |
  339. Plan analysis tools work on plans loaded in the app (via file open, paste, query execution, or Query Store fetch). Query Store tools use a built-in read-only DMV query — no arbitrary SQL can be executed.
  340. The MCP server binds to `localhost` only and does not accept remote connections. Disabled by default.
  341. ## Project Structure
  342. ```
  343. PerformanceStudio/
  344. ├── src/
  345. │ ├── PlanViewer.Core/ # Analysis engine (parser, 30 rules, layout)
  346. │ ├── PlanViewer.App/ # Avalonia desktop GUI
  347. │ ├── PlanViewer.Cli/ # CLI tool (planview command)
  348. │ ├── PlanViewer.Ssms/ # SSMS extension (.vsix, .NET Framework 4.7.2)
  349. │ └── PlanViewer.Ssms.Installer/ # SSMS extension installer (auto-detects SSMS 21/22)
  350. ├── tests/
  351. │ └── PlanViewer.Core.Tests/ # 37 xUnit tests with real .sqlplan fixtures
  352. ├── examples/
  353. │ ├── plans/ # Sample .sqlplan files for testing
  354. │ ├── queries/ # Sample .sql files
  355. │ └── output/ # Generated .sqlplan, .analysis.json, .txt
  356. └── PlanViewer.sln
  357. ```
  358. ## CLI Reference
  359. ### `planview analyze`
  360. ```
  361. Usage: planview analyze [<file>] [options]
  362. Arguments:
  363. <file> .sqlplan file, .sql file, or directory of .sql files
  364. Options:
  365. --stdin Read plan XML from stdin
  366. -o, --output <format> json (default), text, or both (with --server, both writes .json and .txt files)
  367. --compact Compact JSON (no indentation)
  368. --warnings-only Skip operator tree, only output warnings and indexes
  369. -s, --server <name> SQL Server name (matches credential store key)
  370. -d, --database <name> Database context for execution
  371. -q, --query <sql> Inline SQL text to execute
  372. --output-dir <path> Directory for output files
  373. --estimated Estimated plan only (query is NOT executed)
  374. --auth <type> windows, sql, or entra (default: auto-detect)
  375. --trust-cert Trust server certificate
  376. --timeout <seconds> Query timeout (default: 60)
  377. --login <name> SQL Server login (bypasses credential store)
  378. --password <password> SQL Server password (bypasses credential store)
  379. --config <path> Path to a .planview.json config file (overrides auto-discovery)
  380. ```
  381. ### `planview credential`
  382. ```
  383. planview credential add <server> --user <user> [-p <password>]
  384. planview credential list
  385. planview credential remove <server>
  386. ```
  387. On Linux, `planview credential` exits with an error. See [Platform Support](#platform-support).
  388. ### Configuration file (.planview.json)
  389. A `.planview.json` file changes what the analyzer reports. The CLI commands `analyze`, `query-store` and `repl` read it. The desktop app reads it each time it opens a plan. The MCP server does not read it and always uses the defaults.
  390. The file is looked for in this order, and the first one found wins:
  391. 1. The path given to `--config`. If that file does not exist, the command stops with an error.
  392. 2. `.planview.json` in the current directory.
  393. 3. `.planview.json` in your home directory.
  394. If none exists, the analyzer uses its defaults. The file is JSON. Comments and trailing commas are allowed.
  395. ```jsonc
  396. {
  397. "rules": {
  398. "disabled": [3],
  399. "severity_overrides": { "10": "Info" }
  400. },
  401. "suppressions": [
  402. {
  403. "query_hash": "0x00E1987CD1C28B4C",
  404. "rule": 10,
  405. "operator": "eventuous.Messages",
  406. "reason": "Library procedure. The library owns the clustered index."
  407. },
  408. {
  409. "query_hash": "00e1987cd1c28b4c",
  410. "type": "Implicit Conversion",
  411. "reason": "Accepted. A vendor fixes the column type."
  412. }
  413. ]
  414. }
  415. ```
  416. The `rules.disabled` list holds rule numbers. A disabled rule never runs.
  417. The `rules.severity_overrides` map gives a rule number a new severity. The allowed values are `Info`, `Warning` and `Critical`.
  418. The `suppressions` list marks single findings as accepted. Use it when a finding is correct but you cannot or will not act on it. A suppressed finding is not removed. It stays in the output with `"suppressed": true` and its reason. The text output tags it as `[suppressed: <reason>]` and the HTML output shows a `suppressed: <reason>` badge. A suppressed finding keeps its severity, including one set by `severity_overrides`.
  419. A suppressed finding does not count toward `total_warnings`, `critical_warnings` or `warning_types`. The summary reports it in `suppressed_warnings` instead. The same rule applies to the counts in the desktop app.
  420. Each suppression has these fields:
  421. | Field | Required | Meaning |
  422. |-------|----------|---------|
  423. | `query_hash` | Yes | The query hash of the statement. Leading `0x` is optional and case does not matter, so `0x00E1987CD1C28B4C` and `00e1987cd1c28b4c` are the same hash. The suppression applies to that statement only, including statements inside a stored procedure body. |
  424. | `rule` | One of `rule` or `type` | A rule number. It matches findings from that rule. It never matches a warning that SQL Server wrote into the plan, because no rule produced it. |
  425. | `type` | One of `rule` or `type` | A warning type, such as `Implicit Conversion`. The whole type must match and case does not matter. Use it for warnings that have no rule number. If you give both `rule` and `type`, both must match. |
  426. | `operator` | No | Text that must appear in the operator label. Case does not matter. Use the label from the `operator` field of the JSON output, such as `Key Lookup on eventuous.Messages (Node 1)`. A partial match works, so `eventuous.Messages` is enough. A finding on the statement as a whole has no operator, so a suppression that sets `operator` never matches it. |
  427. | `reason` | Yes | Why the finding is accepted. It must not be empty. |
  428. A suppression that is missing a field is an error. The command prints one line that names the file, for example `Suppression 2 in C:\work\team.json has no "reason".`, and exits with code 1. The number is the zero-based position in the list. The desktop app does not stop. It opens the plan with the defaults and shows the message in the toolbar.
  429. To find the `query_hash` of a statement, run `planview analyze` with JSON output and read `statements[].query_hash`. Each warning in the JSON also shows its `rule` number when a rule produced it, and its `operator` label when it belongs to an operator.
  430. ## Authentication
  431. There are three ways to authenticate, in order of precedence:
  432. 1. **`--login` / `--password`** — passed directly on the command line (or via `.env` file). Simplest for dev/test.
  433. 2. **Credential store** — stored in Windows Credential Manager or Apple Keychain via `planview credential add`. Best for repeated use.
  434. 3. **Windows Authentication** — used automatically when no SQL credentials are found. Requires a valid Kerberos ticket.
  435. Override the auto-detection with `--auth windows`, `--auth sql`, or `--auth entra`.
  436. **macOS note:** Windows Authentication does not work on macOS (no Kerberos ticket by default). Use `--login`/`--password`, the credential store, or `--auth entra` instead.
  437. ## Platform Support
  438. | Platform | GUI | CLI | Credential Store |
  439. |----------|-----|-----|-----------------|
  440. | Windows | Yes | Yes | Windows Credential Manager |
  441. | macOS | Yes | Yes | Apple Keychain |
  442. | Linux | Yes | Yes | None. Use `--login` with `--password-stdin`, or a `.env` file |
  443. ### macOS: SQL Server via Docker
  444. macOS users need a SQL Server instance to use the live capture features. The easiest path is Docker:
  445. ```bash
  446. docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourPassword123" \
  447. -p 1433:1433 --name sql_server \
  448. -d mcr.microsoft.com/mssql/server:2022-latest
  449. # Store the credential
  450. planview credential add localhost --user sa -p YourPassword123
  451. # Test connectivity
  452. planview analyze --server localhost --database master --trust-cert \
  453. --query "SELECT @@VERSION" -o text
  454. ```
  455. Always use `--trust-cert` with local Docker instances.
  456. ## Analysis Rules
  457. The analyzer runs 30 rules against each plan, covering:
  458. | Category | Rules |
  459. |----------|-------|
  460. | Memory | Large grants, grant vs used ratio, spills to TempDB (including exchange spills) |
  461. | Estimates | Row estimate mismatches (10x+), zero-row actuals, row goals |
  462. | Indexes | Missing index suggestions, key lookups, RID lookups, scan with residual predicates |
  463. | Parallelism | Serial plan reasons, thread skew, ineffective parallelism, DOP reporting |
  464. | Joins | Nested loop high executions, many-to-many merge join worktables |
  465. | Filters | Late filter operators with impact quantification, function-wrapped predicates |
  466. | Functions | Scalar UDF detection (T-SQL and CLR), UDF timing |
  467. | Parameters | Compiled vs runtime values, sniffing issue detection |
  468. | Patterns | Leading wildcards, implicit conversions (with seek plan severity upgrade), OPTIMIZE FOR UNKNOWN, NOT IN with nullable columns, OR expansion, CASE in predicates |
  469. | Compilation | High compile CPU, compile memory exceeded, early abort |
  470. | Objects | Table variables, table-valued functions, CTE multiple references, eager index spools, lazy spools, row count spools |
  471. | Operators | Operator self-time calculation with per-thread awareness for parallel plans |
  472. Rules can be disabled, have their severity overridden, or have single findings suppressed per statement via a `.planview.json` config file. See [Configuration file](#configuration-file-planviewjson).
  473. ## Sponsors
  474. <table>
  475. <tr>
  476. <td><a href="https://signpath.io"><img src="docs/signpath_logo.svg" alt="SignPath" width="40"></a></td>
  477. <td>Free code signing on Windows provided by <a href="https://signpath.io">SignPath.io</a>, certificate by <a href="https://signpath.org">SignPath Foundation</a></td>
  478. </tr>
  479. </table>
  480. ## License
  481. MIT — see [LICENSE](LICENSE).
  482. Execution plan operator icons are from Microsoft's [vscode-mssql](https://github.com/microsoft/vscode-mssql) extension (MIT). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.