BroadSQL Editor

The BroadSQL Editor is BroadSQL's native workspace for browsing, editing and versioning the Scripts in the Scripts Library. It replaced the earlier behavior where EDIT opened an external editor with no connection to the library.

It manages the Scripts that Scripts Library describes: the folder set by ScriptsLibrary in BroadSQL.ini, shown as a tree of folders and files. Those remain ordinary, human readable text files at their existing locations; the Editor is an improved native experience on top of them, not a lock in mechanism. Opening the Editor never requires an active database connection; only running a Script from inside it does.

The Editor shows Scripts only. JavaScript files for the experimental JS commands are outside the Scripts Library, never appear in the tree, and cannot be created here.

Opening it

EDIT
EDIT <script>
LIB EDIT
LIB EDIT <script>

All of these open or focus the same single Editor window: the first call in a session creates it, every later call reuses it, and none of them starts an external editor. Opening a Script never saves anything.

Without <script>, the Editor opens on a new, unsaved Script, ready to type in, exactly as if you had chosen New Script (an untouched new Script already open is reused rather than adding another). With <script>, only that Script is opened, and it is selected in the Scripts pane.

<script> is a path relative to the Scripts Library, resolved exactly as LIB RUN resolves it (no file name search, no alias, no extension added). If the Script exists it opens on its existing tab; if it does not, the Editor offers to create it. A path that leaves the library, a folder, or a file that is not text is reported as an error.

The window

Under the menu bar, a row of icon buttons gives the most used commands, in three groups: New, New Folder and Save; Format, Run and History; Rename, Duplicate and Delete. Hovering a button shows its name and keyboard shortcut. Run (green) and Delete (red) are the only colored buttons.

Below it, three panes sit side by side, separated by dividers you can drag:

• Scripts, on the left: the Scripts Library, with a Search field above it;
• the editor, in the middle, one tab per open Script, from the toolbar down to the status bar; it receives the extra space when the window is enlarged;
• on the right, two tabs: Metadata and Output.

The status bar at the bottom reports what the last action did, for example Opened 'reports/QR13.sql'. Divider positions are not remembered between sessions.

Closing the Editor window (its X button) only hides it: every open tab and its unsaved content survive, and the same window reopens, exactly as left, the next time any of the commands above is used.

Browsing

The Scripts pane shows the content of the configured Scripts Library folder as a tree: its folders, subfolders and Scripts appear directly, without a node for the library folder itself. Every text file is a Script whatever its extension; files that are not text are not shown, and the reserved archives folder is never shown. In every folder, folders come first, then Scripts, each in alphabetical order without regard to case. Folders show a folder icon, open when expanded, and Scripts a document icon.

The Search field filters by path or @description. Double clicking a Script, or selecting it and pressing Enter, opens it in an editor tab; File > Open opens the Script selected in the tree. Enter on a folder expands or collapses it. Ctrl+click adds an item to the selection and Shift+click selects a range, as in any tree.

The tree always shows which Script you are editing: when you switch tabs, open, duplicate, rename or move a Script, the active tab's Script is selected and scrolled into view, its folders expanded. A new Script that has not been saved has no place in the library yet, so the selection is cleared. Selecting an item in the tree opens nothing; double click or Enter does.

Every right click menu ends with Refresh, which rescans the folder for changes made outside BroadSQL (files added, removed or renamed with another program), keeps the folders you had expanded open, and never touches a tab with unsaved changes or a new unsaved Script. Changes made in the Editor itself appear without it.

Right clicking an item selects it and shows its actions: Open, New Script, New Folder, Rename, Duplicate, Delete, the Copy Path entries and Send to CLI for a Script; New Script, New Folder, Rename, Delete and the Copy Path entries for a folder; New Script and New Folder (at the top level) on empty space.

Moving Scripts and folders

Drag a Script or a folder onto a folder to move it there, or onto empty space below the tree to move it to the top level. Dropping onto a Script moves the item into that Script's folder. To move several items at once, select them (Ctrl+click, Shift+click) and drag the selection. It is a move inside the Scripts Library: nothing is copied, and files from outside BroadSQL cannot be dropped in.

• A moved Script keeps its name, its identity and its full revision history, exactly like Rename.
• An item inside a selected folder moves with that folder, once; an item already in the destination stays where it is.
• The whole move is checked before anything moves. Nothing is ever overwritten: if the destination already holds an item with the same name, or two selected items have the same name, nothing moves and a message says why. A folder cannot be dropped onto itself or onto one of its own subfolders.
• If the move fails on disk partway, the items already moved are moved back, and the error is shown; in the rare case where one cannot be moved back, the message names it and where it is. The tree always shows what is really on disk afterwards.
• A Script open in a tab stays open, unsaved changes included. Its tab, the Metadata path and the status bar show the new path, and Save writes to the new path. Moving a folder does the same for every open Script inside it.

Editing

Each open Script gets its own tab, titled with its file name and an asterisk while it has unsaved changes. The editor provides SQL syntax highlighting (a convenience only, whatever the file extension), line numbers, undo/redo (Ctrl+Z, Ctrl+Y), Find and Replace (Ctrl+F, Ctrl+H) and the normal editing behavior.

Every tab shows a close control ("x"), in addition to File > Close (Ctrl+W) and File > Close All. Closing a tab with unsaved changes always asks first: Save, Discard or Cancel. Save closes the tab only if the save succeeds. Discard throws the unsaved changes away. Cancel leaves the tab open.

Right clicking a tab offers Close, Close Other Tabs, Close Tabs to the Right, **Close Tabs to the Left and Close All Tabs**, always relative to the tab you right clicked, which need not be the active one. Each tab they close follows the same rule: a tab without unsaved changes closes at once, and each tab with unsaved changes asks Save, Discard or Cancel. Cancel keeps that tab open and the others still close. The same menu offers the Copy Path entries and Send to CLI for that tab's Script. Hovering a tab shows its Script's path.

New, New Folder, Rename, Duplicate, Delete

• New Script (toolbar, File menu, Scripts pane right click menu) opens a new tab, titled New Script 1, New Script 2 and so on, starting with -- @status: draft. Nothing is written until you save it: its first Save asks for its name, a path in the library, prefilled with the folder that was selected when you created it. If the last part of the name has no extension, .bsql is added; any extension you type is kept as typed, because the extension carries no meaning. Folders in the path are created as needed, and so is the library folder itself if it does not exist yet. Cancelling the name leaves the Script unsaved. A new Script closed without any change asks nothing. Rename, Duplicate, Delete, History, Copy Path and Send to CLI need a saved Script; Run on an unsaved Script offers Save and Run.
• New Folder (toolbar, File menu, Scripts pane right click menu) asks for the new folder's name and creates it in the place the dialog states, by the same rule wherever you start it: in the selected folder; beside the selected Script (in its folder, never under the file); at the top of the library when nothing is selected. A name with / creates nested folders.
• Rename changes a Script's name or folder. The Script keeps its identity and its full revision history. A folder is renamed from its right click menu; the Scripts inside keep their identity and history, and open tabs follow them. A folder can be deleted only when it is empty.
• Duplicate copies a Script's current content into a new, independent Script with its own fresh history.
• Delete asks for confirmation and moves the Script to the library's archives folder. This is the same operation as LIB DEL, so the Script can be restored with File > Recently Deleted..., LIB RESTORE or LIB UNDO.

Every path used here is confined to the Scripts Library: a name such as ../elsewhere/x.bsql, or one that starts in the reserved archives folder, is refused.

Metadata assistance

The Metadata tab, on the right, shows one field per metadata key BroadSQL uses, each label above its field: Description, Instance (Database Group), Environment, Tags and Status, each with a tooltip. It reloads from the active tab's current buffer whenever a different tab is selected, so it always reflects that tab's unsaved edits. Description shows a few lines so a longer text is easy to read, but it remains a single value: a line break typed or pasted into it becomes a space, and Enter commits it like in the other fields.

Instance (Database Group) and Environment are chosen from a list, not typed: the list holds every Database Group (or Environment) defined in your connection definitions, the same ones Save accepts, so a misspelled name can no longer be entered. Each selected value is shown in the field as a chip with a remove button (×).

• Click the field, start typing, or press Down to open the list. Each value has a check box, and ALL comes first. Typing filters the list (any part of the name, case ignored); clearing the filter shows the whole list again.
• Up and Down move through the list, Enter selects or unselects the highlighted value, Esc closes the list, and Tab moves to the next field. Backspace in the empty filter removes the last chip. Clicking a value selects or unselects it; clicking × on a chip removes it.
• Several values can be selected. ALL and specific values are exclusive: choosing ALL clears the specific values, and choosing a value clears ALL. No value selected means NONE.
• The list follows your other choice. Once Database Groups are selected, the Environment list shows first, under Used by the selected Database Groups, the Environments in which they have a connection, then every other Environment under Other Environments. Likewise, selected Environments put first the Database Groups that have a connection in them. This only orders the list: every value stays available, whatever you chose first.
• A value the Script already declares is shown as written, even one that is not defined (for example after a typing mistake made directly in the text); Save then reports it, as described in What Save checks.
• When no connection definitions are available, nothing can be listed: typing a name and pressing Enter adds it.

The Script's text is what is saved, and the tab and the text stay in step both ways:

• Editing a field changes only that field's metadata line in the text, in place: the same comment style, spacing and position. Every other line stays exactly as written: comments before, between and after the metadata, block comments, blank lines, the order of the metadata lines, and the SQL. A field that had no line gets one, after the last metadata line; clearing a field removes its line only.
• Metadata typed directly in the editor (for example changing -- @status: draft to -- @status: stable) shows in the Metadata tab when you save.

Below them, two read only values describe the file:

• Path: the Script's path in the Scripts Library, for example reports/QR13.sql. Hovering it shows the full path on disk. The copy button next to it copies the library path; right clicking the field or the button offers Copy Library Path, Copy Full Path and Copy CLI Command.
• Last modified: when the file was last written on disk, in the same format as History. It updates when the Script is saved.

There is no separate "Apply" step. Editing a field commits it into the text as soon as the field loses focus or Enter is pressed, and the tab becomes dirty like any other edit. Instance and Environment commit when their list closes, when a chip is removed, or when the field loses focus. The file itself is written only by Save. Leaving a field blank, or Instance or Environment with no value selected (NONE), removes its line. Selected values are written exactly as before, comma separated on one line, for example -- @environment: PROD,QA.

Scripts no longer have aliases: an @alias line in an older Script is an ordinary comment with no effect.

Formatting

Format (toolbar, or Edit > Format Document) reformats the current buffer. It never runs automatically on save. A Script can hold SQL, BroadSQL commands, or both, so Format never sends the whole text to the SQL formatter. It splits the text into statements using the very same rules that execution uses, then:

• leaves every BroadSQL command byte for byte untouched: @, LIB RUN, CONNECT, EXPORT, SHOW and every other command;
• reformats a statement only if it is SQL that the formatter accepts, changing only spacing and line breaks and keeping strings, comments and keyword casing as typed; a statement it cannot safely reformat is left unchanged with a note explaining why;
• keeps everything between statements, such as separators, comments and blank lines, exactly as written;
• declines to format at all if a quote or block comment is never closed, saying where, because statement boundaries cannot be trusted in that case.

The metadata header is never touched by Format. Edit > Format Selection formats the selected text with the same rules.

Save

Save (Ctrl+S) writes the current tab's content to its file. If nothing about the content, metadata or path changed since the last save, no new revision is recorded; if anything did, exactly one is recorded. A failed save leaves the tab exactly as dirty as it was.

The file is written back in the encoding it was read in (see Scripts Library: Encoding). If the text cannot be represented in that encoding, the save is refused and the file is left unchanged. New files are UTF-8 without a byte order mark.

If the file saves but recording the revision fails, the tab is still marked saved and a distinct warning says revision history could not be updated; it is caught up automatically the next time the Script is opened.

What Save checks

Save protects the metadata, not the SQL. Unfinished drafts save normally, and the SQL itself is checked by the database when the Script runs. LIB LINT reports unknown Database Groups or environments, invalid @params lines, leftover %1 to %9 parameters and ${name} written inside quotes, for saved Scripts. Save refuses metadata that would corrupt the library. When it refuses, nothing is written, the tab stays dirty, the Metadata tab is shown with the offending field focused, and the message says what is wrong:

A blank Instance or Environment (NONE) is always valid, and so is ALL. When no connection definitions are available, the Database Group and environment checks are skipped; the status check still applies. Status is a list: empty, draft, stable or deprecated. New Scripts start as draft.

Save All saves every tab with unsaved changes.

Run

Run (toolbar, F5, or Run > Run) executes the active, saved Script through the same execution pipeline as @script and LIB RUN script: the same parsing, arguments, nested Scripts, warnings and errors. Nothing about how a Script runs is special to the Editor.

Run executes on the database BroadSQL is currently connected to in the console, whatever the Script's @instance and @environment say: it never connects or switches by itself.

Run always executes what is saved on disk. If the tab has unsaved changes, or holds a new Script never saved, Run asks [Save and Run] [Cancel]; there is no option to run the in memory buffer, so BroadSQL never silently runs an older version.

If the Script declares arguments with a -- @params: line, Run first asks for each declared name in a small dialog, in declaration order. A field takes a number, a single-quoted string, TRUE, FALSE, NULL or one ${variable}; Run stays disabled until every field holds a valid value. The values are passed exactly as @script name=value passes them. A Script without @params runs directly, without a dialog. Cancelling the dialog cancels the run. The Metadata tab shows the declared parameters (Parameters), read only: edit the @params line in the text.

Run is available whenever a Script is open and BroadSQL has a database connection, whether or not the Script has unsaved changes; without a connection the button and menu item are disabled. Everything else in the Editor works with no connection. Run switches the right hand tabs to Output, shows Running '<name>'..., and once execution finishes the output appears there as plain text, as the command line would show it without colors: a statement that fails shows the database's error (connection, SQLState, error code, message and the position in the statement). The Output ends with the Script's status line, as in the console, and OUTPUT QUIET hides the same lines there. The status bar gives the status: Execution completed: SUCCESS., Execution completed with errors: COMPLETED_WITH_ERRORS, see Output., Execution failed: FAILED, see Output. or Execution cancelled: CANCELLED, see Output., and Run is available again in every case.

Run Selection (running only highlighted text) is not implemented in this release.

Copy Path and Send to CLI

A Script is identified by its path in the Scripts Library, such as reports/QR13.sql: the path LIB commands and @ use. Three copy actions put a form of it on the clipboard: Copy Library Path (reports/QR13.sql), Copy Full Path (the file's absolute path on disk) and Copy CLI Command (@reports/QR13.sql;). They are in the Edit menu, the tab and Scripts pane right click menus, and next to Path in the Metadata tab.

Send to CLI (Run > Send to CLI, or the tab and Scripts pane right click menus) writes the command that runs the Script on the BroadSQL prompt of the console the Editor was opened from, for example:

@reports/QR13.sql;

The command is not executed: switch to the console, check or edit it (for example add parameters), and press Enter. The Editor stays open. A path containing spaces is quoted, as the prompt expects: @"my reports/QR 13.sql";. The command always uses the Script's current path, after any rename or move. It runs the saved file, so save first to include unsaved changes; the status bar reminds you when the tab has any.

Send to CLI never replaces or extends what is on the prompt. It does nothing, and the status bar says why, when:

• the prompt already holds typed text;
• the prompt is in the middle of a statement not yet ended with ; (end it, or press Esc there);
• BroadSQL is running a command or asking a question;
• the console is the basic console (activatejline=OFF), which cannot receive text; use Copy CLI Command and paste it instead.

Automatic version history

Every successful save that changes a Script's content, metadata or path is recorded as a new revision, kept indefinitely as a complete snapshot. Renaming, and a metadata only change with no body change, each create their own revision too. Moving a Script or a folder records a revision with the new path for each Script moved.

History and Restore

History (toolbar, or History > History...) opens a window listing every revision of the active Script, newest first, with the current one marked. Selecting a revision shows its complete content, read only. The window stays open while you keep working.

Compare with Current and Compare with Previous open a read only side by side comparison of the selected revision against, respectively, the current one or the one before it. It shows a summary count of additions, deletions and modifications; both versions scrolled together with changes colored and the changed part of a modified line highlighted; Previous Change and Next Change buttons; a metadata section whenever a metadata field differs; and a path banner whenever the name or location differed.

If a file changed outside BroadSQL while a tab has unsaved edits, the conflict prompt (see "External modification detection") offers Compare too.

Restore Selected... restores the selected revision's content into the Script at its current path (a historical name is never silently reapplied). Restoring never rewrites or removes any revision: restoring an old revision at v12 creates v13 from its content, and v9 through v12 stay exactly as they were.

External modification detection

BroadSQL notices when a file was changed outside itself, on Refresh, when the Editor window is reopened after being hidden, and right before Save or Run. A tab with no unsaved changes is reloaded silently. A tab with unsaved changes is never overwritten without asking:

'customer.bsql' was changed outside BroadSQL, and this tab has unsaved changes.

[Compare] [Reload External Version] [Keep Editor Version] [Cancel]

Compare shows the on disk version against the unsaved buffer, then asks again. Keeping the editor version means the next Save overwrites the external change; reloading discards the unsaved edits. If the file was deleted outside BroadSQL, BroadSQL says so and Save simply recreates it.

Deletion and recovery

There is one deletion model for the whole Scripts Library: a Script is moved to the archives folder and nothing is purged automatically. File > Recently Deleted... is a view of that same archive, newest first, with a Restore button that moves the Script back to its original path. Restore refuses, rather than overwrite, a Script that exists there again. LIB LIST ARCHIVES, LIB RESTORE and LIB UNDO show and restore the same archive from the command line.

Revision history follows the archive. Restoring an archived Script continues its revision history. A brand new file created at the same path after a deletion starts a new history and never inherits the old one. History recorded by an earlier release under the previous library locations is not carried over.

Differences from earlier releases

The Scripts Library replaces the former SQL library and Scripts catalogs. BroadSQL does not migrate anything from them; the differences are deliberate:

What is not yet available

Run Selection (see above) is the one part of this feature not implemented in this release.

About

Help > About BroadSQL Editor shows the BroadSQL version, the copyright, and a Documentation link to the documentation home page.

Related pages

• Scripting overview: what a Script is, and the other Scripting pages.
• Scripts Library: the metadata header, LIB commands, archive and LIB LINT.
• Running Scripts: what Run does, the same as @ and LIB RUN.