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.
Global file search preview
In the desktop app, global file content search previews the selected file below the results. Use the up and down arrow keys or hover to select a result. The preview shows its path and line numbers and scrolls to the highlighted match. Drag to select text in the preview and press Mod+C to copy it. Use Mod+A to select the whole file, or Shift+arrow keys to extend a selection. Click a result or press Enter to open the file. While focused in the read-only preview, the arrow keys still navigate results, Enter opens the selected result, and Escape closes the search dialog. Filename-only matches preview the beginning of the file. Empty files and read failures show an appropriate message.
Use the preview toolbar edit button to change the file in place, including empty files. While editing, Enter and arrow keys edit text, and undo and redo are available. Click Save or press Mod+S to write the file; Cancel discards the current edits. The preview stays on the same file until you save or cancel, with searching, opening other results, and closing the dialog temporarily unavailable. Saving preserves the detected encoding and line endings. If another program has modified or deleted the file, or saving fails, DBX keeps your draft and shows an error without automatically overwriting external changes.
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=unnamedplusWith 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.
Run DBX actions from Vim
Type :dbx <action> in the Vim command line to run a DBX action. Action names match the shortcut action IDs and are case-insensitive, so :dbx formatsql also works. An unknown name shows a notice instead of running anything.
| Scope | Actions |
|---|---|
| Editor | executeSql, executeSqlInNewResultTab, explainSql, formatSql, saveSql, expandSelectStar, toggleLineComment, toggleBlockComment, selectCurrentStatement, previousStatement, nextStatement, statementStart, uppercaseSelection, lowercaseSelection, sendSelectionToAi, sqlIntentionActions |
| App | newQuery, closeTab, closeOtherTabs, closeAllTabs, reopenClosedTab, openSettings |
Editor actions behave like their keyboard shortcuts. For example, executeSql runs the selection when there is one, and the current statement otherwise. Running from Visual mode, which enters :'<,'>dbx executeSql, restores the visual selection first, so only the selected SQL is used. Linewise and blockwise selections are expanded to whole lines.
Editing actions that Vim already provides, such as undo, indent, delete line, and join lines, are not exposed through :dbx; use the native Vim commands instead.
Each action also has a space-free command, :Dbx followed by the action name with its first letter capitalized, for example :DbxExecuteSql or :DbxFormatSql. Use these in vimrc mappings, because CodeMirror Vim mappings stop at the first space and cannot map :dbx executeSql directly:
nnoremap Qr :DbxExecuteSql<CR>
vnoremap Qr :DbxExecuteSql<CR>
nnoremap Qf :DbxFormatSql<CR>
nnoremap Qj :DbxNextStatement<CR>
nnoremap Qk :DbxPreviousStatement<CR>CodeMirror Vim runs a built-in command as soon as the typed keys match it, without waiting for more keys the way Vim's timeoutlen does. Use a prefix that is not already a single-key command, such as Q. Common leader keys like <Space> (move right) and , (repeat the last f/t search backward) are consumed by their built-in commands, so mappings like <Space>r or ,x never fire. To use one of them as a prefix, unmap its built-in command first, which also removes that key's original behavior:
unmap <Space>
nnoremap <Space>r :DbxExecuteSql<CR>
vnoremap <Space>r :DbxExecuteSql<CR>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.
Double-Click String or Word Selection
By default, double-clicking inside a SQL string selects its whole value. For example, double-clicking the year in '2013-12-20 09:30:26.603' selects the entire timestamp without the surrounding quotes.
To select only the word or numeric segment under the pointer:
- Open Settings → Editor.
- Set Double-click inside a string to Select single word.
- Click Apply or Apply and Close.
This mode uses the editor's default word boundaries. For example:
| String content | Double-click target | Selected text |
|---|---|---|
2013-12-20 09:30:26.603 | Year | 2013 |
2013-12-20 09:30:26.603 | Milliseconds | 603 |
123-456 | Second numeric segment | 456 |
123.456 | Second numeric segment | 456 |
abc123 | Digits | abc123 |
This is word selection, so adjacent letters and digits remain one word. Switch back to Select whole value to restore the default behavior. This option controls double-clicking strings in the SQL editor; it does not control text selection in the result grid.
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.
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 onecolumn (new)column per assigned column (expressions are evaluated, soSET a = a + 1shows the actual new value);INSERT— the grid shows the rows that would be inserted (column names from the target columns,VALUESexpanded);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.
Table and Object Navigation
Ctrl/Cmd+Clicka 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.
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.
PL/SQL Debugging
For Oracle and OceanBase Oracle mode, use the debug entry points to step through procedures, functions, package members, and anonymous blocks. See PL/SQL Debugging for startup, explicit debug compilation, recovery, and transaction boundaries.
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.
Inspect Existing Session Evidence
For Oracle and OceanBase Oracle connections, open Process List from the connection context menu, then choose Diagnostics on a session row to inspect SQL, an existing plan, statistics and waits, and long operations. This reads evidence already retained by the database; it does not execute the target SQL or generate a new plan.
Diagnostics freezes the session and SQL identity captured when opened. Refresh reads the same target. If the session moves to another SQL statement, the page marks the change instead of attaching the new statement's data to the original result. Select explicitly when several audit requests or cached plans match. SQL text shows its completeness. Plan rows are estimates; Oracle cursor counters, OB request statistics, and cached-plan cumulative statistics have separate scope labels.
Stop reading ends the local wait and attempts to cancel diagnostic queries without terminating the target session. Permission errors, unavailable views, evicted cache entries, and uncollected data have distinct states. Failed refreshes retain earlier data with its sampling time. An empty long-operation result does not mean the SQL has finished. OB long operations show available timing information without inventing a work percentage.
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
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.
On Desktop, the Locate current file button in the SQL Files panel expands parent directories, selects the current file, and scrolls it into view. If its directory is not open yet, it is added to the file tree first. Unsaved queries cannot be located. File filters remain in effect; hidden or missing files show a notification.
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
USEand 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.
Inspect results
Learn data-grid browsing, copying, export, and safe editing.
Run SQL files
Execute large scripts with file- and statement-level progress.
Configure snippets
Create personal SQL templates that expand through completion.
Use AI
Generate, explain, and optimize SQL, then return it to the editor for review.