The SQL editor opens one SQL document as one work tab (), 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.
What's on the screen
| No. | Name | Description |
|---|---|---|
| 1 | Work tab | The 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. |
| 2 | Run buttons | The Execute, Run Script, Cancel and Plan buttons. See "Running a query" below. |
| 3 | Dashboard button | Sends the current statement to a dashboard tile. See Dashboards. |
| 4 | Auto Commit switch | Turning it off shows the Commit and Rollback buttons. See "Working with transactions" below. |
| 5 | Format button | Tidies line breaks and indentation. See "Formatting" below. |
| 6 | Execution target | Shown 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. |
| 7 | Keyboard Shortcuts button | The keyboard icon. Lists the shortcuts of this editor. |
| 8 | Editor | Where you write SQL. The statement under the cursor gets a green bar on its left, showing what the Execute button will run. |
| 9 | Result area | The result tabs and the History tab. See "Result tabs" below. Drag the border between the editor and the result area to change their heights. |
| 10 | Status bar | The 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 when | Button or badge | What it does |
|---|---|---|
| The Auto Commit switch is off | Commit and Rollback buttons | Commit or roll back this tab's transaction. |
| There are uncommitted changes | Uncommitted badge | Appears next to the execution target. |
| PostgreSQL has tables with row-level security (RLS) on | Test with RLS... button | Runs SQL as another role. See RLS matrix and simulator. |
| Databricks connections | SQL Warehouse box and session button | Choose 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.
- 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 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.
- 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.
- 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
.sqlfiles 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
| Button | Shortcut | What runs |
|---|---|---|
| Execute | Ctrl+Enter (Cmd+Enter on macOS) | The selection if there is one, otherwise the single statement under the cursor |
| Run Script | Ctrl+Shift+Enter (Cmd+Shift+Enter on macOS) | The statements in the selection if there is one, otherwise every statement in the tab, in order |
| Cancel | Esc | Cancels the running query. If the find bar is open, Esc closes the find bar first |
- Put the cursor inside the statement to run. Check that the green bar on the left is on that statement.
- Click the Execute button or press
Ctrl+Enter(Cmd+Enteron macOS). The bar blinks orange while it runs. - 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,/andDELIMITERare 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 forDROP,TRUNCATEandUPDATE/DELETEwithoutWHERE, 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.
UPDATEand 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.
- Turn off the Auto Commit switch (1). The Commit and Rollback buttons (2) appear.
- 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. - 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
CREATEandALTERcommits 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
- Click the execution target in the toolbar. You can also click the settings button on the SQL document's row in the ERD list.
- In the SQL Editor Settings window, change the title and the Connection, Database and Schema boxes.
- 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.tablein 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, andCtrl+Spaceopens it at any time. On macOS pressCtrl+SpaceorOption+I(Cmd+Spaceis usually taken by Spotlight first). PressEnterto insert a popup item. - Column suggestions come only from the tables in the
FROMandJOINof the statement under the cursor. Until you write a table, columns of all tables are suggested. Tables, views, keywords and SQL templates such asCASE WHEN,COALESCE,EXISTSandWITHare suggested as well. After inserting a template, pressTabto 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 tab.
- In an
INSERTstatement, 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 tab.
| Shortcut | What 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 |
F4 | Opens 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
- 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.
- Choose the kind of SQL from the menu that appears. For tables these are
SELECT,INSERT,UPDATE,DELETEandCREATE (DDL). - 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 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.
| Item | Shortcut | What 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) | None | All SQL in the tab |
- Indentation follows the indentation style and tab size on the 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.
| Project | Where SQL documents are kept | Who sees them |
|---|---|---|
| Local project | NeoSQL storage on this device | Only on this device |
| Account project | The NeoSQL server | Only 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 nameopens 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
| Desktop | Web | |
|---|---|---|
| Where SQL runs | The local server on your computer connects to the database directly. Databases on an internal network or behind a firewall work too | The NeoSQL server connects to the database. Only databases reachable from the internet work |
| Session idle timeout | Set per connection profile environment on the tab | Fixed at 30 minutes |
| Exporting results | Available | Copy 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,
UPDATEandDELETEyou 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.
Related screens
- SQL execution and transactions: sessions, Auto Commit, commits caused by DDL, and what runs.
- Result grid: filters, sorting, copying and row counts of result tabs.
- Editing result data: editing rows in a result and applying them.
- Bind parameters: the window that opens for SQL with value placeholders.
- Execution plan: the result of the Plan button.
- SQL history and saved SQL: finding SQL you ran.
- Dangerous SQL confirmation: the confirmation before running a dangerous statement.
- Dashboards: sending the current statement to a tile.
- Object explorer: opening SQL tabs and dragging nodes to generate SQL.