Skip to content

Instantly share code, notes, and snippets.

@tshego3

tshego3/T-SQL Debugger in SSMS & VS.md

Last active March 12, 2026 10:20
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tshego3/e0552c661739e7ab8206e8e0fe9a2fec to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tshego3/e0552c661739e7ab8206e8e0fe9a2fec to your computer and use it in GitHub Desktop.
Download ZIP
T-SQL Debugger in Server Management Studio (SSMS) and SQL Server Data Tools (SSDT) for Visual Studio
Raw
T-SQL Debugger in SSMS & VS.md

Transact-SQL debugger

Transact-SQL (T-SQL) debugger in SQL Server Management Studio (SSMS)

Run the Transact-SQL debugger

To use the Transact-SQL (T-SQL) debugger in SQL Server Management Studio (SSMS), you can follow the steps below. This process allows you to set breakpoints, step through your T-SQL code, and inspect variables during execution, which is helpful for debugging complex stored procedures or scripts.

Prerequisites

  1. SQL Server Management Studio (SSMS): You need to have SSMS installed. Make sure you have the appropriate version that supports the debugger.

  2. Permissions: You must have the necessary permissions to execute and debug stored procedures and other T-SQL code. Generally, you'll need ALTER and EXECUTE permissions on the object you're debugging.

  3. SQL Server Instance: The SQL Server instance you're connecting to must support debugging. This typically applies to versions like SQL Server 2005 and higher.

Guide to Using the T-SQL Debugger in SSMS

1. Open SQL Server Management Studio (SSMS)

Launch SSMS and connect to your SQL Server instance.

2. Enable Debugging (Optional)

If debugging is not enabled, you might need to enable it:

  • Go to Tools > Options.
  • In the Options dialog, navigate to Query Execution > SQL Server > Advanced.
  • Ensure that the option Enable Transact-SQL Debugging is checked.

3. Set Up Your Script

Open the T-SQL script (like a stored procedure, function, or query) that you want to debug.

Example:

CREATE PROCEDURE MyProcedure
AS
BEGIN
    DECLARE @counter INT = 0;
    -- GO
    WHILE @counter < 10
    BEGIN
        PRINT @counter;
        SET @counter = @counter + 1;
    END
END;
  • Alternatively, you can debug an existing stored procedure or script.

4. Set Breakpoints

  • In the Query Editor, find the line of code where you want to set a breakpoint.
  • Click in the left margin next to the line number, or press F9 while the cursor is on the line where you want the breakpoint. A red circle will appear, indicating a breakpoint.

Breakpoints are useful to stop execution at certain points in your code so that you can inspect variable values and control flow.

5. Start Debugging

To start debugging:

  • Click the "Debug" button (green play button with a bug icon) in the SSMS toolbar, or press Alt + F5.
  • Alternatively, you can right-click in the Query Editor and choose Debug.

When you start debugging, SSMS will execute the T-SQL code. Execution will pause when it hits a breakpoint.

6. Step Through Code

Once the debugger has paused at a breakpoint, you can control the execution flow using the following options:

  • Step Into (F11): Steps into the next line of code or a stored procedure call.
  • Step Over (F10): Steps over a stored procedure call or block of code, moving to the next line in the current scope.
  • Step Out (Shift + F11): Steps out of the current procedure or batch, returning to the calling code.
  • Run to Cursor (Ctrl + F10): Runs the script to the location where the cursor is placed, skipping any breakpoints in between.

7. Inspect Variables and Results

While paused at a breakpoint, you can inspect variables and the result set:

  • Locals Window: This shows the current values of variables within the scope of your code. Go to Debug > Windows > Locals.
  • Watch Window: You can add specific variables or expressions to watch their values. Go to Debug > Windows > Watch.
  • Immediate Window: Allows you to execute T-SQL commands while debugging and see results immediately.

You can also hover over variables in the code to see their current values.

8. Stop Debugging

To stop the debugging session, click the Stop Debugging button (red square in the toolbar) or press Shift + F5.

9. Additional Options

  • Breakpoints Management: You can manage your breakpoints using the Breakpoints window. Access this by going to Debug > Windows > Breakpoints. From there, you can enable, disable, or delete breakpoints.
  • Debugging Stored Procedures: If you're debugging a stored procedure, you can set breakpoints in the procedure body, and use Step Into to enter the procedure as it is called.
Transact-SQL (T-SQL) debugger in SQL Server Data Tools (SSDT) for Visual Studio

Install SQL Server Data Tools (SSDT) for Visual Studio

To use the Transact-SQL (T-SQL) debugger in SQL Server Data Tools (SSDT) for Visual Studio, follow these steps to set it up and run T-SQL scripts in debug mode. The T-SQL debugger allows you to step through your SQL code, set breakpoints, and inspect variables and values during execution, which is particularly useful when you're troubleshooting complex stored procedures, functions, or scripts.

Prerequisites:

  1. SQL Server: You need to have access to a SQL Server instance where the SQL scripts will run.
  2. SQL Server Data Tools (SSDT): This is a Visual Studio extension that provides the tools for developing SQL Server databases, including T-SQL debugging capabilities.
  3. Visual Studio: Make sure you're using a version of Visual Studio that supports SSDT. SSDT is typically available in Visual Studio 2017 and later.

Steps to Use the T-SQL Debugger in SSDT for Visual Studio:

1. Install SQL Server Data Tools (SSDT)

  • If you haven’t already, you need to install SQL Server Data Tools. This can be done from the Visual Studio Installer or by downloading it directly from Microsoft.

To Install SSDT via Visual Studio Installer:

  • Open the Visual Studio Installer.
  • Select Modify on your installed version of Visual Studio.
  • Under Workloads, select Data storage and processing.
  • Click Modify to install SSDT.

2. Open Your SQL Project in Visual Studio

  • Launch Visual Studio.
  • Create or open an SQL Server Database Project (which typically contains T-SQL scripts, like stored procedures, functions, etc.).
  • You can also open a regular SQL file (ending in .sql) that you want to debug.

3. Configure Your SQL Server Connection

  • In the Server Explorer window, right-click on Data Connections and select Add Connection.
  • Provide the necessary connection details for the SQL Server instance that you want to debug against.
  • Make sure you have permission to execute the scripts on this SQL Server.

4. Set Breakpoints in Your T-SQL Script

  • Open the T-SQL script (e.g., a stored procedure or query) that you want to debug.
  • Set breakpoints in the code by clicking on the left margin next to the line where you want to pause execution (or press F9 with the cursor on the line where you want the breakpoint).

Tip: You can set multiple breakpoints in different locations within your code.

5. Set the Correct Target Platform

  • Important: If you encounter the error Deploy72002: A project which specifies SQL Server 2022 or Azure SQL Database Managed Instance as the target platform cannot be published to SQL Server 2019, you’ll need to adjust your project’s target platform.
  • To resolve this, open your project properties, go to the Project Settings tab, and set the Target Platform to SQL Server 2019 (or the correct version you’re working with).

6. Start Debugging

  • To start debugging, click on Debug in the top menu, then select Start Debugging (or press Alt + F5).
  • Alternatively, you can select Execute with Debugger from the context menu. This will deploy the script to your SQL Server and attach the debugger.

7. Control the Debugging Process

Once your code hits a breakpoint, you can control the debugging flow:

  • Step Into (F11): Step into the next line of code or into a called function/procedure.
  • Step Over (F10): Step over the next line of code, but if it calls another procedure or function, it will execute it without stepping into it.
  • Step Out (Shift + F11): Step out of the current procedure and back to the caller.
  • Continue (F5): Resume execution until the next breakpoint is hit or the script finishes.

8. Watch Variables and Inspect Values

  • Locals Window: Shows local variables and their values.
  • Watch Window: Allows you to add specific variables or expressions to watch as you step through the code.
  • Call Stack: Displays the call stack of the current execution thread, which is useful to see the sequence of function calls leading up to the current line.
  • Immediate Window: Allows you to run T-SQL statements and inspect values or call functions/procedures manually while debugging.

9. Handle Errors and Troubleshooting

  • If your code encounters an error or doesn’t behave as expected, you can use the Error List window to view error messages and troubleshoot the issues.
  • Check the Output window for more detailed logs on what’s happening during the execution of your script.

10. End Debugging

  • When you’re done, you can stop the debugger by selecting Debug > Stop Debugging from the menu, or pressing Shift + F5.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment