Query Editor

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.

Vim configuration

In the desktop app, enable Vim mode in Editor Settings to load commands from ~/.dbx/vimrc. Create the file if needed, then restart DBX after editing it. Blank lines and lines beginning with " are ignored. Commands supported by CodeMirror Vim, such as these mappings, apply to every SQL editor tab:

" DBX Vim mappings
imap jj <Esc>
nmap Y y$
set clipboard=unnamedplus

With set clipboard=unnamedplus, Vim yanks and deletes write to the system clipboard, and normal-mode p and P read from it. Unsupported commands do not prevent the editor from starting.

Basic Workflow

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.

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.

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.

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.

Save and reuse

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

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.

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.

Cancellation depends on the driver and database. After Stop is clicked, the server may still need time to interrupt the current statement.

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 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

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.

Refresh connection metadata after creating or changing objects. DBX caches and lazy-loads table structure to reduce repeated requests in large schemas.

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.

Raw SQL parameters are not quoted automatically. Use them only for reviewed SQL fragments and never concatenate untrusted input.

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 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

In Settings → Data → Query history retention, choose 200, 1000 (default), 5000, 10000, or Unlimited. The limit is shared by all connections and execution sources, including MCP. A lower limit takes effect the next time a history entry is recorded: older entries beyond the limit are deleted. Raising the limit does not recover deleted entries. History page sizes remain unchanged.

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

History can contain business fields, table names, predicates, or literal values. Review sensitive information before sharing logs, screenshots, or configuration backups.

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 for the complete rules.