How do I organize my saved queries so that I can find them again?

Applies to BroadSQL 5.5.0 · reviewed October 18, 2026

What you'll accomplish

Saved queries pile up: a folder of .sql files with names that made sense the day they were written, copies of copies, and no way to tell which file needs which values. Finding the right one takes longer than writing it again, and running the wrong one is easy.

You will give your Scripts folders, a one line description and a few tags, then find them by subject, see what each one expects before running it, and let BroadSQL point out duplicates and mistakes. With the four WORLD Scripts of this page, LIB TREE ALL; shows every Script with its description, and LIB FIND languages; finds the one about languages in one command.

Short answer

Keep Scripts in subfolders of the Scripts Library, start each one with -- @description: and -- @tags: lines, then use LIB TREE ALL;, LIB FIND <word>;, LIB SHOW <script>; and LIB LINT;.

Before you start

The Scripts Library is the scripts folder of your installation. The example uses four Scripts for the WORLD sample, in two folders. Two of them come from earlier how-tos; if you have not saved them yet, save all four now.

1. One folder per subject, one description and a few tags per Script

The header lines at the top of a Script are comments for the database, and metadata for BroadSQL: @description is shown when you browse, @tags are words you search for, @status marks a Script as draft, stable or deprecated. Save the first Script with its header:

-- @description: Largest countries of a continent
-- @tags: world, population
-- @param continent TEXT "Continent, as in COUNTRY.CONTINENT"
-- @param min_population INTEGER = 50000000 "Smallest population listed"
SELECT CODE, NAME, POPULATION
  FROM COUNTRY
 WHERE CONTINENT = ${continent} AND POPULATION >= ${min_population}
 ORDER BY POPULATION DESC;

The second one looks countries up by code:

-- @description: Countries by ISO code
-- @tags: world, lookup
-- @param codes LIST OF TEXT "Three-letter country codes"
SELECT CODE, NAME FROM COUNTRY WHERE CODE IN (${codes}) ORDER BY CODE;

The third one lists the official languages of a list of countries:

-- @description: Official languages of a list of countries
-- @tags: world, languages
-- @param codes LIST OF TEXT "Three-letter country codes"
SELECT COUNTRYCODE, LANGUAGE FROM COUNTRYLANGUAGE
 WHERE ISOFFICIAL = 'T' AND COUNTRYCODE IN (${codes})
 ORDER BY COUNTRYCODE, LANGUAGE;

The fourth one, about cities, goes in its own folder and is still a draft:

-- @description: Largest cities of a list of countries
-- @tags: world, population
-- @status: draft
-- @param codes LIST OF TEXT "Three-letter country codes"
-- @param min_population INTEGER = 1000000 "Smallest city population listed"
SELECT CI.NAME AS CITY, CO.NAME AS COUNTRY, CI.POPULATION
  FROM CITY CI JOIN COUNTRY CO ON CI.COUNTRYCODE = CO.CODE
 WHERE CO.CODE IN (${codes}) AND CI.POPULATION >= ${min_population}
 ORDER BY CI.POPULATION DESC;

2. See the whole library at a glance

LIB TREE shows the folders, how many Scripts each holds, and each Script with its description. ALL includes Scripts tagged for other Database Groups and environments:

LIB TREE ALL;

With only these four Scripts in the library, the tree looks like this:

WORLD> LIB TREE ALL;
Scripts Library tree (every Database Group/environment, 4 Scripts):
cities/ (1)
  big-cities.sql  [draft] Largest cities of a list of countries
countries/ (3)
  by-codes.sql            Countries by ISO code
  largest.sql             Largest countries of a continent
  official-languages.sql  Official languages of a list of countries

3. Find a Script by subject

LIB FIND searches the full text of every Script, header included, so a word of a description or a tag is enough. This finds countries/official-languages.sql:

LIB FIND languages;

To see the library grouped by tag, LIB LIST ALL BY TAG; lists the Scripts under world, population, lookup and languages; a Script with two tags appears in both groups.

4. Check what a Script expects before running it

LIB SHOW prints the Script and its parameters, so you know which values to pass and which have a default:

LIB SHOW cities/big-cities.sql;

It shows codes, a required list of texts, and min_population, an integer that defaults to 1000000. Run it with those values:

@cities/big-cities.sql codes=('FRA', 'DEU');

5. Let BroadSQL check the library

LIB LINT reads every Script and reports what looks wrong, without changing anything: a @param line it cannot read, a parameter declared and never used, a ${name} that nothing defines, and two Scripts with the same SQL apart from layout, comments and letter case. To try it, make a copy of a Script under another name, then run:

LIB LINT;

The report names the two Scripts with the same SQL. Remove the copy with LIB DEL <script>;: BroadSQL asks for a confirmation and moves it to the archives/ folder of the library, and LIB UNDO; brings it back.

Variations

• Only the Scripts for this connection: LIB LIST; without ALL hides the Scripts tagged with @instance or @environment for another Database Group or environment.
• By folder or by status: LIB LIST ALL BY FOLDER;, LIB LIST ALL BY STATUS;.
• Edit in a window: EDIT countries/largest.sql; opens the BroadSQL Editor, with the library as a tree.
• Start from ready-made Scripts: the Scripts Gallery offers Scripts with complete headers.

Watch out

• Running, showing and editing always use the exact path (countries/largest.sql). Only LIB LIST and LIB FIND accept part of a name.
• Metadata describes a Script, never enforces anything: a draft Script runs like any other.
• Tags are free text: agree on a few words with your team, or each person will search for different ones.

Related

• Scripts Library
• Save a query and run it by name
• LIB FIND, LIB TREE, LIB LINT

Commands used

• LIB TREE
• LIB FIND
• LIB LIST
• LIB SHOW
• LIB LINT
• LIB DEL
• LIB UNDO

Found something wrong or unclear on this page? Tell us, with the page address.