# SQL editor

The SQL editor runs statements against the workspace's database in tabs. It completes names from the catalog, keeps a history of what you run, saves queries, and formats, explains and cancels statements.

## Where to find it

| Action | How |
| --- | --- |
| Open a query tab | `File` > `New Query`, `⌘T` (`Ctrl+T`) |
| Run the statement under the cursor | `Run`, `⌘Enter` (`Ctrl+Enter`) |
| Run every statement in the tab | `Run all`, `⌘⇧Enter` (`Ctrl+Shift+Enter`) |
| Cancel a running statement | `Cancel`, `⌘.` (`Ctrl+.`) |
| Save the query | The save button in the editor toolbar, `⌘⇧S` (`Ctrl+Shift+S`) |
| Show history | `History` in the sidebar, `⌘⇧H` (`Ctrl+Shift+H`) |
| Lay SQL out on several lines | `Format` > `Beautify`, `⌘I` (`Ctrl+I`) |
| Put SQL back on one line | `Format` > `Uglify`, `⌘⇧I` (`Ctrl+Shift+I`) |
| Explain a statement | `Explain`, `⌘⇧E` (`Ctrl+Shift+E`) |
| Explain and execute a statement | `Explain Analyze` in the `Explain` menu, `⌘⇧⌥E` (`Ctrl+Shift+Alt+E`) |
`Run` sends the statement under the cursor, or the selected text. `Run all` sends every statement in the tab. The footer under the grid shows the row count, the time and the statement that produced the result.

![A query tab holding two SELECT statements with the cursor in the second, its twenty rows in the grid, and a footer with the row count and time.](https://bobbytables.app/docs/img/sql-editor/01-two-statements.png)

_Run sends only the statement under the cursor._

## Completion

Completion suggests SQL keywords, schemas, tables, views and columns from the catalog the sidebar loads. It opens as you type, and `Enter` accepts the highlighted suggestion. After a schema name and a dot it lists that schema's tables and views. After a table name or alias and a dot it lists the columns with their types.

[Typing select * from bookshop.boo lists book_sales and books, books is chosen, and typing an alias and b.t lists the title column, which is accepted.](https://bobbytables.app/docs/video/sql-editor/02-completion.mp4)

_Suggestions come from the connected database._

![The completion list after b. in select * from bookshop.books b where, listing author_id, format, id, in_print, isbn, metadata and page_count with their types and NOT NULL.](https://bobbytables.app/docs/img/sql-editor/03-completion-columns.png)

_Column suggestions show each column's type._

## History

`History` in the sidebar lists the statements run on this connection, newest first and grouped by day. Each entry shows whether it succeeded, its first line, duration, time, row count and database. `Search history` narrows the list, and right-clicking an entry offers `Copy`, `Run in new tab`, `Open in new tab`, `Delete` and `Clear all history...`.

![The History tab listing recent statements under a day heading, with a cancelled pg_sleep run, a failed query and successful runs, and the context menu open on the newest entry.](https://bobbytables.app/docs/img/sql-editor/04-history.png)

_Right-click an entry to copy it or run it again._

## Saved queries

The save button opens `Save query`. Give the query a `Name`, an optional `Folder` and `Keyword`, and a `Scope` of `This connection` or `All connections`. The tab takes the query's name, and the `Saved` tab in the sidebar lists it with a dot for this connection or a globe for all connections. History and saved queries are stored on this computer.

![The Saved tab listing Open orders, Reviews by rating and Top sellers, with the Top sellers tab open in the editor above its ten rows.](https://bobbytables.app/docs/img/sql-editor/05-saved-queries.png)

_A saved query's tab carries its name._

![The Save query dialog with Top sellers in Name, an empty Folder, This connection as the Scope and an empty optional Keyword.](https://bobbytables.app/docs/img/sql-editor/06-save-query-dialog.png)

_Scope decides whether other connections list the query._

## Format and Explain

`Beautify` puts each clause on its own indented line with upper-case keywords, and `Uglify` puts the statement back on one line. With nothing selected, both change the whole tab. `Explain` shows how the server would run the statement under the cursor without running it, while `Explain Analyze` executes it. On PostgreSQL the output opens as text with a `Copy` button.

[A crowded one-line query is beautified onto indented lines with upper-case keywords, then uglified back onto a single line.](https://bobbytables.app/docs/video/sql-editor/07-beautify-uglify.mp4)

_Formatting changes the layout, never what the statement does._

![The results pane after Explain on the Top sellers query, listing the server's indented steps from the limit and sort down to scans of order_items and books, with a Copy button.](https://bobbytables.app/docs/img/sql-editor/08-explain.png)

_On PostgreSQL the explanation opens as text you can copy._

## Errors and cancelling

When the server rejects a statement, the results pane shows its message with the `SQLSTATE` code and the line and column, and the editor marks that position. While a statement runs, the toolbar counts the elapsed time and offers `Cancel`. PostgreSQL and CockroachDB cancel over a separate connection, MySQL, MariaDB and TiDB use `KILL QUERY`, and SQLite is interrupted. The results pane then reports `Query cancelled`.

![The query select * from bokos with the error position marked in the editor, and the results pane reporting that relation bokos does not exist with its SQLSTATE code, line and column.](https://bobbytables.app/docs/img/sql-editor/09-error-position.png)

_The mark sits where the server says the problem starts._

[select pg_sleep(30) runs while the toolbar counts the elapsed time, Cancel is pressed, and the results pane reports that the query was cancelled.](https://bobbytables.app/docs/video/sql-editor/10-cancel.mp4)

_Cancelling does not wait for the busy connection._

## Good to know

- History belongs to the connection it was run on. A saved query with the `All connections` scope appears for every connection.
- Explain runs are recorded in history too.
- Column aliases can change how a result is drawn. See [Result display directives](https://bobbytables.app/docs/result-directives).

## Related

- [Results grid](https://bobbytables.app/docs/results.md)
- [Result display directives](https://bobbytables.app/docs/result-directives.md)
- [Sidebar, Open Anything and tabs](https://bobbytables.app/docs/navigation.md)
- [Safe mode and the console](https://bobbytables.app/docs/safe-mode.md)