BroadSQL BroadSQL Downloads
Documentation / Scripting: Running Scripts

Running Scripts

Run a Script with @, the preferred short form, or with LIB RUN, which only runs Scripts of the library:

@maintenance/cleanup.bsql
LIB RUN maintenance/cleanup.bsql
@./helper.bsql
@C:\temp\foo.bsql
@reports/customer.bsql customer_id=42 country='FR'
@"C:\My Scripts\foo.bsql" since=${last_run}
LIB RUN "folder/my script.bsql" region='EU' year=2026

How a reference is resolved

How a reference is resolved depends only on its form, never on a search:

ReferenceMeaning
@foo.bsqlfoo.bsql in the Scripts Library root.
@maintenance/foo.bsqlmaintenance/foo.bsql under the Scripts Library. It is not relative to the working directory.
@./foo.bsqlTyped at the prompt: relative to BroadSQL's working directory. Written inside another Script: relative to the folder that contains the Script currently running.
@C:\temp\foo.bsql, @/tmp/foo.bsqlAn explicit path to a Script outside the library. Any absolute path in the form of your operating system works, including a Windows UNC path.
LIB RUN foo.bsqlThe same as @foo.bsql: the Scripts Library only.
  • A plain reference such as @common/util.bsql always starts at the library root, even inside another Script. @./helper.bsql means "next to this Script", so a folder of Scripts can be moved as a bundle.
  • LIB RUN runs Scripts of the library and nothing else. It rejects an absolute path, a ./ path and any path that would leave the library, such as ../elsewhere/x.bsql. Use @ with an explicit path for a Script stored elsewhere. Plain references made with @ are held inside the library in the same way.
  • Nothing is searched: there is no file name search across subfolders, no shorthand and no fallback folder. The name you write is the path that is used.
  • Path forms follow your operating system. On Windows both \ and / separate folders and .\ is an explicit relative reference. On Linux and macOS a backslash is an ordinary file name character.
  • archives/ at the top of the library is reserved for archived Scripts and cannot be run.
  • Quote a reference that contains spaces.

If a Script cannot be run, the message names the path that was actually used and says why: not found, a directory instead of a file, unreadable, not a text file, a path that leaves the library, or a library folder that is missing or is a file.

What happens while it runs

A statement ends at ; and may span several lines. Line comments (--) and block comments (/* ... */) are ignored; a ; or a comment marker inside a quoted string is ordinary text. Each statement is echoed before it runs.

A Script that cannot be run as a whole is refused before anything executes and before any argument is assigned: unreadable content, a quote or block comment that is never closed (the message gives the line and column), no statement, a Script already running in the current chain, nesting deeper than 32 levels, an invalid -- @params: line, a declared argument that the call does not pass, or an invalid ON ERROR or OUTPUT statement.

BroadSQL splits statements only at ;. A procedural SQL block that contains ; is therefore still split at each inner ;.