SQL Visual Debugger

Why did your SQL query return these rows?

Most SQL tools show you the final result. That is useful, but it does not show which rows came from FROM, which rows disappeared in WHERE, how a JOIN duplicated rows, or what changed after GROUP BY, HAVING, DISTINCT, ORDER BY, and LIMIT.

SQL Visual Debugger turns supported read-only SELECT queries into a step-by-step visual walkthrough inside VS Code, so you can inspect the intermediate result after each stage instead of guessing from the final output.

It is built for developers, students, analysts, and anyone who wants to understand how a query actually transforms data.

Supported local databases: MySQL, PostgreSQL, SQL Server, and SQLite.

Want to see the debugger before connecting a database? Run SQL Visual Debugger: Try Demo Query from the Command Palette.

How It Works

1. Open a .sql file in VS Code.
2. Select a supported SELECT query, or place your cursor inside the query.
3. Right-click and choose SQL Visual Debugger: Debug Query.
4. Choose your local database type and enter the connection details.
5. Step through the result as each SQL clause changes the rows.

Passwords are used for the current VS Code session only and are not saved.

Default local connection paths:

• MySQL: localhost, port 3306, user root
• PostgreSQL: localhost, port 5432, user postgres
• SQL Server: local server name with Windows Authentication or SQL Server Authentication
• SQLite: absolute path to a local .db or .sqlite file

See What The JOIN Did

JOIN bugs are easy to miss because the final result may look valid while rows were duplicated, removed, or matched differently than expected.

For supported joins, SQL Visual Debugger shows both sides of the join, the join condition, the row-count change, and the joined result. You can click join-key rows to inspect how matches were produced.

Understand GROUP BY

Aggregations can hide the rows that created each result.

For supported grouped queries, the debugger shows the grouped output and lets you inspect the source rows that contributed to each group. This makes COUNT, SUM, AVG, and other grouped calculations easier to reason about.

See What WHERE Removed

Filters are easier to trust when you can see the before and after.

For supported WHERE and HAVING clauses, the debugger shows which rows or groups survived and which were removed.

What It Helps You Understand

• FROM - see the starting row set before later steps change it
• JOIN - understand how rows matched across tables and why row counts changed
• WHERE - see which rows were filtered out and why
• GROUP BY - see how rows were grouped and which rows contributed to each group
• HAVING - see which grouped rows were removed after aggregation
• SELECT - understand the final projected columns and derived values
• DISTINCT - see which duplicate rows were removed
• ORDER BY - see how the final result was sorted
• LIMIT / TOP - see where the result was truncated when supported by the current dialect
• CASE - inspect why supported conditional output values were chosen
• window functions - inspect supported ranking and aggregate window calculations
• non-recursive WITH CTEs - follow supported CTE flows
• supported subqueries - inspect supported FROM, WHERE IN, and scalar WHERE subqueries

Supported Today

SQL Visual Debugger currently supports local debugging flows for MySQL, PostgreSQL, SQL Server, and SQLite built around:

• read-only SELECT queries
• supported non-recursive WITH queries
• FROM
• JOIN
• WHERE
• GROUP BY
• HAVING
• SELECT
• DISTINCT
• ORDER BY
• LIMIT / supported TOP-style limiting
• simple FROM (...) alias subqueries
• supported WHERE IN (...) subqueries
• supported scalar subqueries in WHERE
• supported CASE expressions
• supported window functions in SELECT
• simple uncorrelated aggregate scalar subqueries in the SELECT list

Current Boundaries

SQL Visual Debugger is intentionally focused. When a query is outside the supported visual-debugging shape, the extension should stop with a clear message instead of pretending to debug it.

Currently unsupported or limited areas include:

• non-SELECT statements such as INSERT, UPDATE, DELETE, DROP, and ALTER
• UNION
• recursive CTEs
• remote database hosts
• non-equality join conditions
• CROSS JOIN, NATURAL JOIN, and FULL OUTER JOIN
• many advanced subquery shapes
• correlated scalar subqueries in the SELECT list
• grouped scalar subqueries in the SELECT list
• some advanced window-function syntax
• SQL Server TOP with GROUP BY is a known debugger limitation

PostgreSQL note: if your tables are inside a schema other than public, use schema-qualified names such as schema_name.orders.

SQLite note: SQLite connections use a local absolute file path. Network shares and relative paths are intentionally rejected.

Safety And Trust

SQL Visual Debugger is built for read-only debugging.

It:

• runs supported read-only SELECT and WITH query shapes
• blocks non-read-only SQL before execution
• blocks unsupported query shapes instead of guessing
• uses local database connections only
• keeps passwords only in session memory
• clears cached passwords after access-denied failures so the next attempt prompts again

This is not a general-purpose SQL runner. It is a focused debugger for supported SQL query analysis.

Telemetry And Privacy

SQL Visual Debugger collects anonymous product telemetry to improve reliability and prioritize future support.

Telemetry may include:

• extension version
• anonymous install ID
• debugger command usage
• successful, failed, rejected, and unsupported debug attempts
• safe query-shape flags such as has_join, has_group_by, has_distinct, or has_window_function
• query length bucket, such as 100-499 characters
• interactions with visual explanation features, such as opening DISTINCT details or clicking JOIN rows
• safe error categories, such as unsupported_syntax or a database error code

Telemetry never includes:

• SQL query text
• table, column, schema, or database names
• database credentials
• database hostnames or IP addresses
• query result data
• file paths
• location fields such as city, country, latitude, or longitude

Telemetry respects VS Code's global telemetry setting and can also be disabled from the Command Palette with:

SQL Visual Debugger: Disable Telemetry

Or by setting:

"sqlVisualDebugger.telemetry.enabled": false