dbx/docs/content/docs/query-editor.mdx

---
title: Query Editor
description: Write, understand, parameterize, execute, analyze, and reuse SQL in DBX.
---

The query editor is the SQL workspace in DBX. It combines dialect-aware highlighting and completion, semantic diagnostics, parameter input, execution progress, multiple results, execution plans, query history, the SQL library, and AI assistance in one tab.

## Basic Workflow

<Steps>
  <Step>
    ### Choose connection context

    Select a connection, database, and schema when creating a query. You can also open a contextual query from the object tree, Quick Open, SQL Library, or SQL Files.

  </Step>
  <Step>
    ### Write and inspect SQL

    Use completion, hover details, semantic diagnostics, formatting, and code folding. Depending on settings, `Ctrl/Cmd+Click` can navigate to table data or the related object.

  </Step>
  <Step>
    ### Make the execution scope explicit

    Select the SQL to run or use the current statement or full editor. For multi-statement text, the execution target picker can confirm the exact range.

  </Step>
  <Step>
    ### Inspect results or a plan

    The result area supports multiple runs, horizontal tabs, or a list view. Use Explain Plan to inspect the plan tree, summary, and standard result table.

  </Step>
  <Step>
    ### Save and reuse

    Save stable queries to the SQL Library or external `.sql` files, then reopen them through history, Quick Open, or folders.

  </Step>
</Steps>

## Execute SQL

| Action | macOS | Windows / Linux |
| --- | --- | --- |
| Execute the current scope | `Cmd+Enter` | `Ctrl+Enter` |
| Execute in a new result | `Cmd+\` | `Ctrl+\` |
| Stop execution | Click the execution button after it changes to Stop | Click the execution button after it changes to Stop |

When text is selected, DBX prioritizes the selection. Otherwise, the current-statement and execution-target settings determine the scope. Shortcuts can be changed under [Keyboard Shortcuts](/en/docs/keyboard-shortcuts).

Normal execution updates the active result. **Execute in a new result** preserves older results for comparison. Results can use horizontal tabs or a list view, and repeated executions can retain run history or pin important results.

For multi-statement execution, the result area shows the current statement, total count, completion state, and errors. When the driver supports it, the active query or remaining statements can be cancelled.

<Callout type="warn">Cancellation depends on the driver and database. After Stop is clicked, the server may still need time to interrupt the current statement.</Callout>

### Preview DML changes before executing

For an `UPDATE`, `INSERT`, or `DELETE` statement, the toolbar shows a **Preview changes** button (also available in the editor context menu). DBX rewrites the statement into an equivalent read-only `SELECT` and opens it in a new result tab. The preview re-evaluates the expressions being written, so expressions with side effects (advancing a sequence, volatile functions) still take effect during the preview, and values shown for non-deterministic functions (`uuid()`, `rand()`, `now()`) may differ from the actual execution:

- `UPDATE` — the grid shows the affected rows plus one **`column (new)`** column per assigned column (expressions are evaluated, so `SET a = a + 1` shows the actual new value);
- `INSERT` — the grid shows the rows that would be inserted (column names from the target columns, `VALUES` expanded);
- `DELETE` — the grid shows the rows that would be removed.

Statements DBX cannot rewrite safely (for example some dialect-specific forms, or `UPDATE ... FROM`) are reported as **Preview is not supported** and can still be executed normally.

## Execution Scope and Target Picker

| Scope | How it is selected | Best for |
| --- | --- | --- |
| Selected SQL | Highlight text before execution | The clearest and safest option in a multi-statement draft |
| Current statement | Put the cursor inside a statement | Running one statement from a script quickly |
| Full editor | No selection and settings choose the full document | Short, single-purpose scripts |

The execution target picker marks executable statements and shows a preview when needed. It can be disabled in settings, but it is useful for production and complex scripts.

Use [SQL File Execution](/en/docs/sql-file) for large `.sql` files or tasks that need per-statement progress and file-level statistics.

## Completion and Semantic Diagnostics

Completion uses the active database dialect and metadata to suggest:

- SQL keywords, functions, types, and engine-specific syntax
- Databases, schemas, tables, views, columns, and column comments
- Table aliases, CTEs, subquery scope, and visible fields
- JOIN conditions based on foreign keys or relationship metadata
- Dialect-specific functions and syntax for MySQL, PostgreSQL, SQL Server, ClickHouse, and others
- User-defined [SQL Snippets](/en/docs/sql-snippets)

Semantic diagnostics flag selected unresolved tables, columns, aliases, and SQL structures. They help catch mistakes early but do not guarantee that vendor extensions will be accepted or rejected; the server result remains authoritative.

<Callout type="info">Refresh connection metadata after creating or changing objects. DBX caches and lazy-loads table structure to reduce repeated requests in large schemas.</Callout>

## Table and Object Navigation

- `Ctrl/Cmd+Click` a table name to open data or locate the object, depending on settings
- Locate the table referenced at the cursor in the sidebar
- Use Quick Open to search connections, databases, tables, SQL Files, and the SQL Library
- Search embedded object-source views and open SQL in the editor for further work

Navigation depends on SQL parsing and current metadata. Dynamic SQL, ambiguous names, or references without a schema may require manual confirmation.

## SQL Parameters and Variables

Before execution, DBX can recognize common placeholders and open a parameter-input dialog:

| Syntax | Example |
| --- | --- |
| Positional | `?` |
| Named | `:user_id` |
| Shell style | `${user_id}` |
| MyBatis style | `#{user_id}` |
| SQL Server style | `@user_id` |
| Script variable | `@set user_id = 42;` |

Parameters can be entered as strings, numbers, booleans, `NULL`, or raw SQL values. Per-database settings can disable placeholder forms that conflict with native syntax.

<Callout type="warn">Raw SQL parameters are not quoted automatically. Use them only for reviewed SQL fragments and never concatenate untrusted input.</Callout>

## Formatting, Compacting, and Folding

- **Format SQL** normalizes indentation, line breaks, and keyword style
- **Compact SQL** removes unnecessary whitespace for copying or inspecting generated SQL
- **Code folding** collapses long queries, subqueries, or routine blocks and has configurable shortcuts
- See [SQL Formatting](/en/docs/sql-formatter) for formatter and variable-syntax settings

Formatting and compacting only change editor text; they do not execute SQL.

## Explain Plan

Explain Plan accepts query-like SQL that is safe to analyze, such as `SELECT`, `WITH`, `TABLE`, or `VALUES`. Supported databases can return:

- A standard result table
- An expandable plan tree
- Node, cost, estimated-row, relation, and index summaries
- Raw details returned by the database

`EXPLAIN` semantics vary by database, and some engines provide only table or text output. A plan reflects optimizer estimates rather than real production performance; evaluate it together with data volume, statistics, indexes, and measured runtime.

## Query History

Query history stores executed SQL per connection with time and context. You can:

- Filter by date range
- Search and restore SQL into the editor
- Distinguish normal and AI-assisted sources
- Recover or compare earlier troubleshooting work
- Use historical SQL as a possible reference source in field lineage

<Callout type="warn">History can contain business fields, table names, predicates, or literal values. Review sensitive information before sharing logs, screenshots, or configuration backups.</Callout>

## SQL Library and SQL Files

| Method | Best for | Platform boundary |
| --- | --- | --- |
| SQL Library | Saving and searching reusable queries in folders inside DBX | Full local SQL Library management is available on Desktop; cloud-sync scope depends on settings |
| External SQL Files | Sharing `.sql` files with a repository, script directory, or editor | Local file open/save and the file tree are Desktop capabilities |
| Query tabs | Temporary analysis and unfinished drafts | Settings can restore all tabs, pinned tabs only, or none |

The save dialog can search or create folders. Quick Open indexes both SQL Library entries and SQL Files.

## Safety and Boundaries

- Read-only connections reject recognizable writes in the core execution path
- Production protection requires a fresh explicit confirmation for writes
- Dangerous-SQL confirmation and Redis command safety are additional layers
- `USE` and database switches update query context, but the active connection and target database still need review
- Completion, diagnostics, and explain plans depend on the active driver and metadata support

See [Production and Write Safety](/en/docs/production-safety) for the complete rules.

<Cards>
  <Card title="Inspect results" href="/en/docs/data-grid">
    Learn data-grid browsing, copying, export, and safe editing.
  </Card>
  <Card title="Run SQL files" href="/en/docs/sql-file">
    Execute large scripts with file- and statement-level progress.
  </Card>
  <Card title="Configure snippets" href="/en/docs/sql-snippets">
    Create personal SQL templates that expand through completion.
  </Card>
  <Card title="Use AI" href="/en/docs/ai-assistant">
    Generate, explain, and optimize SQL, then return it to the editor for review.
  </Card>
</Cards>