Screens: SQL editor

SQL editor

The SQL editor opens one SQL document as one work tab (Document tabSQL editor), where you write and run SQL. Each tab has its own execution target (connection, database, schema) and its own database session. How sessions and transactions behave is explained in SQL execution and transactions, and execution targets in Connections and execution targets.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What's on the screen

No.NameDescription
1Work tabThe title of the SQL document. The tag in front is painted in the connection profile's color. A dot replaces the close button while there are unsaved changes, and a TX badge appears while a transaction is uncommitted.
2Run buttonsThe Execute, Run Script, Cancel and Plan buttons. See "Running a query" below.
3Dashboard buttonSends the current statement to a dashboard tile. See Dashboards.
4Auto Commit switchTurning it off shows the Commit and Rollback buttons. See "Working with transactions" below.
5Format buttonTidies line breaks and indentation. See "Formatting" below.
6Execution targetShown as connection / database / schema. The database appears only for DBMSs with a database level, such as PostgreSQL and SQL Server, and All appears when no schema is set. Click it to open the SQL Editor Settings window.
7Keyboard Shortcuts buttonThe keyboard icon. Lists the shortcuts of this editor.
8EditorWhere you write SQL. The statement under the cursor gets a green bar on its left, showing what the Execute button will run.
9Result areaThe result tabs and the History tab. See "Result tabs" below. Drag the border between the editor and the result area to change their heights.
10Status barThe bottom line of the app. Shows this tab's connection, database and schema, the SQL document title, the cursor position (line, column) and the number of selected characters. When the Auto Commit switch is off, a Transaction item is added in front.

Depending on the connection and state, the toolbar also shows these.

Shown whenButton or badgeWhat it does
The Auto Commit switch is offCommit and Rollback buttonsCommit or roll back this tab's transaction.
There are uncommitted changesUncommitted badgeAppears next to the execution target.
PostgreSQL has tables with row-level security (RLS) onTest with RLS... buttonRuns SQL as another role. See RLS matrix and simulator.
Databricks connectionsSQL Warehouse box and session buttonChoose the SQL Warehouse for this tab, and open a new session (New session) or close it (Close session). You cannot change them while changes are uncommitted or a query is running.
  • The Execute, Run Script and Plan buttons work only when the target connection has connection details.
  • The Plan button is disabled for DBMSs that do not provide an execution plan through SQL. See Execution plan.

Opening a SQL tab

You can create a SQL tab only when the project has at least one connection with connection details. Otherwise the buttons and menus are disabled and the Connect a connection to a database first to create a SQL editor. message appears.

  1. Create a new SQL document from one of these places.
    • In the explorer, right-click a node such as a connection, database, schema or table and choose the Explorer context menuNew SQL Editor... menu. That node's location is filled in as the execution target.
    • Click the SQL button of the ERD and SQL list at the bottom left. Hover a connection or schema row of the list and choose the New SQL item from its + button to have that location filled in.
    • Click the + button at the end of the work tab strip and choose the Add SQL Editor... item. When no tabs are open, click the Create New SQL Editor button in the middle.
  2. In the Create SQL Editor window, enter a title and choose the Connection and Schema boxes. For DBMSs with a database level, also choose the Database box.
  3. Click the OK button. The SQL document is created in the project and its SQL tab opens.
  • Click an existing SQL document in the ERD list to open it.
  • If a SQL document with the same target as the node you right-clicked already exists, the menu becomes a SQL Editor submenu. From the submenu, create a new one or open one of the five most recently edited documents.
  • Drop .sql files onto the work tab strip to create and open one SQL document per file, titled with the file name. If there is only one connection and schema it does not ask; otherwise it asks once for the execution target.

Running a query

ButtonShortcutWhat runs
ExecuteCtrl+Enter (Cmd+Enter on macOS)The selection if there is one, otherwise the single statement under the cursor
Run ScriptCtrl+Shift+Enter (Cmd+Shift+Enter on macOS)The statements in the selection if there is one, otherwise every statement in the tab, in order
CancelEscCancels the running query. If the find bar is open, Esc closes the find bar first
  1. Put the cursor inside the statement to run. Check that the green bar on the left is on that statement.
  2. Click the Execute button or press Ctrl+Enter (Cmd+Enter on macOS). The bar blinks orange while it runs.
  3. Check the result in the result area. On failure the result tab shows the error, and the failed statement gets a red bar and a marker next to the line numbers.
  • Statements are split at ;. Depending on the DBMS, GO, / and DELIMITER are also read as separators. The detailed rules, and the choices you get when the Run Script button stops at an error, are in SQL execution and transactions.
  • If a check is needed before running, a window opens first: the Bind parameters window for value placeholders (?, :name), the Dangerous SQL confirmation window for DROP, TRUNCATE and UPDATE/DELETE without WHERE, and a confirmation window when the connection profile's protection mode asks for one.
  • If the result grid has edits you have not applied, it asks whether to discard them before running again.
  • Right-clicking the editor also offers the Execute Statement, Run Script, Cancel Query and Explain Plan menus.

Result tabs

  • The Execute button writes the result over the result tab you are looking at. A result tab is named after the queried table, or Result when that is unknown.
  • To keep a result, right-click its result tab (2) and choose the Pin tab menu. Pinned tabs are not overwritten; if no unpinned result tab is left, a new one is created. The same menu closes the tab, or the other, left, right or all tabs.
  • The Run Script button creates one Statistics tab (1) and one result tab for each SELECT. UPDATE and DDL do not get result tabs; the Statistics tab sums them up in the Queries, Updated Rows, Errors, Execute time items.
  • If result tabs already exist when you click the Run Script button, the Close extra result tabs window lets you choose between the Close tabs and Keep tabs buttons. Pinned tabs are never closed. Turn on Don't ask again to stop being asked.
  • The History tab (3) lists the SQL run in this SQL document. See SQL history and saved SQL.
  • Result tabs received before you changed the execution target get a warning icon and the Ran against a different target notice, and that result cannot be edited. Click the Re-run here button to run it again on the current target.
  • Filters, sorting, copying and row counts of the result grid are in Result grid, editing results in Editing result data, and saving to files in Exporting results.

Working with transactions

A SQL tab opens with the Auto Commit switch on, so each statement you run is committed immediately. To check results before committing, turn the switch off.

  1. Turn off the Auto Commit switch (1). The Commit and Rollback buttons (2) appear.
  2. Run a statement such as UPDATE. When there are uncommitted changes, the Uncommitted badge (3) and the TX badge on the work tab (4) appear.
  3. Check the result and click the Commit button to commit, or the Rollback button to undo. The editor's context menu also has the Commit and Rollback menus.
  • If you close the tab or change the execution target with changes uncommitted, it asks whether to commit or roll back. NeoSQL never commits or rolls back on its own.
  • DDL such as CREATE and ALTER commits pending changes on some DBMSs. The per-DBMS table, the transaction idle timeout and the BigQuery exception are in SQL execution and transactions.
  • If the connection drops and uncommitted changes are rolled back, the Uncommitted changes were rolled back. Rerun the affected SQL statements as needed. notice appears above the editor.

Changing the execution target

  1. Click the execution target in the toolbar. You can also click the settings button on the SQL document's row in the ERD list.
  2. In the SQL Editor Settings window, change the title and the Connection, Database and Schema boxes.
  3. Click the OK button. The change is saved to the SQL document right away.
  • Changing the execution target closes this tab's database session and opens a new one on the new target. If a transaction is uncommitted, the Resolve transaction before changing target window first asks whether to commit or roll back. You cannot change it while a query is running.
  • SQL Server cannot change a session's default schema, so the Schema box is locked with the SQL Server doesn't support session-level schema switching, so queries run against the login's default schema. Qualify objects in other schemas as schema.table in your SQL. notice. Write tables in other schemas as schema.table in your SQL.
  • A SQL tab opened for an external MCP client to run SQL shows a lock icon next to its execution target, and its title and target cannot be changed.

Autocomplete and editing aids

  • The autocomplete popup opens as you type. Typing alias. shows that table's columns, and Ctrl+Space opens it at any time. On macOS press Ctrl+Space or Option+I (Cmd+Space is usually taken by Spotlight first). Press Enter to insert a popup item.
  • Column suggestions come only from the tables in the FROM and JOIN of the statement under the cursor. Until you write a table, columns of all tables are suggested. Tables, views, keywords and SQL templates such as CASE WHEN, COALESCE, EXISTS and WITH are suggested as well. After inserting a template, press Tab to move to the next field.
  • When a continuation appears as faint text while you type a statement, accept it with Tab (or → at the end of the line). After the first three or more characters of a statement, it may also show, as faint text, SQL you ran before on this connection that starts the same way.
  • Syntax colors follow the DBMS of the target connection.
  • Columns that are not in the referenced tables get a red underline. Only tables whose metadata has been loaded are checked, so it can differ from the real database. Turn it off with the Highlight unknown columns item on the Project settingsSQL Editor tab.
  • In an INSERT statement, the column under the cursor and its value are highlighted together, and a wavy underline appears when the numbers of columns and values do not match.
  • Indentation style and tab size are set on the Project settingsSQL Editor tab.
ShortcutWhat it does
Ctrl+F / Ctrl+R (Cmd on macOS)Opens the find / Replace bar. Ctrl+G and Ctrl+Shift+G move to the next and previous match
Ctrl+/ (Cmd+/ on macOS)Adds or removes line comments
F4Opens the table under the cursor in a table tab (Table tab). Same as the Open "orders" menu in the context menu
Ctrl+Shift+E (Cmd+Shift+E on macOS)Shows the execution plan
  • Right-clicking the editor offers the Cut, Copy and Paste menus, and the Format SQL, Toggle Comment, UPPERCASE and lowercase menus. The AI: Tune query menu is explained in AI in the editor and ERD.

Generating SQL from the explorer

  1. Drag a table, view, function, procedure or sequence node from the explorer and drop it on the editor. If you selected several nodes, they come along together.
  2. Choose the kind of SQL from the menu that appears. For tables these are SELECT, INSERT, UPDATE, DELETE and CREATE (DDL).
  3. The SQL is inserted where you dropped it. Dropping below the last line inserts it on a new line at the end.
  • Nodes of a different connection than this tab cannot be dropped, and the editor shows the Different connection — can't drop here notice.
  • You can also right-click a node in the explorer and choose the Explorer context menuGenerate Query menu to generate the same SQL. That menu does not insert the SQL into the editor; it shows it in a preview window, where the Copy SQL button copies it.

Formatting

The Format button tidies line breaks and indentation for the target DBMS's syntax and changes keywords to upper case.

ItemShortcutWhat it formats
Format Statement (clicking the button itself)Ctrl+Shift+F (Cmd+Shift+F on macOS)The selection if there is one, otherwise the statement under the cursor
Format All (the arrow next to the button)NoneAll SQL in the tab
  • Indentation follows the indentation style and tab size on the Project settingsSQL Editor tab.
  • Formatting only changes the SQL text. Save afterwards to keep it in the SQL document.

Saving

SQL documents are not saved automatically. Press Ctrl+S (Cmd+S on macOS) to save.

  • While there are unsaved changes, a dot replaces the work tab's close button. If you close the tab anyway, the Unsaved Changes window lets you choose the Save, Discard or Cancel button.
  • The title and execution target are saved when you click the OK button in the SQL Editor Settings window. The SQL you are writing is not saved along with them.
  • Where it is saved depends on the project.
ProjectWhere SQL documents are keptWho sees them
Local projectNeoSQL storage on this deviceOnly on this device
Account projectThe NeoSQL serverOnly you see the SQL documents you created. Teammates in the same project do not see them
  • In an account project, if another device saved the same SQL document first, saving asks whether to take the server's content or overwrite it with yours. If you are not editing, the tab switches to the server's content on its own.

Telling production connections apart

Set the environment of the connection profile and the screen shows which database a SQL tab points at.

  • The profile color paints the work tab's tag and the line to the right of the editor's line numbers.
  • With a background watermark turned on, the label is laid across the editor background. It is on from the start for the production environment.
  • When the protection mode asks for confirmation, a confirmation window titled [environment] connection name opens before running; in read-only mode, statements other than SELECT are blocked.
  • How to set profiles and what protection mode covers are in Safeguards for production databases.

Web and desktop

DesktopWeb
Where SQL runsThe local server on your computer connects to the database directly. Databases on an internal network or behind a firewall work tooThe NeoSQL server connects to the database. Only databases reachable from the internet work
Session idle timeoutSet per connection profile environment on the Project settingsSQL Editor tabFixed at 30 minutes
Exporting resultsAvailableCopy the results, or export files on desktop when the This feature is only available in the desktop app. notice appears
  • Editing, running, transactions and saving are otherwise the same. All differences between web and desktop are in Web and desktop.

Things to keep in mind

  • While the Auto Commit switch is on, UPDATE and DELETE you run cannot be undone. When changing data in a production database, turn the switch off, run, check the result and then commit.
  • The Execute button runs only the selection if there is one. Clicking it with part of a statement selected runs that part or fails. Check the green bar or the selection before running.
  • To avoid running against a target you did not mean, check the execution target in the toolbar and the status bar first. If tables with the same name exist in several schemas, a different table may change.
  • SQL documents persist only when saved with Ctrl+S. The app asks before closing when documents are unsaved, but documents are never saved automatically.
  • The red underline for unknown columns is a guess. No underline does not mean the statement will succeed.
  • SQL documents in account projects are not shared with teammates. To pass SQL to a teammate, copy and send it.