4. Installing and starting SQL Workbench/J

4.1. Pre-requisites
4.2. First time installation
4.3. Upgrade installation
4.4. Starting the program from the commandline
4.5. Starting the program using the shell script
4.6. Starting the program using the Windows® launcher
4.7. Configuration directory
4.8. Copying an installation
4.9. Increasing the memory available to the application

4.1. Pre-requisites

To run SQL Workbench/J a Java 8 runtime environment or higher is required. You can either use a JRE ("Runtime") or a JDK ("Development Kit") to run SQL Workbench/J.

SQL Workbench/J does not need a "fully installed" runtime environment, you can also copy the jre directory from an existing Java installation or use the no-installer packages from the Oracle home page

The "local" Java installation in the jre subdirectory will not be used by the Windows® launcher if a Java runtime has been installed and is registered in the system (i.e. the Windows® registry)

If you cannot (or do not want to) do a regular installation of a Java 8 runtime, you can download a ZIP distribution from Oracle's home page. Under "JRE Download" you can download tar.gz archives for Windows® and Linux (32bit and 64bit versions are available).

The archive just needs to be unpacked. Inside the archive the actual JRE is stored in a directory named e.g. jre1.8.0_xx where xx is the build number of the Java runtime. When moving this directory to the installation directory of SQL Workbench/J you have to rename it to jre in order for the Windows® launcher or the batch files to recognize it.

Maven central also offers ZIP archives of the Java runtime: http://maven.nuiton.org/nexus/content/repositories/jvm/com/oracle/jre/

4.2. First time installation

Once you have downloaded the application's distribution package, unzip the archive into a directory of your choice. Apart from that, no special installation procedure is needed.

You will need to configure the necessary JDBC driver(s) for your database before you can connect to a database. Please refer to the chapter JDBC Drivers for details on how to make the JDBC driver available to SQL Workbench/J

When starting SQL Workbench/J for the first time, it will create a directory called .sqlworkbench in the current user's home folder to store all its configuration information.

The "user's home directory" is $HOME on a Linux or Unix based system, and %HOMEPATH% on a Windows® system. (Technically speaking it is using the contents of Java system property user.home to find the user's home directory)

4.3. Upgrade installation

When upgrading to a newer version of SQL Workbench/J simply overwrite the old sqlworkbench.jar, the exe files and shell scripts that start the application. If you are using the bundle that includes the libraries for reading and writing OpenOffice and Microsoft Office files, replace all existing jar files with those from the distribution archive as well.

4.4. Starting the program from the commandline

sqlworkbench.jar is a self executing JAR file. This means, that if your Java runtime is installed and registered with the system, a double click on sqlworkbench.jar will execute the application. To run the application manually use the command:

java -jar sqlworkbench.jar

Native executables for Windows® and Mac OSX are supplied that start SQL Workbench/J by using the default Java runtime installed on your system. Details on using the Windows® launcher can be found here.

4.5. Starting the program using the shell script

To run SQL Workbench/J under an Unix-type operating system, the supplied shell script sqlworkbench.sh can be used. For Linux desktops a sample ".desktop" file is available.

4.5.1. Specifying the Java runtime for the shell script

The shell scripts (and the batch files) first check if a Java runtime is available in the sub-directory jre. If that is available it will be used.

If no "local" Java runtime is found, the environment variable WORKBENCH_JDK is checked. If that variable is defined and points to a Java runtime installation, the shell script will use $WORKBENCH_JDK/bin/java to run the application.

If WORKBENCH_JDK is not defined, the shell script will check for the environment variable JAVA_HOME. If that is defined, the script will use $JAVA_HOME/bin/java to run the application.

If neither WORKBENCH_JDK nor JAVA_HOME is defined, the shell script will simply use java to start the application, assuming that a valid Java runtime is available on the path.

All parameters that are passed to the shell scripts are passed to the application, not to the Java runtime. If you want to change the memory or other system settings for the JVM, you need to edit the shell script.

4.6. Starting the program using the Windows® launcher

To start SQL Workbench/J on the Windows® platform, the supplied SQLWorkbench.exe (32bit Windows) or SQLWorkbench64.exe (64bit Windows) can be used to start the program when using an installed Oracle Java runtime. The file sqlworkbench.jar has to be located in the same directory as the exe files, otherwise it does not work.

SQL Workbench/J does not need a "fully installed" runtime environment, you can also copy the jre directory from an existing Java installation. Note that the "local" Java installation in the jre subdirectory will not be used by the Windows® launcher if a Java runtime has been installed and registered in the system.

If you cannot (or don't want to) do a regular installation of a Java 8 runtime, you can download a ZIP distribution for Windows® from Oracle's homepage: http://www.oracle.com/technetwork/java/javase/downloads/index.html. Under "JRE Download" there is also an option to download a no-installer version. These downloads are offered as tar.gz archives, so a tool that can handle Unix/Linux that format is needed for unpacking the archive (e.g. TotalCommander or 7-Zip).

When using a 32bit Java runtime the default memory available to the application is set to 1GB. When using a 64bit Java runtime the default is set to 65% of the available physical memory.

4.6.1. Parameters for the Windows® launcher

Additional parameters to the Windows® launcher can be defined in a INI file that needs to be created in the directory where the .exe is located. The name of the INI has to match the name of the used executable. To specify parameters for the 64bit executable, use SQLWorkbench64.ini. To specify parameters for the 32bit executable, use SQLWorkbench.ini

4.6.1.1. Specifying the Java location

The launcher executables are based on WinRun4J, further documentation on the format of the configuration file and parameters can also be found there.

If the launcher cannot find your installed Java runtime, you can specify the location of the JRE in the INI file with the following parameter:

vm.location=c:\Program Files\Java\jdk8\jre\bin\server\jvm.dll

You need to specify the full path to the jvm.dll, not the directory where the Java runtime is installed. Note that the 32bit Java runtime has both a server\jvm.dll and client\jvm.dll A 64bit Java runtime only has a server\jvm.dll.

4.6.1.2. Defining the memory for the application

The memory that is available to the Java runtime is defined through the parameter vm.heapsize.preferred in the INI file. The unit is bytes. To start SQL Workbench/J with 12GB of available memory (which is only possible on a 64bit system!) add the following line to the INI file:

vm.heapsize.preferred=12000

You can verify the available memory in the about dialog: HelpAbout

4.7. Configuration directory

The configuration directory is the directory where all config (workbench.settings, WbProfiles.xml, WbDrivers.xml) files are stored.

If no configuration directory has been specified on the commandline, SQL Workbench/J will identify the configuration directory by looking at the following places

  1. The current directory
  2. The directory where sqlworkbench.jar is located
  3. In the user's home direcotry (e.g. $HOME/.sqlworkbench on Unix based systems or %HOMEPATH%\.sqlworkbench on Windows® systems)

If the file workbench.settings is found in one of those directories, that directory is considered the configuration directory.

If no configuration directory can be identified, it will be created in the user's home directory (as .sqlworkbench).

The above mentioned search can be overridden by supplying the configuration directory on the commandline when starting the application.

The following files are stored in the configuration directory:

  • General configuration settings (workbench.settings)
  • Connection profiles (WbProfiles.xml)
  • JDBC Driver definitions (WbDrivers.xml)
  • Customized shortcut definitions (WbShortcuts.xml). If you did not customize any of the shortcuts, this file does not exist
  • Macro definitions (WbMacros.xml)
  • Saved column orders from the DbExplorer(WbColumnOrder.xml)
  • Log file (workbench.log)
  • Workspace files (*.wksp)
  • The cache directory for the code completion

If you want to use a different file for the connection profile than WbProfiles.xml then you can specify the location of the profiles with the -profileStorage parameter on the command line. Thus you can create different shortcuts on your desktop pointing to different sets of profiles. The different shortcuts can still use the same main configuration file.

4.8. Copying an installation

To copy an installation to a different computer, simply copy all the files from the configuration directory to the other computer (the log file does not need to be copied). When a profile is connected to a workspace, the workspace file should be specified without a directory name (or using the %ConfigDir% placeholder). In that case it is always loaded from the configuration directory. If the workspace file is given with an absolute directory, this needs to be adjusted after the copying the files.

You will need to edit the driver definitions (stored in WbDrivers.xml) because the full path to the driver's jar file(s) is stored in the file.

If you store all JDBC drivers in a common directory (or below a common root directory) you can define the libdir variable. In that case the paths to the driver's jar file are stored relative to the %LibDir% directory. After copying the installation you only need to adjust the %LibDir% variable on the other computer.

4.9. Increasing the memory available to the application

SQL Workbench/J is a Java application and thus runs inside a virtual machine (JVM). The virtual machine limits the memory of the application independently from the installed memory that is available to the operating system.

SQL Workbench/J reads all the data that is returned by a SQL statement into memory. When retrieving large result sets, you might get an error message, indicating that not enough memory is available. In this case you need to increase the memory that the JVM requests from the operating system (or change your statement to return fewer rows).

When using the Windows launcher (e.g. SQLWorkbench64.exe), the available memory is defined in the INI file.

When using the shell or batch scripts, the available memory is defined through the -Xmx parameter for the java command. In the following example, the parameter -Xmx4g sets the available memory to 4GB

java -Xmx4g -jar sqlworkbench.jar

If you are using the supplied shell scripts to start SQL Workbench/J, you can edit the scripts and change the value for the -Xmx parameter in there.

[Note]
With a 32bit Java runtime, you can not use (or assign) more than approx. 1.5GB for the application. If you need to process results that require more memory that that, you will have to use a 64bit Java runtime.