To run SQL Workbench/J a Java 6 runtime environment is required. You can either use a JRE ("Runtime") or a JDK ("Development Kit") to run SQL Workbench/J.
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)
When upgrading to a newer version of SQL Workbench/J simply overwrite the old
sqlworkbench.jar
and the exe launcher and shell scripts that
start the application.
Starting with build 99 the file names have changed. The jar file is now
named sqlworkbench.jar
and the filename of the Windows
launcher is now sqlworkbench.exe
.
If you are upgrading from build 98 or earlier, please delete the old files
Workbench.jar
and JWorkbench.exe
.
sqlworkbench.jar is a self executing JAR file. This means, that if your JDK is installed properly, a double click (on the Windows® platform) 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.
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.
The shell scripts (and the batch files) first check if the environment variable WORKBENCH_JDK
is defined. If that variable is defined, 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.
On a 32bit Windows® platform the supplied SQLWorkbench.exe can be used to start the program when using a Sun JDK. The native launcher searches for an installed JDK (querying the registry) and then starts SQL Workbench/J. The file sqlworkbench.jar has to be located in the same directory as the SQLWorkbench.exe, otherwise it doesn't work.
![]() | |
For a Windows 64bit system, you have to use |
The launcher only works with a Sun JDK, as it directly calls the JDK' dll to start the virtual machine. If you are using a different JDK you cannot use the launcher to start SQL Workbench/J on Windows (unless it uses the same directory layout and filenames as the Sun JDK).
By default the launcher increases the maximum JVM heap size to 256MB. If you need more heap memory, you need to pass the appropriate JVM parameter to the launcher. Please refer to Increasing the memory for details on how to increase the memory that is available to SQL Workbench/J
The launcher executables are based on WinRun4J, further documentation on the format of the configuration file and parameters can also be found there.
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
sqlworkbench.jar
is located$HOME/.sqlworkbench
on Unix based systems
or %HOMEPATH%\.sqlworkbench
on Windows systems)
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.
Note that, before Build 98 the default configuration directory was the program's directory and not a directory in the user's home directory.
The following files are stored in the configuration directory:
workbench.settings
)WbProfiles.xml
)WbDrivers.xml
)WbShortcuts.xml
).
If you did not customize any of the shortcuts, this file does not existWbMacros.xml
)workbench.log
)*.wksp
)
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 commandline.
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.
If you want to control the location where SQL Workbench/J stores the configuration files, you have to start the application with the parameter -configDir to specify an alternate directory:
java -jar sqlworkbench.jar -configDir=/export/configs/SQLWorkbench
or if you are using the Windows® launcher:
SQLWorkbench -configDir=c:\ConfigData\SQLWorkbenchThe placeholder
${user.home}
will be replaced with the current user's home directory
(as returned by the Operating System), e.g.:java -jar sqlworkbench.jar -configDir=${user.home}/.sqlworkbenchIf the specified directory does not exist, it will be created.
To copy an installation to a different computer, simply copy all the above files to the other computer (the log file does not need to be copied). When a profile is connected to a workspace, the filename of the workspace file is usually stored with a placeholder for the configuration directory (%configDir%) so that the profiles don't need to be adjusted.
You will need to edit the driver definitions (stored in WbDrivers.xml
)
as the full path to the driver's jar file(s) is stored in the file (unless you
define the location of the drivers using the libdir variable.
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 the data that is returned by a SELECT
statement into the main 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 you use the Windows® Launcher to start SQL Workbench/J
you need to create a configuration file named SQLWorkbench.ini
(or SQLWorkbench64.ini
when using the 64bit launcher) with the following content:
vm.heapsize.preferred=512This will increase the memory for the application to 512MB. For more options to configure the JVM, please refer to the documentation of WinRun4J
If you are running SQL Workbench/J on a non-Windows® operating system or do not want to use the launcher, then you need to pass this parameter directly to the JVM
java -Xmx512m -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.
Command line parameters are not case sensitive.
The parameters -PROFILE
or -profile
are
identical. The usage of the command line parameters is identical between
the launcher or starting SQL Workbench/J using the java
command itself.
![]() | |
When quoting parameters on the commandline (especially in a Windows environment) you have to use single quotes, as the double quotes won't be passed to the application. |
The parameter -configDir
specifies the directory where
SQL Workbench/J will store all its settings. If this parameter is not supplied,
the directory where the default location is used.
The placeholder ${user.home}
will be
replaced with the current user's home directory (as returned by the Operating System).
If the specified directory does not exist, it will be created.
java -jar sqlworkbench.jar -configDir=${user.home}/wbconfig SQLWorkbench -configDir='c:\Configurations\SQLWorkbench'
On the Windows platform you can use a forward slash to separate directory names in the parameter.
The -libdir
parameter defines the base directory for your JDBC drivers. The value of
this parameter can be referenced when defining a driver library
using the placholder %LibDir%
The value for this parameter can also be set in the file workbench.settings
.
SQL Workbench/J stores the connection profiles in a file called WbProfiles.xml
.
If you want to use a different filename, or use different set of profiles for different purposes
you can define the file where the profiles are stored with the -profilestorage
parameter.
If the value of the parameter does not contain a path, the file will be expected (and stored) in the configuration directory.
With the -vardef
parameter a definition file for
internal variables can be specified.
Each variable has to be listed on a single line in the format variable=value
.
Lines starting with a #
character are ignored (comments).
the file can contain unicode sequences (e.g. \u00fc
. Values
spanning multiple lines are not supported. When reading a file during startup
the default encoding is used. If you need to read the file in a specific encoding
please use the WbVarDef
command with the -file
and -encoding
parameter.
#Define some values var_id=42 person_name=Dent another_variable=24
If the above file was saved under the name vars.txt
, you can use those
variables by starting SQL Workbench/J using the following commandline:
java -jar sqlworkbench.jar -vardef=vars.txt
You can also define a list of variables with this parameter. In this case, the first character after the = sign, has to be # (hash sign) to flag the value as a variable list:
java -jar sqlworkbench.jar -vardef=#var_id=42,person_name=Dent
Defining variable values in this way can also be used when running in batch mode.
If the -nosettings
parameter is specified, SQL Workbench/J will not write
its settings to the file workbench.settings
when it's beeing closed. Note
that in batch mode, this file is never written.
![]() | |
If this parameter is supplied, the workspace will not be saved automatically as well! |
You can specify the name of an already created connection
profile on the commandline with the -profile=<profile name>
parameter. The name has to be passed exactly like it appears in the profile dialog
(case sensitiv!). If the name contains spaces or dashes, it has to be enclosed in
quotations marks. If you have more than one profile with the same name but in different
profile groups, you have to specify the desired profile group using the -profilegroup
parameter, otherwise the first profile matching the passed name will be selected.
Example (on one line):
java -jar sqlworkbench.jar -profile='PostgreSQL - Test' -script='test.sql'
In this case the file WbProfiles.xml
must be in the current
(working) directory of the application. If this is not the case, please specify the
location of the profile using either the -profilestorage
or
-configDir
parameter.
If you have two profiles with the names "Oracle - Test"
you will
need to specify the profile group as well (in one line):
java -jar sqlworkbench.jar -profile='PostgreSQL - Test' -profilegroup='Local' -script='test.sql'
You can also specify the full connection parameters on the commandline, if
you don't want to create a profile only for executing a batch file.
The advantage of this method is, that SQL Workbench/J does not need the files
WbProfiles.xml
, WbDrivers.xml
to be
able to connect to the database.
The connection can be specified with the following parameters:
Parameter | Description |
---|---|
-url | The JDBC connection URL |
-username | Specify the username for the DBMS |
-password | Specify the password for the user |
-driver | Specify the full class name of the JDBC driver |
-driverJar | Specify the full pathname to the .jar file containing the JDBC driver |
-autocommit | Set the autocommit property for this connection. You can also
control the autocommit mode from within your script by using the
SET AUTOCOMMIT command.
|
-rollbackOnDisconnect | If this parameter is set to true, a ROLLBACK will
be sent to the DBMS before the connection is closed. This setting is
also available in the connection profile.
|
-trimCharData |
Turns on right-trimming of values retrieved from CHAR
columns. See the description of the
profile properties for details.
|
-removeComments | This parameter corresponds to the Remove comments setting of the connection profile. |
-fetchSize | This parameter corresponds to the Fetch size setting of the connection profile. |
-ignoreDropError | This parameter corresponds to the Ignore DROP errors setting of the connection profile. |
-emptyStringIsNull | This parameter corresponds to the Empty String is NULL setting of the connection profile. This will only be needed when editing a result set in GUI mode. |
-connectionProperties |
This parameter can be used to pass extended connection properties if
the driver does not support them e.g. in the JDBC URL. The values are passed as key=value pairs,
e.g.
If either a comma or an equal sign occurs in a parameter's value, it must be quoted.
This means, when passing multiple properties the whole expression needs to be quoted:
As an alternative, a colon can be used instead of the equals sign,
e.g
If any of the property values contain a comma or an equal sign, then the whole parameter value needs to be quoted again, even
when using a colon.
|
-altDelim |
The alternate delimiter to be used for this connection.
To define a single line delimiter append the characters :nl to the parameter value:
e.g. -altDelimiter=GO:nl to define a SQL Server like GO as the
alternate delimiter. Note that when running in batchmode you can also override
the default delimiter by specifying the
-delimiter parameter.
|
-separateConnection | If this parameter is set to true, and SQL Workbench/J is run in GUI mode,
each SQL tab will use it's own connection to the database server. This setting is
also available in the connection profile.
The default is true .
|
-workspace | The workspace file to be loaded. If the file specification does not
include a directory, the workspace will be loaded from the
configuration directory. If this parameter
is not specified, the default workspace (Default.wksp ) will be loaded.
|
-readOnly | Puts the connection into read-only mode. |
If a value for one of the parameters contains a dash or a space, you will need to quote the parameter value.
A disadvantage of this method is, that the password is displayed in plain text on the command line. If this is used in a batch file, the password will be stored in plain text in the batch file. If you don't want to expose the password, you can use a connection profile and enable password encryption for connection profiles.