BroadSQL BroadSQL
Documentation / Installation

Installation

Requirements

  • Operating system: Windows (primary, fully supported) or Linux (see the note in the Linux section below).
  • Java: 21 or later (a JRE is enough to run BroadSQL; a JDK is only needed to build it from source). See Technical requirements for the full runtime contract.

Install

  1. Download the latest ZIP from the downloads page.
  2. Unzip it to a location on your disk, e.g. C:\BroadSQL.
BroadSQL/
  BroadSQL.bat            Windows launcher
  BroadSQL.ps1            PowerShell launcher (Windows)
  broadsql.sh             Linux/Unix launcher
  connect.bat             Synonym for BroadSQL.bat (Windows)
  conf/                   Configuration files (BroadSQL.ini, the CDF, log settings)
  drivers/                Add JDBC drivers not included in the distribution here
  extensions/             Add JAR files with additional commands here
  lib/                    Required libraries, including broadsql.jar
  logs/                   Log files
  scripts/                Your own script files (run with @)
  sqllib/                 Library of saved SQL queries

Windows

  1. Edit conf/BroadSQL.ini if needed (the defaults work out of the box): see Application settings for every setting it supports.
  2. Start BroadSQL with connect.bat (or BroadSQL.bat), optionally passing a connection ID as an argument, or right-click BroadSQL.ps1 and "Run with PowerShell".
  3. Log in with the default password clipper8AD (change it later with SET MASTER PASSWORD;).
  4. Add database connections with CONFIG;.

See Getting started for a full walkthrough of steps 3 and 4.

Linux

Linux is supported but has rougher edges than Windows: one of them is fixed directly in the steps below, since it would otherwise stop BroadSQL from starting at all.

1. Edit conf/broadsqlux.ini and set DefaultFolder, SqlLib, and LogFolderName to full paths under your BroadSQL root (see Application settings for every setting it supports).

2. Edit broadsql.sh. Two changes are needed:

  • Set JRE_HOME to a Java 21 or later installation (the shipped default points at a Java 8 path, left over from an older release; it will not run BroadSQL 5.x).
  • Fix the classpath argument: see below.

As shipped, the line reads:

$JRE_HOME/bin/java ... -cp lib/*;drivers/*;extensions/* com.projectsontracks.controller.BroadSQL -to=$CDF

; is Windows' classpath separator, not Linux's, and because it isn't quoted here, bash reads it as three separate shell commands (java ... -cp lib/*, then drivers/*, then extensions/* com.projectsontracks.controller.BroadSQL ...) instead of one -cp argument, so BroadSQL never actually starts. Replace that one line with:

$JRE_HOME/bin/java -Xms2048m -Xmx4096m -Dbsql.settings=conf/broadsqlux.ini -Dfile.encoding=Cp850 -Dlogback.configurationFile=conf/logback-broadsql.xml -cp "lib/*:drivers/*:extensions/*" com.projectsontracks.controller.BroadSQL -to=$CDF

The two changes: : instead of ; between entries (Linux's classpath separator), and the whole -cp value wrapped in double quotes so bash passes lib/*, drivers/*, and extensions/* through to the JVM literally: the JVM itself expands each trailing /* to every JAR in that directory, which only works if the shell doesn't expand it first.

3. chmod +x broadsql.sh, then run ./broadsql.sh.

4. Log in with the default password clipper8AD.

5. CONFIG is not available on Linux: create connections manually with SQL against the CONNECTIONS table of the CDF instead (see Getting started, Step 1).

See Getting started for what to do next.