Application 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\\, not C:\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 placeholder error if a required key is missing or misspelled) except DefaultFileFormat, CsvSeparator, DefaultEnvironment, ScriptsLibrary, JsScripts, activatejline, jlinehistoryfile, color, theme, displaymode, scripthistoryvault, the apiproxy* family, FieldsSeparator, ScreenSeparator, MaxRowsOnScreen, MaxRowXLSX, Autocommit, and IsLogActivated, which can all be left out entirely: see their rows below for what happens when they are. A present but invalid value (wrong type, or not one of a setting's allowed values) never stops BroadSQL from starting either, for any setting in this file: BroadSQL prints a one-time startup message identifying the setting and falls back to its documented default, and only functionality that genuinely depends on that specific setting is affected. For MaxRowXLSX, DefaultFileFormat and CsvSeparator, the export forms that depend on the invalid value refuse to run, with an error naming the setting, rather than silently guessing; see their rows below.

`[General]`

Key	Default (shipped)	Purpose
`ServersFileName`	`./conf/ConnectionsDefinitionFile.cdf;TRACE_LEVEL_SYSTEM_OUT=0` (Win) / `file:./conf/ConnectionsDefinitionFile.cdf` (Linux)	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) / `/home/myuser/broadsql/temp` (Linux, replace with a folder of your own)	Folder where `DUMP` writes its files, and where `REPEAT ... TO <file>` writes a file given without a folder. See Export.
`DefaultExtFileName`	`results.xlsx`	Name (without its extension) of the file `DUMP /` and `DUMP (<query>)` write when `TO <destination>` is omitted: `results` by default. See Export.
`CustomExtensionsFolder`	`extensions`	Folder scanned at startup for JAR files containing custom commands, on Windows and Linux alike. A relative path is relative to the installation folder, where the launchers start BroadSQL. The launchers put `extensions/*` on the Java classpath, so keep `extensions` unless you also change the launcher. Empty: no folder is scanned and no custom command is registered. See Extending BroadSQL.
`FieldsSeparator`	`\t` (tab)	Column separator of the plain-text output of compatibility commands kept for scripts from earlier releases. It has no effect on `DUMP` (or `PULL`): `AS CSV` uses `CsvSeparator` and `AS TEXT` always uses a tab. Optional: if the key is absent, or its value is not exactly one character, BroadSQL prints an `INFO` message once at startup and falls back to `\t`.
`ScreenSeparator`	`\|` (pipe)	Column separator used when displaying query results on screen (independent of `FieldsSeparator`): it separates the columns and starts and ends every line of the table, including the border lines. For a literal space, use `\u0020`. Optional: if the key is absent, or its value is not exactly one character, BroadSQL prints an `INFO` message once at startup and falls back to the pipe character.
`CsvSeparator`	`SEMICOLON`	Field separator of the CSV export format (`DUMP ... AS CSV`, and the monitoring file of `REPEAT ... TO <file> AS CSV`) and of the CSV files read by `LOAD`: `COMMA` or `SEMICOLON` (not case-sensitive; the characters `,` and `;` are accepted too). No other separator is supported: with any other value, BroadSQL prints an `INFO` message at startup and `AS CSV` fails with a configuration error until the value is corrected. `AS TEXT` always uses a tab and `AS JSON` has no separator, whatever this setting says. Optional: if the key is absent or empty, `SEMICOLON` is used. See Export.
`DefaultEnvironment`	`DEV`	Recognized and validated at startup (free text, e.g. `DEV`, `QA`), but currently has no effect on any command: H2 databases created by `DUMP ... AS H2` 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 Export.
`MaxRowsOnScreen`	`100`	Maximum number of rows printed to the screen for a query (`0` = no limit). `DUMP <table>` and `DUMP (<query>)` always write every row; `DUMP /` exports only a result that was displayed in full, so it refuses a result cut at this limit. Optional: if the key is absent, or not a valid integer, BroadSQL prints an `INFO` message once at startup and falls back to `100`.
`Autocommit`	`false`	Default autocommit mode for new connections. Changeable mid-session with `SET AUTOCOMMIT`. Optional: if the key is absent, or not exactly `true`/`false`, BroadSQL prints an `INFO` message once at startup and falls back to `false`.
`MaxRowXLSX`	`500000`	Row-count threshold used only by `DUMP <table>` alone (no `TO`/`AS`) to decide its output format: at or below this count (or when the count cannot be determined), it uses the format from `DefaultFileFormat` below; above it, it always writes a tab-separated `.txt` file instead. Optional: if the key is absent, BroadSQL prints an `INFO` message once at startup and falls back to `500000`. If it is present but not a valid integer (e.g. `MaxRowXLSX=format`), BroadSQL still starts and every unrelated command keeps working, but `DUMP <table>` alone refuses to run, with a clear error naming `MaxRowXLSX` and its invalid value, until the setting is corrected.
`DefaultFileFormat`	`ODS`	Default export format of `DUMP` (and its alias `PULL`) when `AS <format>` is omitted. One of `XLSX`, `ODS`, `CSV`, `TXT` (the TEXT format; not case-sensitive). Optional: if the key is absent, BroadSQL prints an `INFO` message once at startup and uses `ODS`. If its value isn't one of those four, BroadSQL prints an `INFO` message at startup and `DUMP` refuses the forms that rely on this default with a configuration error (`DUMP <table>` alone falls back to `ODS`); an explicit `AS <format>` always works. 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 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 JavaScript scripting.
`WinEditPlus`	(empty)	Read at startup but not currently used: the `EDIT` command opens the BroadSQL Editor regardless of this value.
`activatejline`	`ON`	The JLine interactive console, BroadSQL's standard console: command history (Up/Down, Ctrl+R), line editing and keyboard shortcuts, TAB completion (commands, SQL, database objects, stored names, APIs, file paths), colors (`color`, `theme`) and a table layout that follows the window width (`displaymode`). `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. `OFF` explicitly selects the basic operating-system console instead, without these features. Optional: if the key is absent, it defaults to `ON`; any value other than `ON` or `OFF` also uses `ON`, and BroadSQL reports it once at startup. If JLine fails to initialize for any reason, BroadSQL prints one warning and falls back to the standard console rather than failing to start. See Interactive console for the keyboard shortcuts, TAB completion, history, colors and table layout.
`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.
`color`	`AUTO`	Terminal colors: syntax highlighting of what you type, colored `ERROR`/`WARNING`/`INFO` and success messages, and a colored prompt. `AUTO` uses colors only when the console is the JLine terminal and it reports color support; never with `activatejline=OFF`, and never when output is redirected to a file or a pipe. `ON` always emits colors, even when the terminal does not report support. `OFF` never does. Not case-sensitive. Colors only change how text looks: the text itself, what is written to log files, exports and command behavior are identical whatever the value. Optional: if the key is absent, or not one of these values, `AUTO` is used and BroadSQL reports it once at startup. See Interactive console.
`theme`	`default-dark`	The color theme used when colors are on (see `color`): `default-dark` (for dark backgrounds), `default-light` (for light backgrounds), `classic` (traditional red, yellow and green messages and bold keywords, readable on any background), `high-contrast-dark`, `high-contrast-light`, `mono` (bold, underline and inverse only, no colors) or `none`. `none` keeps the appearance BroadSQL had before themes existed: no syntax highlighting, plain prompt and messages, and JLine's own completion menu colors. Not case-sensitive. Optional: if the key is absent, or names no built-in theme, `default-dark` is used and BroadSQL reports it once at startup. See Interactive console.
`displaymode`	`AUTO`	Layout of result tables (query results and the grids of commands such as `SHOW TABLES`, `SHOW FK` or `LIB LIST`) for the terminal width. `NORMAL` is the established layout: each column as wide as its header and declared size, values never shortened. `COMPACT` fits the table to the terminal: the widest columns are narrowed and longer values are shortened on screen with a trailing `~`; when even that cannot fit, each row is shown vertically, one `COLUMN: value` line per column. `WIDE` keeps the `NORMAL` widths and adds a space on each side of the column separators. `AUTO` reads the actual terminal width before each table: `COMPACT` below 80 columns, `WIDE` from 160 columns, `NORMAL` in between, and `NORMAL` when the width is unknown (`activatejline=OFF`, redirected output); resizing the window applies to the next table. Display only: the values kept for `<@last:...>` and `DUMP /`, and every export, are never shortened. Independent of `theme`. Not case-sensitive. Optional: if the key is absent, or not one of these values, `AUTO` is used and BroadSQL reports it once at startup. See Interactive console.
`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.
`scripthistoryvault`	(empty)	Where the Script Library's filesystem revision vault (version history for edited Scripts) stores its index and per-asset revisions. Same per-OS-user, never-install-relative resolution rules as `jlinehistoryfile` above, except the default subfolder is `script-history` instead of `history`. Ships as a commented-out example (`;scripthistoryvault=`): uncomment and set only if you need it somewhere other than the default location. Optional: if the key is absent, or empty, it is stored at `%USERPROFILE%\.broadsql\script-history` (Windows) / `$HOME/.broadsql/script-history` (Linux/macOS).

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.

prompt.text, ServersFileType and TemporaryFolder (all conf/broadsqlux.ini only) were never read by any current BroadSQL code either and have been removed from the official Linux template. The same "starts normally, has no effect" rule applies if your own file still has them.

`[Log]`

See Command activity log for full details, including file naming, rollover, and SET TRACE.

Key	Default (shipped)	Purpose
`IsLogActivated`	`FALSE` (Win) / `TRUE` (Linux)	Master switch for the per-connection activity log. The Linux template turns it on, since Linux installations are more often run unattended, where a log from the first run is useful. Optional: if the key is absent, or not exactly `true`/`false`, BroadSQL prints an `INFO` message once at startup and falls back to `false` on both platforms.
`LogFolderName`	`C:\\BroadSQL\\logs` (Win) / `logs` (Linux)	Folder the activity log is written to, with or without a trailing separator. A relative path is relative to the installation folder: `logs` is the installation's own `logs` folder. 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 AUTOCOMMIT (Autocommit), SET TRACE (IsLogActivated, hidden command). Everything else, including DefaultFileFormat, CsvSeparator, DefaultFolder and MaxRowXLSX, can only be changed by editing the file.