culprit-sql-studio

<p align="center"> <img src="docs/images/logo.svg" width="88" height="88" alt="Culprit SQL Studio"> </p> <h1 align="center">Culprit SQL Studio</h1> <p align="center"> <b>Find out what's slowing your database down, and exactly how to fix it.</b> </p> <p align="center"> A fast desktop app and CLI for SQL Server, PostgreSQL, MySQL, MariaDB and SQLite, on macOS, Linux and Windows.<br> Plain-language answers for people. Safe, structured access for coding agents. </p> <p align="center"> <img alt="SQL Server" src="https://img.shields.io/badge/SQL%20Server-CC2927?style=flat-square&logo=microsoftsqlserver&logoColor=white"> <img alt="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-336791?style=flat-square&logo=postgresql&logoColor=white"> <img alt="MySQL" src="https://img.shields.io/badge/MySQL-00758F?style=flat-square&logo=mysql&logoColor=white"> <img alt="MariaDB" src="https://img.shields.io/badge/MariaDB-003545?style=flat-square&logo=mariadb&logoColor=white"> <img alt="SQLite" src="https://img.shields.io/badge/SQLite-003B57?style=flat-square&logo=sqlite&logoColor=white"> <img alt="MCP server" src="https://img.shields.io/badge/MCP-ready-1b1a18?style=flat-square"> <img alt="macOS, Linux and Windows" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-1b1a18?style=flat-square"> <a href="https://github.com/cristipufu/culprit-sql-studio/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cristipufu/culprit-sql-studio/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-ffcf33?style=flat-square"></a> </p> <p align="center"> <a href="https://culpritsql.com"><b>culpritsql.com</b></a> · <a href="#why-culprit">Why Culprit</a> · <a href="#what-you-get">What you get</a> · <a href="#built-for-coding-agents">Coding agents</a> · <a href="#safe-on-production">Safety</a> · <a href="#get-started">Get started</a> · <a href="docs/guide.md">Guide</a> </p> <br> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/dashboard-dark.png"> <img alt="Culprit's dashboard for a SQL Server database: database time over five hours with a plan change, a deploy mark and a throttling period on its timeline, 31 findings ranked by severity, the top queries, where time goes, a blocked session right now, health, deadlocks, index advice and plan insights" src="docs/images/dashboard-light.png"> </picture> <br>

Why Culprit

When a database gets slow, someone has to dig through Query Store, wait statistics, plan caches and execution plans to find out why. That takes an expert, an afternoon and a handful of tools that each show a piece of the picture.

Culprit does the digging in seconds. It reads the statistics your database already keeps, works out where the time goes, and tells you in one sentence what is wrong, what it costs and what to change:

Repeats its read of order_items 1.5M times, once per row of order_items.<br> 27% of database time, and it times out on every run · Fix: the query forces a loop join; remove the hint and let the optimizer choose · Verify: run it with actual rows: a hash join, or far fewer executions of order_items.

<table> <tr> <td width="33%" valign="top">

🎯 Answers, not raw numbers

Every finding is ranked by its share of database time and comes with the evidence, a production-safe fix and a way to prove it worked.

</td> <td width="33%" valign="top">

🛡️ Safe on production

Scans read statistics only and never run your queries. Anything that would change data on a production database asks first.

</td> <td width="33%" valign="top">

🤖 Built for coding agents

An MCP server, JSON output everywhere and per-connection permissions let Claude Code, Cursor or Codex investigate with you. Every call is approved and audited.

</td> </tr> <tr> <td valign="top">

⚡ Fast and light

A 14 MB app that opens in under a second and shows the last report instantly while a fresh scan runs in the background.

</td> <td valign="top">

🧭 One tool, five engines

The same views, wording and workflow on SQL Server, PostgreSQL, MySQL, MariaDB and SQLite. When an engine can't show something, Culprit says why in one sentence.

</td> <td valign="top">

🔌 Open and pluggable

Add your own checks or database engines without forking. The app, the CLI and the agent tools share one Rust core.

</td> </tr> </table>

What you get

Findings you can act on

52 checks look for what actually costs time: runaway loops in plans, plan regressions, missing and unused indexes, N+1 query loops, type mismatches that block indexes, parameter-sensitive plans, queries that fail or time out, spills to disk, hot rows, statements that lock a whole table, slow storage, connection storms, replication lag, stale statistics, risky settings and more. Each finding names the queries involved, shows their share of database time, and ends with a fix you copy (Culprit never applies it for you) and a way to verify it.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/findings-dark.png"> <img alt="A finding: a query repeats its read of order_items 1.5 million times because it forces a loop join, with its share of database time, the query as evidence, the expensive plan step, the fix and how to verify it" src="docs/images/findings-light.png"> </picture>

Plans that explain themselves

Every captured plan comes with insights in plain words ("repeats its read of order_items 1.5M times, once per row"), a diagram that shows where the cost goes, and the operator's details one click away. 33 rules cover SQL Server, PostgreSQL, MySQL and SQLite plans. Measure a run safely (writes are rolled back), and on SQL Server see the last actual plan without re-running the query or watch a long query's progress step by step.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/queries-dark.png"> <img alt="The Queries view: queries ranked by database time with trend sparklines, and the selected query's plan diagram, where a nested loop reading order_items 1.5 million times does 94% of the work" src="docs/images/queries-light.png"> </picture>

"What changed?" in one drag

Drag across the database-time chart to compare two periods. Culprit lists what got slower, what's new and what improved, and says why: "Got 293× slower at 5:00 PM, when SQL Server switched from plan 163 to plan 198." It also lines regressions up with everything else that changed around them: a dropped index, a new setting, a restart, a deploy your pipeline marked with culprit mark, or the cloud throttling the server (Amazon RDS CPU credits running out, Azure tier limits), read with your own aws or az sign-in.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/what-changed-dark.png"> <img alt="What changed between two periods: one query got 293 times slower after a plan switch, seven new queries, with database time and runs before and after" src="docs/images/what-changed-light.png"> </picture>

Compare any two plans

Paste or drop a plan from anywhere (SSMS .sqlplan, PostgreSQL EXPLAIN, MySQL EXPLAIN FORMAT=JSON) and compare it with another. The headline says what matters: "Plan 13 is estimated 3.5K× more expensive because it scans orders where Plan 12 seeks orders_status_created_idx." Every changed step is marked in both diagrams.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/compare-dark.png"> <img alt="Two PostgreSQL plans side by side, with a one-sentence explanation of why one costs 3,500 times more and a list of the changed steps" src="docs/images/compare-light.png"> </picture>

Who is blocking whom, right now

Live sessions turn a wall of lock waits into one sentence and a tree: which session holds everyone up, why (here: a transaction left open by the application) and who waits behind it. Deadlocks get the same treatment, with the pattern named and the fix spelled out.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/live-dark.png"> <img alt="Live sessions: session 71 has been idle in an open transaction for 22 seconds and two sessions wait behind it, shown as a blocking tree" src="docs/images/live-light.png"> </picture>

And everything else, done properly

| Feature | What it does | |---|---| | Index advisor | Indexes to add, ranked by the database time of the queries that need them, plus duplicate, overlapping and unused indexes to clean up, with what each costs on writes | | Where time goes | Wait statistics in plain words, traced back to the queries behind them, with a live sample to compare against the usual mix | | Health signals | Memory, compiles, connections, row locks, storage latency per file, replication lag and cloud limits, each graded with a one-line takeaway | | SQL editor | Tabs, autocomplete for schemas, tables and columns, saved queries, estimated and measured plans. Reads run read-only; production changes ask first | | Schema explorer | Tables, sizes, indexes and how each index is used, plus drift between two environments with the SQL to close the gap | | Connections | Paste any connection string, discover Azure and AWS databases with your existing CLI login, or import from Azure Data Studio, VS Code, DBeaver and DataGrip. Passwords stay in your OS keychain | | Keyboard first | A command palette (⌘K) for every view, finding, query and action |

Built for coding agents

Culprit is designed to be driven by an agent as comfortably as by a person. culprit mcp serves 25 tools over the Model Context Protocol (dashboard, findings, plans, insights, what changed, blocking, waits, index advice, verify and more), every CLI command prints JSON when piped, and finding ids are stable, so an agent can find a problem, fix the code and prove the fix worked.

claude mcp add culprit -- culprit mcp   # Claude Code; Cursor and Codex take the same command
culprit agent init                      # teach agents in this repository to use Culprit

You decide what agents may do, per connection: nothing, read statistics and plans (the default), or run read-only queries that you approve one by one. Approval shows the exact statement and what Culprit guarantees about it, and every tool call lands in a local audit log.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/agent-approval-dark.png"> <img alt="An approval dialog: claude-code wants to run a SELECT on a development connection; checked as read-only, rolled back, capped at 200 rows and 30 seconds; Deny or Run once" src="docs/images/agent-approval-light.png" width="720"> </picture> </p>

Safe on production

• Read-only by design. Scans read statistics and catalog views only, with short lock timeouts. Estimated plans never execute anything.
• Planning never lends your privileges. On PostgreSQL the planner runs the functions a statement reaches, so a login with more than pg_monitor plans only the statements it ran itself, and none while functions other roles wrote are in reach. Every plan is made in a read-only transaction that is rolled back.
• Production is guarded. Statements Culprit can prove only read run in a read-only transaction. Anything else on a production connection needs an explicit confirmation that says what it will do, and destructive statements need the connection's name typed.
• Fixes are suggestions. Every fix is shown and copied, never applied, and uses online or concurrent operations where the server supports them.
• Secrets stay put. Passwords live in the OS keychain, Entra ID uses your az login, and nothing about your servers leaves your machine. Exports redact literal values by default.
• Agents get least privilege. Off, statistics only, or approved read-only queries, per conn