The configuration database (CDF) and maintenance mode

The CDF (Connections Definition File) is the encrypted H2 database where BroadSQL keeps its configuration: your connections and their passwords, Database Groups, Environments, login scripts, database types and the API catalog. You manage it with CONFIG and the connection commands. You never need to connect to it to change your configuration.

This page explains how BroadSQL protects the CDF, how it upgrades it when you install a new release, and the advanced CDF maintenance mode for diagnosis and repair.

Key terms

Managing your configuration

Use these, from any prompt (BroadSQL>, a connection, or maintenance mode). They read and save the CDF directly, without touching your current database connection:

• CONFIG (Windows): connections, Database Groups, Environments, login scripts.
• CONFIG API (Windows): the API catalog.
• ADD CONNECTION, EDIT CONNECTION, DEL CONNECTION, and the Database Group, Environment and login script commands, on every platform.
• SHOW ALL CONNECTIONS, SHOW CONNECTION, SHOW ALL GROUPS, SHOW ALL ENVIRONMENTS.

BroadSQL> CONFIG;
BroadSQL> SHOW ALL CONNECTIONS;
BroadSQL> CONNECT WORLD;
WORLD> CONFIG;

Why the CDF is protected

The CDF holds every database password you saved. A damaged CDF stops BroadSQL from loading your connections. For these reasons, BroadSQL treats it as a private system database:

• BroadSQL never connects to it at startup, and DISCONNECT never returns to it.
• No ordinary connection can open it, whatever its name. A connection whose URL points to the CDF file (another name, a relative path, .., a different letter case, a symbolic link, a junction or a hard link) is refused. So is a copied or renamed CDF: BroadSQL recognizes a CDF by its content, not only by its file name.
• Such a connection cannot be saved either: CONFIG and ADD CONNECTION refuse a URL that opens the CDF.
• The commands that write somewhere refuse the CDF as their destination: DUMP and PULL AS H2, EXPORT to one of its files, REPEAT ... TO one of its files, and LINK TABLE of a CDF table. PING, COMPARE TABLE STRUCTURE and a JavaScript connect() refuse it as well.

A refusal looks like this, and nothing is opened or written:

WORLD> CONNECT MYCDF;
ERROR: CONNECT refused: connection 'MYCDF' opens the BroadSQL configuration database (CDF).
The CDF cannot be used as an ordinary connection. Use CONNECT $CDF for maintenance.

WORLD> CONNECT OLDCOPY;
ERROR: CONNECT refused: connection 'OLDCOPY' is a BroadSQL configuration database (CDF).
CDF databases cannot be opened as ordinary connections.

What the protection covers, and what it does not

BroadSQL applies these checks to everything BroadSQL itself opens or writes: connections, test connections, export destinations, linked tables and monitoring files. Three kinds of access are outside its reach:

Reading the CDF's content without BroadSQL needs the master password, because the file is encrypted. Anyone who can write the file can still damage it: protect the conf folder with your operating system's permissions and keep backups.

CDF maintenance mode

Maintenance mode is a direct SQL session on the CDF, for diagnosis, repair, recovery, and configuration created by older releases. It is an advanced operation: prefer CONFIG and the commands above for every normal change.

Before you start

• Back up the CDF: copy conf/ConnectionsDefinitionFile.cdf.mv.db while BroadSQL is closed.
• Know the master password. There is no separate maintenance password.

Entering and leaving maintenance mode

1. Type CONNECT $CDF; at the prompt. BroadSQL asks for the master password, every time:

``` BroadSQL> CONNECT $CDF; CDF maintenance: enter the BroadSQL master password. [Enter password]

WARNING: CDF MAINTENANCE MODE You are connected directly to the BroadSQL configuration database. Direct changes can make your configuration unusable. Use CONFIG and the connection commands for normal changes. Back up the CDF before changing it. DISCONNECT leaves maintenance mode.

$CDF [MAINTENANCE]> ```

1. Run SQL. Reads and writes are allowed:

``` $CDF [MAINTENANCE]> SELECT ID, TYPE_ID, STATUS_ID FROM CONNECTIONS; $CDF [MAINTENANCE]> UPDATE CONNECTIONS SET COMMENT='Moved to the new server' WHERE ID='SALES'; $CDF [MAINTENANCE]> COMMIT; ```

1. Type DISCONNECT; (or BYE;, CLOSE;). The CDF is closed and BroadSQL reads its configuration again, so your changes are visible at once:

``` $CDF [MAINTENANCE]> DISCONNECT; Disconnected from 'BroadSQL configuration database (CDF maintenance)' CDF maintenance mode ended. Disconnected. No active database connection. BroadSQL> ```

A wrong password, an empty one, or pressing Enter changes nothing: the current connection and prompt stay as they were.

WORLD> CONNECT $CDF;
CDF maintenance: enter the BroadSQL master password.
[Enter password]
ERROR: CDF maintenance refused: invalid master password. Nothing was changed.
WORLD>

Rules of maintenance mode

• CONNECT $CDF must be typed at the prompt. It is refused in a Script, a REPEAT and a BroadSQL Editor run, and it takes no argument: a password is never written on a command line.
• Autocommit follows the Autocommit setting (off by default): COMMIT your changes. Uncommitted changes are rolled back, with a warning, when you leave. While you hold uncommitted changes, CONFIG may wait and then report a lock timeout: commit first.
• No login script runs. Nothing is written to the command activity log. What you type is not kept in the console history.
• These commands are refused, because they would write into the CDF or need it closed: LOAD, BATCHLOAD, LINK TABLE, ENV, / <environment>, SET PASSWORD, SET MASTER PASSWORD, and DUMP or PULL AS H2 to $CDF.
• DUMP from the CDF to a file is allowed, with a warning: the file can contain stored passwords in clear. Protect or delete it.
• Maintenance mode is never restored: not at the next start, not after LOGOUT, not by DISCONNECT. Leaving it closes the CDF and forgets the authorization.
• Being in maintenance mode never lets another connection open the CDF.

Tables of the CDF

Do not create, drop or alter tables, and do not change the master password with SQL: use SET MASTER PASSWORD. After a master-password change, the $CDF row of CONNECTIONS has an empty USER_PASSWORD: BroadSQL never reads it, and no copy of the master password is kept there.

CDF schema versions and automatic upgrades

Schema version and release number

The CDF schema version describes the structure of the CDF. It is not the BroadSQL release number: a release that changes nothing in the CDF keeps the same schema version and never writes the CDF at startup.

What happens at startup

After you type the master password, and before anything else (configuration, the restored connection, any SQL), BroadSQL reads the schema version recorded in the CDF itself:

• Current: nothing is written.
• Older, or unversioned: BroadSQL upgrades it automatically, without asking: 1. it makes a backup and checks that the backup opens and holds the same data; 2. it applies each missing upgrade step in order, and records each version only once that step has completely succeeded; 3. it reports the result.

[Enter password]
INFO: CDF upgrade: unversioned legacy CDF -> schema 2.
INFO: Backup: C:\BroadSQL\conf\backups\ConnectionsDefinitionFile.cdf_schemalegacy_to2_20261016_140322.zip (verified)
INFO: CDF upgrade completed: schema 2 (BroadSQL 5.5.0).
BroadSQL>

The next start reads schema 2 and does nothing: an upgrade runs at most once per version. Your connections, their passwords, Database Groups, Environments, login scripts, types and API catalog are kept unchanged.

Where backups are stored

In the backups folder next to the CDF, one zip file per upgrade: conf/backups/<CDF file name>_schema<old>_to<new>_<date>_<time>.zip. A backup holds the CDF file exactly as it was, still encrypted with your master password. BroadSQL never deletes backups: remove old ones yourself when you no longer need them.

Checking an upgrade

The startup messages above show the old version, the new one and the backup. To see the recorded versions later, in maintenance mode:

$CDF [MAINTENANCE]> SELECT META_KEY, META_VALUE FROM BROADSQL_SYSTEM_METADATA;
$CDF [MAINTENANCE]> SELECT * FROM BROADSQL_SCHEMA_HISTORY ORDER BY SCHEMA_VERSION;

SCHEMA_VERSION is the current version, SCHEMA_INTRODUCED_IN the release that introduced it, and SCHEMA_APPLIED_BY the release that applied it.

Restoring a backup

1. Close BroadSQL.
2. Move conf/ConnectionsDefinitionFile.cdf.mv.db somewhere safe.
3. Open the backup zip and extract its .mv.db file into conf, under the name ConnectionsDefinitionFile.cdf.mv.db.
4. Start BroadSQL and type the master password that was in use when the backup was made.

If the restored CDF is older than your release, BroadSQL detects it and upgrades it again, with a new backup.

Upgrade failure

If an upgrade step fails, BroadSQL stops: it does not load the configuration, restore a connection or accept any command, and it does not record the new version.

ERROR: CDF upgrade failed while applying schema 2 (system metadata): <reason>.
The CDF still reports no schema version (legacy). BroadSQL cannot start with it.
Backup made before the upgrade: C:\BroadSQL\conf\backups\ConnectionsDefinitionFile.cdf_schemalegacy_to2_20261016_140322.zip
To recover: close BroadSQL, replace the CDF's .mv.db file with the .mv.db file of that backup, then start BroadSQL again.

Restore the backup as described above. A start that was interrupted during an upgrade (a closed window, a power cut) is safe: the next start makes a new backup and finishes the upgrade.

If the backup itself cannot be made (a full disk, a folder without write permission), nothing is changed:

ERROR: The CDF upgrade was not started: the backup could not be created or verified (<reason>). Nothing was changed.

A CDF newer than your BroadSQL

A CDF upgraded by a newer release cannot be used by an older one. BroadSQL refuses to start and does not change it:

ERROR: This CDF uses schema 3, introduced by BroadSQL 5.6.0. This BroadSQL (release 5.5.0) supports schema 2 at most.
The CDF was not changed. Use BroadSQL 5.6.0 or later, or restore a backup made for this release.

Before installing a new release

• Close BroadSQL and copy your conf folder: it holds the CDF and your settings.
• Keep the previous release's folder until the new one has started once: an upgraded CDF does not go back to an older release.
• Only one BroadSQL should start on a CDF during an upgrade. Another one starting at the same time stops with The CDF is in use by another process (possibly being upgraded). Close the other BroadSQL and start again.

Changing the master password

SET MASTER PASSWORD asks for the current master password, then for the new one twice. The accepted characters are listed on the Security page; a new password that does not follow them is refused before anything is changed.

The CDF is never encrypted again in place:

1. The CDF is opened and kept open, so another BroadSQL cannot open it during the change.
2. A backup is saved: conf/backups/<CDF file name>_masterpwd_<date>_<time>.zip, encrypted with the previous master password, and checked.
3. A copy of the CDF is encrypted with the new password, in the folder <CDF file name>.rotation-new next to the CDF.
4. The copy must open with the new password, refuse the previous one, and hold exactly the same data as the CDF.
5. The CDF is moved to <CDF file name>.rotation-previous, the copy takes its place, and it is checked again.
6. The previous file and the temporary folder are deleted, and BroadSQL asks you to log in with the new password.

When a step before 5 fails, the CDF is unchanged and the message says "The master password was NOT changed". When the check of step 5 fails, the previous file is put back. The backup always stays: delete it when you no longer need it, and keep it as safely as the CDF meanwhile.

The command is refused in CDF maintenance mode, while a CONFIG or CONFIG API window is open, while a Script runs in the BroadSQL Editor, and while another BroadSQL has the CDF open. Close the other BroadSQL sessions that use the same CDF before the change: after it, they can no longer save to the CDF until you log in to them again with the new password.

Master password recovery

If BroadSQL stops during the change (a crash, a power cut), the next login sorts it out:

BroadSQL never deletes a file it may need. If it cannot sort the files out, it says so and leaves them all in place. Then, with every BroadSQL closed:

1. In the folder of the CDF, look for <CDF file name>.mv.db, the folders <CDF file name>.rotation-previous (the CDF as it was, previous password) and <CDF file name>.rotation-new (the copy, new password), and the file <CDF file name>.rotation (a record of the change; it holds no password).
2. If <CDF file name>.mv.db is missing, copy the .mv.db file of <CDF file name>.rotation-previous to the CDF's folder under that name, and log in with the previous password.
3. Otherwise, try both passwords at the login. If neither works, restore the backup of step 2 as described in Restoring a backup, with the previous password.
4. Once you can log in, delete the two .rotation- folders and the .rotation file.

Linked tables created by earlier releases

Up to release 5.4.5, LINK TABLE $CDF CONNECTIONS could link a CDF table into an ordinary H2 database. Such a linked table stores the CDF's location and the master password in that other database. BroadSQL 5.5.0 refuses to create one, but does not change your databases. To find old ones, connect to each H2 database you may have used, and run:

SELECT TABLE_SCHEMA, TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='TABLE LINK';
SCRIPT NODATA;

SCRIPT NODATA shows each linked table's definition: a link whose URL ends with ConnectionsDefinitionFile.cdf points to the CDF. Remove it with DROP TABLE <name>;. If that database was shared, copied or backed up where others can read it, change the master password with SET MASTER PASSWORD.

Limits and troubleshooting

Related pages

• Starting, connecting and logging out
• Security
• Connections, Database Groups and Environments
• Application settings
• CONNECT, CONFIG, SET MASTER PASSWORD

History

• Up to 5.4.5, BroadSQL started connected to the CDF ($CDF>), DISCONNECT returned to it, CONFIG required it, and CONNECT $CDF opened it like any database, without asking for a password. Since 5.5.0, BroadSQL starts at BroadSQL>, the CDF is opened only in maintenance mode, and any other connection to it is refused.
• Up to 5.4.5, BroadSQL brought the CDF's structure up to date at every start without a backup. Since 5.5.0, the CDF has a schema version, and an upgrade runs once, after a verified backup.
• Up to 5.4.5, SET MASTER PASSWORD encrypted the CDF again in place, without a backup, accepted any character, and kept a copy of the master password in the $CDF row. Since 5.5.0, it works on a verified copy, keeps a backup, refuses the characters the engine cannot reopen a file with, and keeps no copy of the master password.