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

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

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 left hand panel is the Scripts Library as a tree: folders, subfolders and Scripts, rooted at the configured folder. 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. A Search field filters by path or @description. Double clicking a Script, or selecting it and choosing Open, opens it in an editor tab. Refresh rescans the folder, keeps the folders you had expanded open, and never touches a tab with unsaved changes.

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.

New, New Folder, Rename, Duplicate, Delete

• New asks for a name, which is a path in the library, and creates the Script. 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. A new Script starts with -- @status: draft. If the library folder does not exist yet, New creates it. With a folder selected in the tree, the name is prefilled with that folder.
• New Folder creates an empty folder.
• Rename changes a Script's name or folder. The Script keeps its identity and its full revision history. A folder can be renamed when no Script is open in a tab, and 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 bottom "Metadata" tab shows one field per metadata key BroadSQL uses: 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.

There is no separate "Apply" step. Editing a field commits it into the metadata header as soon as the field loses focus or Enter is pressed, and the tab becomes dirty like any other edit. Every other header line, including an explanatory comment or a line BroadSQL does not use (such as an old @alias), is left exactly as it was. The file itself is written only by Save. Leaving Instance or Environment blank clears the tag.

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

Formatting

Format (button, 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.

Validation

Validate (button, or Edit > Validate) checks the current buffer without executing or changing it. It reports:

• a metadata header line that looks like a tag (-- @key) but is missing its : value;
• the checks LIB LINT performs for a saved Script (an @instance or @environment id that matches no known Database Group or environment, and non contiguous %N parameters), run against the unsaved buffer, for every Script;
• a quote or block comment that is never closed, with the line and column where it starts, found by the same statement rules that execution uses.

Clicking Validate switches the bottom tab strip to "Validation Results"; selecting a result with a known line moves the cursor there. The status bar says Script is valid. or Script is invalid: N errors.

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 the encoding notes in Scripts and the Scripts Library). 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; Validate is the deeper check. 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 with Comment performs the same save and attaches an optional comment to the revision. Save All saves every tab with unsaved changes.

Run

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

Run always executes what is saved on disk. If the tab has unsaved changes, 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 uses %1, %2 and so on, Run first asks for each value in a small dialog; cancelling it cancels the run.

Run needs an active database connection; without one the button and menu item are disabled. Everything else in the Editor works with no connection. Clicking Run switches the bottom tab strip to "Execution Output", shows Running '<name>'..., and once execution finishes the output appears there exactly as the command line would show it, with Execution completed. or Execution failed. in the status bar.

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

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.

History and Restore

History (button, 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.