The Debugger runs a PSQL block or a script one statement at a time. A run pauses at a breakpoint, at an exception or when asked. While it is paused, the values of the variables can be read, and the run goes on step by step or to the next pause. The Debugger is a window of its own, so it can sit on a second screen next to the document. It is available from release 28.0, as in [[Invantive Query Tool Multi-Platform/Debugger|Invantive Query Tool Multi-Platform]]. ![[20261009-qt-debugger-breakpoints.png]] ## Starting a Run The group "Actions" of the tab "General" of the ribbon holds the entries of the Debugger: - "Debug Statement at Cursor" runs the statement at the cursor under the Debugger, as "Execute" runs it. - "Debug All" (Alt+F5) runs all statements of the document, as "Execute All" does. - "Pause at Start" makes a run pause before its first statement. It is on by default. The Debugger window opens with the first run of a document of the window, and shows every following run. ## The Window The tool bar holds the commands of the run: - "Continue" (F5) runs until the next pause. - "Pause" (F8) pauses a running run at the next statement. - "Step Over" (F10) runs the current statement, including the procedures it calls. On the last line of a statement it pauses on the next statement of the script. - "Step Into" (F11) goes into a procedure or function which the statement calls. - "Step Out" (Shift+F11) runs to the end of the current procedure. - "Leave Loop" runs the rest of the current loop and pauses after it. - "Run to Cursor" (Ctrl+F10) runs to the line of the cursor in the source. - "Stop" (Shift+F5) ends the run. "Exceptions" chooses whether a run pauses at no exception, at an exception which no handler catches, or at every exception. The source is on the left, the side bar on the right and the "Debug Console" below. The yellow band above the source says why the run paused, in a sentence, and the yellow arrow beside the text marks the statement which runs next. The line below the band names the unit and where its text comes from. When the run steps into a procedure or function, also one created earlier in the session, the source shows its text with its own line numbers. The lines of the script are numbered as in the editor. ## Breakpoints A click in the margin left of the line numbers sets or removes a breakpoint on that line, and F9 does the same for the line of the cursor. The section "Breakpoints" of the side bar takes a breakpoint as text: `30`, `30 if l_n > 3`, or `unit` followed by the name of a procedure. A breakpoint typed for a line which already has one replaces it. The buttons below the list act on the selected breakpoint, as its context menu does: - "Disable Breakpoint" keeps the breakpoint without using it; "Enable Breakpoint" uses it again. - "Edit Condition..." pauses only when a condition is true, such as `l_change_pct > 25`. - "Hit Count..." pauses only at the given hit; 0 pauses at every hit. - "Log Message..." writes a message to the console instead of pausing. Expressions go between braces, such as `Project {r_pjt.pjt_code}`. - "Remove Breakpoint" deletes it. The glyph in the margin tells them apart: a red dot pauses, a hollow dot is disabled, a dot with two bars has a condition, a dot with `#` counts hits and a purple diamond is a log point. ## Values The section "Call Stack" lists the frames of the paused run; selecting a frame shows its line in the source and its variables in "Scope". A value which changed since the previous pause is red. At the end of the lines which ran in the current pass, the values they produced are shown. Resting the pointer on a name in the source shows its value in a tip, and "Data Tip" in the tool bar or Ctrl+I does the same for the name at the cursor. The tip of the row of a loop lists its columns. The text of the tip is repeated in the line below the band, where a screen reader finds it. A tip shows only what "Scope" holds, so it never runs a function. The section "Watch" takes an expression which is evaluated at every pause. Below it, a loop table keeps chosen variables for every pass of a loop: `9: r_pjt.pjt_code, l_change_pct` keeps two values for each pass of the loop on line 9, shown as a grid. ## Resource Use and Parallel Work The tab "Resource Use" beside the source lists for each unit and statement how often it ran, how long it took, its share of the run, and the time and memory of PSQL and SQL apart, with the number of I/O operations. The tab "Parallel Work" appears when a run starts workers, with a line per worker that shows its passes over time, and the locks, atomic values and buffered output which the workers share under "Between Workers". ## Coverage and Copy State With "Coverage" on in the tool bar, the run counts how often each line runs. A bar left of every line with a statement is green when the line ran and grey when it never did. The help text of the button gives the counts, for a screen reader. Counting makes the run slower, and it starts when the button is pressed. "Copy State" puts the state of the paused run on the clipboard as JSON: where it paused and why, and the call stack with the variables of every frame. Values which look like personal data are replaced by their type and length, and secrets are always left out. ## Debug Console The "Debug Console" collects in order what happened in the run: its pauses, the lines of `dbms_output`, the messages of log points and the evaluations. Its times are in UTC. The field below it evaluates an expression in the selected frame; Enter or "Evaluate" runs it.