4. Installing and starting SQL Workbench/J
Prev |  | Next

## 4. Installing and starting SQL Workbench/J

### 4.1. Pre-requisites

SQL Workbench/J requires a Java 11 (or higher) runtime environment. You can either use a JRE ("Runtime") or a JDK ("Development Kit").

For Windows® and Linux a batch file is provided to automatically download a Java runtime environment

- For Windows®: `download_jre.cmd`
- For Linux/Unix and MacOS: `download_jre.sh`

For Windows® and Linux, it will download the a JRE from the SQL Workbench/J homepage. For MacOS, it will download a Java runtime from Adoptium. The Java runtime will be stored in the sub-directory `jre` which is automatically used by the Windows® launcher and the shell scripts to start SQL Workbench/J

You can manually download Windows®, Linux or MacOS binaries from one of these sites:

- Adoptium
- Azul Systems

Starting with build 126 the Windows® launcher can also download a Java runtime, if none was found.

### 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 with the "optional libraries", please delete all existing `jar` files in the `ext` sub-directory, before extracting the archive of the new version.

### 4.4. Starting the program from the commandline

To start the program a shell/batch script is provided. When using Linux or MacOS SQL Workbench/J can be started using `sqlworkbench.sh`.

When using Windows®, you can either use the batch file `sqlworkbench.cmd>` or `SQLWorkbench.exe` to start SQL Workbench/J.

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.

#### 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. The shell script `download_jre.sh` will automatically extract the Java runtime into that directory.

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` for a 32bit Java runtime or `SQLWorkbench64.exe` for a 64bit Java runtime can be used to start the program. The file `sqlworkbench.jar` has to be located in the same directory as the exe files, otherwise it does not work.

By default the launcher will initialize the Java runtime in the same process as long as the "bitness" of the used Java runtime matches the one from the launcher. If `SQLWorkbench64.exe` is used, but a 32bit Java runtime is configured, the launcher will start Java as a second process. Likewise, if `SQLWorkbench.exe` is used and a 64bit Java runtime is configured, the launcher will also start Java as a second process.

Note that "pinning" SQL Workbench/J to the Windows® taskbar only works if the launcher can initialize the Java runtime as part of its own process and thus no second process is started.

SQL Workbench/J does not need a "fully installed" runtime environment, you can also copy the `jre` directory from an existing Java installation into the directory where SQL Workbench/J is installed. Creating a symbolic link (using `mklink`) also works. A "local" Java installation in the `jre` subdirectory will have priority over any JRE or JDK registered in the Windows® registry.

The launcher searches for the Java runtime in the following order. The first Java installation found will be used.

1. it first checks if a command line parameter `-javaHome` was specified. If it was provided and points to a Java installation, that will be used.
2. then it checks, if the configuration file `SQLWorkbench.cfg` contains a `javaHome` entry. If it exists and points to a Java installation, that will be used.
3. then it checks if a Java runtime is available in the sub-directory `jre`.
4. if the environment variable `WORKBENCH_JDK` is defined, the launcher will use that to run the application.
5. if the environment variable `JAVA_HOME` is defined, the launcher will use that to run the application.
6. then it checks if the Windows registry contains information about a Java runtime.
7. if still no Java was found, all directories defined through the `PATH` variable are searched for a Java installation. The first one found will be used.

If neither of those steps found a Java runtime, the launcher offers to download a Java runtime or select an existing installation. The Java runtime is downloaded from Adoptium, as the the provided batch file does.

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 configuration file that needs to be created in the directory where `SQLWorkbench.exe` is located. The name of the file has to be `sqlworkbench.cfg`.

The format of `sqlworkbench.cfg` is different to the `.ini` file of previous versions. The launcher will convert an existing `SQLWorkbench.ini` or `SQLWorkbench64.ini` to the new format if started for the first time. It is no longer necessary to have different configuration files for the 32bit and 64bit version of the launcher.

##### 4.6.1.1. Specifying the Java location

If the launcher cannot find a Java runtime, you can specify the location of the JRE in the configuration file in the section `[Workbench]` with the following parameter:

    [Workbench]
    javaHome=c:\Program Files\Java

You need to specify the root directory of the Java runtime (or JDK). This can either be a 32bit or a 64bit runtime, but a 64bit runtime is highly recommended (and therefor using `SQLWorkbench64.exe`).

##### 4.6.1.2. Defining the memory for the application

The memory available to the Java runtime is specified through the configuration file by providing the corresponding JVM paramter. The following entry would set the maximum memory to 4GB (the `-Xmx` part is passed to the Java runtime)

    [Java]
    vmarg.mem=-Xmx4g

You can verify the available memory in the about dialog: Help → About

### 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 directory (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.

The location of the settings file (and therefor the configuration directory) is shown through Help → About and on the "General" page of the Options dialog which can be displayed using Tools → Options.

### 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.

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.

Prev |  | Next
3. Change log | Home | 5. Command line parameters