Bobby Tables Download
Browse documentation

Query

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

ActionHow
Open a query tabFile > New Query, ⌘T (Ctrl+T)
Run the statement under the cursorRun, ⌘Enter (Ctrl+Enter)
Run every statement in the tabRun all, ⌘⇧Enter (Ctrl+Shift+Enter)
Cancel a running statementCancel, ⌘. (Ctrl+.)
Save the queryThe save button in the editor toolbar, ⌘⇧S (Ctrl+Shift+S)
Show historyHistory in the sidebar, ⌘⇧H (Ctrl+Shift+H)
Lay SQL out on several linesFormat > Beautify, ⌘I (Ctrl+I)
Put SQL back on one lineFormat > Uglify, ⌘⇧I (Ctrl+Shift+I)
Explain a statementExplain, ⌘⇧E (Ctrl+Shift+E)
Explain and execute a statementExplain 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.
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.

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

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.
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.
The mark sits where the server says the problem starts.
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.

View as Markdown