SQL debugger

The SQL debugger is the SQL Debug panel in the Editor. It shows how the editor reads the query in your console: its structure, its parse tree and the context at your cursor. Open it while you write when you want to check what the editor understands, or when you want a snapshot of that view to share.

Open the SQL debugger

1. Open a console in the Editor.
2. In the editor toolbar, click the debugger button. Point to it first: its tooltip reads Show SQL debugger while the panel is hidden, and Hide SQL debugger while it is open.
3. The SQL Debug panel appears beside the editor, with three tabs: Structure, AST and CST.

The panel follows your work: it reads the text in the console and the position of your cursor. The editor builds this state only while the panel is open, so close the panel when you are done with it.

Read the Structure tab

The Structure tab has the header Query Structure. It breaks the parsed query into five sections, each with a count of its entries:

• Tables lists the tables named in the query.
• CTEs lists every common table expression. An entry shows its order as Order: N, plus its depth, its columns and whether it contains subqueries. Up to five columns are listed; +N more shows the rest.
• Subqueries lists every subquery. An entry shows its level as Level: N, its type (such as Scalar), whether it is correlated and whether it aggregates.
• Joins lists every join, marked Left: and Right: for its two sides.
• At cursor lists the tables that are visible at the position of your cursor.

The tab also summarises the parsed query: its type, its scope depth, how many SELECT statements it contains and whether it has correlated subqueries.

When a section has nothing to show, it reads No tables, No CTEs, No subqueries, No joins or None at cursor. When there is no query to read at all, the tab shows No query structure with "Start typing to analyze the query".

Each section opens and closes. Expand query structure viewer and Collapse query structure viewer open or fold the whole viewer.

Read the AST tab

The AST tab has the header AST Tree. It shows the parse tree of the query as an interactive tree:

• The first two levels open automatically.
• Expand tree viewer and Collapse tree viewer open or fold the tree.
• Hover over an item to see how many children it has.
• The smallest items are the tokens of your query; long rule names are shortened with an ellipsis.

When the editor cannot build a tree yet, the tab shows No parse tree with "Start typing to build the AST".

Read the CST tab

The CST tab shows the context the editor finds at the position of your cursor:

• The Trigger key of the position.
• A Prefix chip with the text being completed, or (empty) when there is none.
• A Rule in JSON chip showing whether the editor has a rule for this position.
• The Keywords, Suggest and Groups lists, each with a count. An empty list shows (none).

Move the cursor and the tab follows it. When the editor has no context for the position, the tab shows No CST context with "Move cursor in the editor".

Copy or download the debug snapshot

1. Click Copy all debug info to copy the snapshot to the clipboard. The button shows Copied! when the copy works, and Copy failed when it does not.
2. Click Download debug log and SQL to save the snapshot as a .txt file instead. The file name is sql-debug_ followed by the time of the download, with colons and dots replaced by dashes.

The snapshot starts with SQL Debug Snapshot and the time it was generated. After that it lists, in order: the SQL text of the console, the structure (including the tables that were visible), the parse tree and the cursor context. Parts with nothing to show are marked (none).

Where to go next

• Write and check SQL covers the helpers you use while writing a query, such as autocomplete and the syntax check.
• Run your first query covers running a query and reading its results.
• Editor troubleshooting lists the messages the Editor shows, with what to do.

Questions, answered

Does the debugger change or run my query?

No. It reads the text in the console and shows how the editor parses it. It never runs the query and never edits the console. To see rows, run the query and read the Results tab, as described in Run your first query.

Why are all three tabs empty?

The tabs stay empty while the editor cannot build a parse tree from the text. This happens when the console is empty, or when the SQL is not yet complete enough to read. Write or fix the statement and check the tabs again.

What is the difference between the AST tab and the CST tab?

The AST tab shows the whole parse tree of the query. The CST tab shows only the context at your cursor: the trigger found there, and the keywords and names the editor can offer from that position.

Why did the CST tab change when I clicked somewhere else?

The tab follows your cursor, so the context changes with the position. When the editor finds no context for the position, it shows No CST context with "Move cursor in the editor".

What does the At cursor section show?

It lists the tables that are visible at the position of your cursor. When nothing is visible there, it shows None at cursor.

Can I keep the debugger open while I edit?

Yes. The panel reads the text in the console and the position of your cursor, so it updates while you write and while you move around the query.

Does the debugger slow down typing?

The editor parses the whole query to build the debug state, and it does that only while the panel is open. Keep the panel open while you need it, and close it when you are done.

Can I share the debug details with someone?

Yes. Use Copy all debug info or Download debug log and SQL, and share the result. The snapshot contains the SQL text of the console, so review it before you send it on.