BroadSQLApplication settings
BroadSQL reads its configuration from a single settings file at startup: conf/BroadSQL.ini on Windows, conf/broadsqlux.ini on Linux (see Installation). This page documents every setting in that file.
File format
- One setting per line:
Key=Value. Values are used exactly as typed, no quoting. - Lines starting with
;are comments. - Folder paths use a doubled backslash on Windows (
C:\\temp\\, notC:\temp\) and must end with the path separator. - The
[General]and[Log]headers are organizational only, to group related settings for the reader; they don't scope or namespace the keys underneath them. A key works the same regardless of which header (or no header) it sits under. - Every setting below is required (BroadSQL fails to start with a
Could not resolve placeholdererror if a required key is missing or misspelled, or with the same kind of error if a value has the wrong type, e.g. non-numeric text for a numeric setting), exceptDefaultFileFormat,CsvSeparator,DefaultEnvironment,ServersFileType,TemporaryFolder, andScriptsLibrary, which can be left out entirely: see their rows below for what happens when they are.
[General]
| Key | Default (shipped) | Purpose |
|---|---|---|
ServersFileName | ./conf/ConnectionsDefinitionFile.cdf (Win) | Path to the Connections Definition File (CDF), the encrypted H2 database that stores your saved connections. Extra H2 connection parameters can be appended after a ; (the shipped Windows file adds ;TRACE_LEVEL_SYSTEM_OUT=0 to silence H2's own console trace output). |
DefaultFolder | c:\\temp\\ (Win) / a path under your BroadSQL install (Linux) | Destination folder for EXPORT (when the file name has no directory part) and DUMP (always). See Export. |
DefaultExtFileName | results.xlsx | Present in the shipped file for historical reasons but not currently used by any command: the actual export file name always comes from the query/table name, never from this setting. |
CustomExtensionsFolder | extensions | Folder scanned at startup for JAR files containing custom commands. See Extending BroadSQL. |
FieldsSeparator | \t (tab) | Column separator used when exporting to a plain-text (.txt, or any extension other than .xlsx/.ods/.csv/.mdb) file with EXPORT/DUMP, and on the initial screen display. Changeable mid-session with SET SEPARATOR (does not persist back to the INI file). Does not affect .csv exports (always a comma) via EXPORT/DUMP, and does not affect PULL ... AS CSV/TXT at all: see Export and PULL. |
ScreenSeparator | | (pipe) | Column separator used when displaying query results on screen (independent of FieldsSeparator). For a literal space, use \u0020. |
CsvSeparator | ; (semicolon) | Field separator used by PULL ... AS CSV and LOAD (a single character, e.g. ; or ,), independent of FieldsSeparator/SET SEPARATOR. Optional: if the key is absent, or empty, PULL ... AS CSV uses ;. PULL ... AS TXT always uses a tab, regardless of this setting. See PULL. |
DefaultEnvironment | DEV | Recognized and validated at startup (free text, e.g. DEV, QA), but currently has no effect on any command: PULL ... AS H2's auto-created connections are registered in the built-in LOCAL environment instead, regardless of this setting. Optional: if the key is absent, or empty, BroadSQL prints an INFO message once at startup and falls back to DEV. Kept for a future feature that may need it. See PULL. |
MaxRowsOnScreen | 100 | Maximum number of rows printed to the screen for a query (0 = no limit). Does not limit EXPORT or DUMP, which always write every row. |
Autocommit | false | Default autocommit mode for new connections. Changeable mid-session with SET AUTOCOMMIT. |
MaxRowXLSX | 500000 | Row-count threshold used only by DUMP to decide its output format: at or below this count (or when the count can't be determined), DUMP uses the format from DefaultFileFormat below; above it, DUMP always writes a tab-separated .txt file instead, regardless of DefaultFileFormat. Does not apply to EXPORT (see Export for EXPORT's own, higher, safety cap). |
DefaultFileFormat | (not required, see below) | Default export format for EXPORT (when the file name has no extension) and for DUMP (at or below MaxRowXLSX). One of XLSX, ODS, CSV, TXT (not case-sensitive). Optional: if the key is absent, or its value isn't one of those four, BroadSQL prints an INFO message once at startup and falls back to ODS; it does not fail to start. Full details in Export. |
ScriptsLibrary | scripts | The Scripts Library: the one folder of reusable Scripts, run with @name or LIB RUN name and managed with the LIB commands and the BroadSQL Editor. A relative path is looked up as given, then under your BroadSQL install folder. Optional: if the key is absent, or empty, BroadSQL prints an INFO message once at startup and uses scripts. The folder must exist to run or list Scripts (the Editor creates it with the first new Script), and it must be a folder, not a file. See Scripts and the Scripts Library. |
JsScripts | jsscripts | Folder holding saved JS scripts, managed with JS LIST/JS RUN/JS FIND. The experimental JavaScript commands are separate from the Scripts Library and never use it. A .js file must be run with its extension (JS RUN name.js). Optional: if the key is absent, or empty, BroadSQL prints an INFO message once at startup and falls back to jsscripts. See Light scripting with JS. |
WinEditPlus | (empty) | Read at startup but not currently used: the EDIT command opens the BroadSQL Editor regardless of this value. |
activatejline | OFF | Enables JLine interactive shell enhancements: Up/Down/Ctrl-R command history, line editing, and TAB completion for BroadSQL commands, SQL keywords, RUN/CONNECT API/SYNTAX/HELP, and (once connected) database schema/table/view/column names. ON or OFF, not case-sensitive. Never changes what a command does or accepts: every command behaves identically whether ON or OFF; only interactive editing/completion conveniences differ. Optional: if the key is absent, or anything other than ON, falls back to OFF. If activatejline=ON but JLine fails to initialize for any reason, BroadSQL prints one warning and falls back to the standard console rather than failing to start. See Getting started for TAB completion and Universal API Client for the API-specific completion. |
jlinehistoryfile | (empty) | Where JLine's persistent command history (Up/Down, Ctrl-R across sessions) is stored, only meaningful when activatejline=ON. Deliberately per OS user, never install-relative: a shared BroadSQL install must not mix or leak one OS user's typed commands into another's history. Optional: if the key is absent, or empty, history is stored at %USERPROFILE%\.broadsql\history on Windows ($HOME/.broadsql/history on Linux/macOS), created on demand. An absolute path here is used exactly as given. A relative path (e.g. jlinehistoryfile=myhistory) resolves under that same per-user .broadsql directory (%USERPROFILE%\.broadsql\myhistory); it is never resolved against the BroadSQL install directory, the folder you started BroadSQL from, or the folder containing this INI file. If the resolved location can't be created or written, BroadSQL prints one warning and falls back to in-memory-only history for that session (Up/Down/Ctrl-R still work within the session; nothing is saved for next time) rather than failing to start. A password is never written to history, in memory or on disk; the literal command you typed is stored, never a ${ENV:...}/VAR/:name reference's resolved value. See Universal API Client. |
apiproxymode | NONE | Enterprise HTTP/HTTPS proxy for API execution (RUN/CONFIG API) only; never affects any other BroadSQL networking (database connections, etc.). NONE: no proxy. SYSTEM: use the operating system's own proxy configuration (Windows/JVM system proxy discovery), with no host/port needed below; note this mode sets a JVM-global property, so it is not strictly scoped to API traffic the way NONE/MANUAL are, though nothing else in BroadSQL currently makes outbound HTTP calls for this to affect. MANUAL: use the explicit apiproxyhost/apiproxyport (and optional apiproxytype/apiproxynonproxyhosts/credentials) below. See Universal API Client. |
apiproxytype | HTTP | MANUAL mode only: HTTP or SOCKS. |
apiproxyhost | (empty) | MANUAL mode only: proxy host name or address. |
apiproxyport | (empty) | MANUAL mode only: proxy port. |
apiproxynonproxyhosts | (empty) | MANUAL mode only: pipe-separated hosts that bypass the proxy (* is a wildcard), e.g. localhost|127.*|*.corp.local. |
apiproxyusername | (empty) | MANUAL mode only, optional proxy authentication. An environment-variable reference is strongly preferred over a literal value: ${ENV:NAME} (BroadSQL's own environment-variable syntax, e.g. apiproxyusername=${ENV:BROADSQL_PROXY_USER}), never logged. |
apiproxypassword | (empty) | MANUAL mode only, optional proxy authentication, using the same ${ENV:NAME} convention as apiproxyusername above, never logged. |
ServersFileType (conf/broadsqlux.ini only) | H2 | (optional, has no effect whether present or absent) Present in the shipped Linux file but not currently used: the CDF is always treated as H2 regardless of this value. |
TemporaryFolder (conf/broadsqlux.ini only) | a path under your BroadSQL install | (optional, has no effect whether present or absent) Present in the shipped Linux file but not currently used by any command. |
Obsolete settings
The former SqlLib, Scripts and ListSubfolders settings no longer exist. BroadSQL does not read them, does not migrate them and does not warn about them: a file that still contains them starts normally and they have no effect. Set ScriptsLibrary instead, and move your files by hand as described in the release notes. LIB LIST always lists Scripts in subfolders, so ListSubfolders is not needed.
[Log]
See Command activity log for full details, including file naming, rollover, and SET TRACE.
| Key | Default (shipped) | Purpose |
|---|---|---|
IsLogActivated | FALSE | Master switch for the per-connection activity log. |
LogFolderName | C:\\BroadSQL\\logs (Win) | Folder the activity log is written to. Must already exist. |
LogFileNamePattern | CONSOLE | File name prefix for the activity log. |
Changing settings
Edit the file with a text editor and restart BroadSQL: settings are only read at startup. A few settings also have a runtime command that changes the current session only, without touching the file: SET SEPARATOR (FieldsSeparator), SET AUTOCOMMIT (Autocommit), SET TRACE (IsLogActivated, hidden command). Everything else, including DefaultFileFormat, DefaultFolder, and MaxRowXLSX, can only be changed by editing the file.