7. Connecting to the database
Prev |  | Next

## 7. Connecting to the database

### 7.1. Connection profiles

SQL Workbench/J uses the concept of profiles to store connection information. A connection profile stores two different types of settings:

- JDBC related properties such as the JDBC driver class, the connection URL, the username etc.
- SQL Workbench/J related properties such as the profile name the associated workspace, etc.

After the program is started, you are prompted to choose a connection profile to connect to a database. The dialog will display a list of available profiles on the left side. When selecting a profile, its details (JDBC and SQL Workbench/J settings) are displayed on the right side of the window.

To create a new profile click on the `New Profile` button (). This will create a new profile with the name "New Profile". The new profile will be created in the currently active group. The other properties will be empty. To create a copy of the currently selected profile click on the `Copy Profile` button (). The copy will be created in the current group. If you want to place the copy into a different group, you can either choose to Copy & Paste a copy of the profile into that group, or move the copied profile, once it is created.

To delete an existing profile, select the profile in the list and click on the `Delete Profile` button ()

### 7.2. Managing profile groups

Profiles can be organized in groups, so you can group them by type (test, integration, production) or customer or database system. When you start SQL Workbench/J for the first time, no groups are created and the tree will only display the default group node. To add a new group click on the `Add profile group` () button. The new group will be appended at the end of the tree. If you create a new profile, it will be created in the currently selected group. If a profile is selected in the tree and not a group node, the new profile will be created in the group of the currently selected profile.

Empty groups are discarded (i.e. not saved) when you restart SQL Workbench/J

You can move profiles from one group to another but right clicking on the profile, then choose Cut. Then right-click on the target group and select Paste from the popup menu. If you want to put the profile into a new group that is not yet created, you can choose Paste to new folder. You will be prompted to enter the new group name.

If you choose Copy instead of Cut, a copy of the selected profile will be pasted into the target group. This is similar to copying the currently selected profile.

To rename a group, select the node in the tree, then press the F2 key. You can now edit the group name.

To delete a group, simply remove all profiles from that group. The group will then automatically be removed.

### 7.3. JDBC related profile settings

#### 7.3.1. Driver

This is the class name for the JDBC driver. The exact name depends on the DBMS and driver combination. The documentation for your driver should contain this information. SQL Workbench/J has some drivers pre-configured. See JDBC drivers for details on how to configure your JDBC driver for SQL Workbench/J.

#### 7.3.2. URL

The connection URL for your DBMS. This value is DBMS specific. The pre-configured drivers from SQL Workbench/J contain a sample URL. If the sample URL (which gets filled into the text field when you select a driver class) contains words in brackets, then these words (including the brackets) are placeholders for the actual values. You have to replace them (including the brackets) with the appropriate values for your DBMS connection.

#### 7.3.3. Username

This is the name of the DBMS user account

You can use placeholders in the username property that get replaced with operating system environment variables or Java properties. E.g. `${user.name}` will be replaced with the current operating system user - this works on any operating system as the variable is supplied by the Java runtime. `${USERNAME}` would be replaced with the current username on Windows®. you can combine this with fixed text, e.g. `DEV_${user.name}` or `TEST_${user.name}`.

#### 7.3.4. Password

This is the password for your DBMS user account. You can choose not to store the password in the connection profile.

#### 7.3.5. Autocommit

This check box enables/disables the "auto commit" property for the connection. If autocommit is enabled, then each SQL statement is automatically committed on the DBMS. If this is disabled, any DML statement (`UPDATE, INSERT, DELETE, ...`) has to be committed in order to make the change permanent. Some DBMS require a commit for DDL statements (`CREATE TABLE, ...`) as well. Please refer to the documentation of your DBMS.

#### 7.3.6. Fetch size

This setting controls the default fetch size for data retrieval. This parameter will directly be passed to the setFetchSize() method of the `Statement` object. For some combinations of JDBC driver and DBMS, setting this parameter to a rather large number can improve retrieval performance especially on slow network connections.

The JDBC driver for PostgreSQL controls the caching of ResultSets through this parameter. As the results are cached by SQL Workbench/J anyway, it is suggested to set this parameter to a value greater then zero to disable the caching in the driver (while disabling auto commit at the same time.

Especially when exporting large results using WbExport or WbCopy it is recommended to turn off the caching in the driver. A good starting point is setting this value to 100.

You can change the fetch size for the current connection manually by running the SQL Workbench/J specific command WbFetchSize

#### 7.3.7. Timeout

This property defines a timeout in seconds that is applied when establishing the connection to the database server. If no connection is possible in that time, the attempt will be aborted. If this is empty, the default timeout defined by the JDBC driver is used.

### 7.4. PostgreSQL connections

When connecting to a PostgreSQL database it's not necessary to specify username and password. Username and password will then be resolved according to the rules as `psql` or any other libpq application would do:

#### Username

If no username is specified in the connection profile, SQL Workbench/J will first check the environment variable `PGUSER`, if that is not defined, the current operating system user will be used.

#### Password

If no password is specified and the saving of the password is disabled, SQL Workbench/J will first check the environment variable `PGPASSWORD`. If that is not defined, SQL Workbench/J will look for a Postgres password file. If that exists and the host, database, port and user are matched in the password file, the stored password will be used.

### 7.5. Extended properties for the JDBC driver

JDBC drivers support additional connection properties where you can fine tune the behavior of the driver or enable special features that are not switched on by default. Most drivers support passing properties as part of the URL, but sometimes they need to be passed to the driver using a different method called extended properties.

If you need to pass an additional parameter to your driver you can do that with the Extended Properties button. After clicking that button, a dialog will appear with a table that has two columns. The first column is the name of the property, the second column the value that you want to pass to the driver.

To create a new property click on the new button. A new row will be inserted into the table, where you can define the property. To edit an existing property, simply double click in the table cell that you want to edit. To delete an existing property click on the `Delete` button ().

Some driver require those properties to be so called "System properties" (see the manual of your driver for details). If this is the case for your driver, check the option `Copy to system properties before connecting`.

### 7.6. SQL Workbench/J specific settings

#### 7.6.1. Prompt for username

If this option is enabled (i.e. checked) you will be asked to enter the username and password each time you connect to the specified database server. If this is checked, the input fields for username and password are disabled (but the values will still be saved in the profile).

This is useful if you have many different usernames for the same DBMS server and don't want to create a connection profile for each user.

#### 7.6.2. Save password

If this option is enabled (i.e. checked) the password for the profile will also be stored in the profile file. If the global option Encrypt Passwords is selected, then the password will be stored encrypted, otherwise it will be stored in plain text!

If you choose not to store the password, you will be prompted for it each time you connect using the profile.

To enable the use of PostgreSQL's password file this option needs to be disabled.

#### 7.6.3. Separate connection per tab

If this option is enabled, then each tab in the main window will open a separate (phyiscal) connection to the database server. This is useful, if the JDBC driver is not multi-threaded and does not allow to execute two statements concurrently on the same connection.

The connection for each tab will not be opened until the tab is actually selected.

Enabling this option has impact on transaction handling as well. If only one connection for all tabs (including the Database Explorer) is used, then a transaction that is started in one tab is "visible" to all other tabs (as they share the same connection). Changes done in one tab via `UPDATE` are seen in all other tabs (including the Database Explorer). If a separate connection is used for each tab, then each tab will have its own transaction context. Changes done in one tab will not be visible in other tabs until they are committed (depending on the isolation level of the database of course)

If you intend to execute several statements in parallel then it's strongly recommended to use one connection for each tab. Most JDBC drivers are not multi-threaded and thus cannot run more then on statement on the same connection. SQL Workbench/J does try to detect conflicting usages of a single connection as far as possible, but it is still possible to lock the GUI when running multiple statements on the same connection

When you disable the use of separate connections per tab, you can still create new a (physical) connection for the current tab later, by selecting File → New Connection. That menu item will be disabled if `Separate connection per tab` is disabled or you have already created a new connection for that tab.

#### 7.6.4. Ignore DROP errors

If this option is enabled, any error reported by the database server when issuing a statement that begins with DROP, will be ignored. Only a warning will be printed into the message area. This is useful when executing SQL scripts to build up a schema, where a `DROP TABLE` is executed before each `CREATE TABLE`. If the table does not exist the error which the `DROP` statement will report, is not considered as an error and the script execution continues.

When running SQL Workbench/J in batchmode this option can be defined using a separate command line parameter. See Section 18, “Using SQL Workbench/J in batch files” for details.

#### 7.6.5. Trim `CHAR` data

For columns defined with the CHAR datatype, some DBMS pad the values to the length defined in the column definition (e.g. a CHAR(80) column will always contain 80 characters). If this option is enabled, SQL Workbench/J will remove trailing spaces from the values retrieved from the database. When running SQL Workbench/J in batch mode, this flag can be enabled using the `-trimCharData` switch.

#### 7.6.6. Hide warnings

When a SQL statement returns warnings from the DBMS, these are usually displayed after the SQL statement has finished. By enabling this option, warnings that are returned from the DBMS are never displayed.

Note that for some DBMS (e.g. MS SQL Server) server messages (`PRINT 'Hello, world'`) are also returned as a warning by the driver. If you disable this property, those messages will also not be displayed.

If you hide warnings when connected to a PostgreSQL server, you will also not see messages that are returned e.g. by the `VACUUM` command.

#### 7.6.7. Remove comments

If this option is checked, then comments will be removed from the SQL statement before it is sent to the database. This covers single line comments using -- or multi-line comments using /* .. */

As an ANSI compliant SQL Lexer is used for detecting comments, this does not work for non-standard MySQL comments using the # character.

#### 7.6.8. Confirm updates

If this option is enabled, then SQL Workbench/J will ask you to confirm the execution of any SQL statement that is updating or changing the database in any way (e.g. UPDATE, DELETE, INSERT, DROP, CREATE, COMMIT, ...).

If you save changes from within the result list, you will be prompted even if Confirm result set updates is disabled.

This option cannot be selected together with the "Read only" option.

The read only state of the connection can temporarily be changed (without modifying the profile) using the WbMode command.

#### 7.6.9. Read only

If this option is enabled, then SQL Workbench/J will never run any statements that might change the database. Changing of retrieved data is also disabled in this case. This option can be used to prevent accidental changes to important data (e.g. a production database)

SQL Workbench/J cannot detect all possible statements that may change the database. Especially when calling stored procedures SQL Workbench/J cannot know if they will change the database. But they might be needed to retrieve data, this cannot be disabled altogether.

You can extend the list of keywords known to update the data in the `workbench.settings` file.

SQL Workbench/J will not guarantee that there is no way (accidentally or intended) to change data when this option is enabled. Please do not rely on this option when dealing with important data that must not be changed. If you really need to guarantee that no data is changed, you have to do this with the security mechanism of your DBMS, e.g. by creating a read-only user.

This option cannot be selected together with the "Confirm updates" option.

The read only state of the connection can temporarily be changed (without modifying the profile) using the WbMode command.

#### 7.6.10. Rollback before disconnect

Some DBMS require that all open transactions are closed before actually closing the connection to the server. If this option is enabled, SQL Workbench/J will send a `ROLLBACK` to the backend server before closing the connection. This is e.g. required for Cloudscape/Derby because executing a `SELECT` query already starts a transaction. If you see errors in your log file while disconnecting, you might need to enable this for your database as well.

#### 7.6.11. Empty string is NULL

If this option is enabled, then a NULL value will be sent to the database for an empty (zero length) string. Everything else will be sent to the database as entered.

Empty values for non-character values (dates, numbers etc) are always treated as `NULL`.

If this option is disabled you can still set a column's value to `NULL` while editing a result set. Please see Editing data for details

#### 7.6.12. Include NULL columns in INSERT

This setting controls whether columns where the value from the result grid is null are included in INSERT statements. If this setting is enabled, then columns for new rows that have a null value are listed in the column list for the `INSERT` statement (with the corresponding `NULL` value passed in the `VALUES` list). If this property is un-checked, then those columns will not be listed in `INSERT` statements. This is useful if you have e.g. auto-increment columns that only work if the columns are not listed in the DML statement.

#### 7.6.13. Check for uncommitted changes

This option is (currently) only available for PostgreSQL, HSQLDB 2.x and Oracle

When closing the application (or a SQL panel) SQL Workbench/J will check if the current transaction has changes that were not committed and will issue a warning.

For more details see the description of DBMS specific features.

#### 7.6.14. Remember DbExplorer Schema

If this option is enabled, the currently selected schema in the DbExplorer will be stored in the workspace associated with the current connection profile. If this option is not enabled, the DbExplorer tries to pre-select the current schema when it's opened.

#### 7.6.15. Store completion cache locally

If this option is enabled, the cache that is used for the code completion is stored locally when the connection is closed. When connecting to the database the next time the cache is pre-filled with the information from the local cache file.

The cache files will be created in a directory named `.cache` inside the configuration directory.

#### 7.6.16. Info Background

Once a connection has been established, information about the connection are display in the toolbar of the main window. You can select a color for the background of this display to e.g. indicate "sensitive" connections. To use the default background, click on the `Reset` () button. If no color is selected this is indicated with the text `(None)` next to the selection button. If you have selected a color, a preview of the color is displayed.

#### 7.6.17. Alternate delimiter

If an alternate delimiter is defined, and the statement that is executed ends with the defined delimiter, this one will be used instead of the standard semicolon. The profile setting will overwrite the global setting for this connection. This way you can define the `GO` keyword for SQL Server connections, and use the forward slash in Oracle connections. Please refer to using the alternate delimiter for details on this property.

#### 7.6.18. Workspace

For each connection profile, a workspace file can (and should) be assigned. When you create a new connection, you can either leave this field empty or supply a name for a new profile.

If the profile that you specify does not exist, you will be prompted if you want to create a new file, load a different workspace or want to ignore the missing file. If you choose to ignore, the association with the workspace file will be cleared and the default workspace will be loaded.

If you choose to leave the workspace file empty, or ignore the missing file, you can later save your workspace to a new file. When you do that, you will be prompted if you want to assign the new workspace to the current connection profile.

To save you current workspace choose Workspace → Save Workspace as to create a new workspace file.

If you specify a filename that does not contain a directory or is a relative filename, it is assumed the workspace is stored in workspace directory.

As the workspace stores several settings that are related to the connection (e.g. the selected schema in the DbExplorer) it is recommended to create one workspace for each connection profile.

#### 7.6.19. Default directory

The default directory controls from where scripts are loaded through WbInclude, or where files are written by WbExport if filenames without directories are used. If nothing is specified, the "current" directory of the application is used for these files.

When an external file is loaded in a SQL tab, that file's directory becomes the default directory and the "Default directory" from the profile is not used.

#### 7.6.20. Main window icon

You can assign an icon file for each connection profile. The icon will then be used for the main window instead of the default application icon.

The icon file can only be a `png` or `gif` file.

Do not use an animated GIF file because that will hang the application!

At least one file with an icon of 16x16 pixel should be selected. You can select multiple files with different icon sizes (e.g. a 16x16 and a 32x32 icon). Whether or not the additional sizes (i.e. bigger than 16x16) will be used depends on your operating system and desktop theme.

#### 7.6.21. macros

For each connection profile, a separate set of macros can be used. If no macro file is specified, the global macro file is used.

#### 7.6.22. Tagging connection profiles

To organize a large number of profiles it is possible to supply tags for each profile. These tags are then used by the profile filter to quickly show only certain profiles.

The tags for a profile are entered as a comma separated list. To see a list of already defined tags, press Ctrl-Space in the input field.

#### 7.6.23. Connect scripts

You can define a SQL script that is executed immediately after a connection for this profile has been established, and a script that is executed before a connection is about to be closed. To define the scripts, click on the button Connect scripts. A new window will be opened that contains two editors. Enter the script that should be executed upon connecting into the upper editor, the script to be executed before disconnecting into the lower editor. You can put more than one statement into the scripts. The statements have to be separated by a semicolon.

The statements that are executed will be logged in the message panel of the SQL panel where the connection is created. You will not see the log when a connection for the DbExplorer is created.

Execution of the script will stop at the first statement that throws an error. The error message will also be logged to the message panel. If the connection is made for a DbExplorer panel, the errors will only be visible in the log file.

##### Keep alive script

Some DBMS are configured to disconnect an application that has been idle for some time. You can define an idle time and a SQL statement that is executed when the connection has been idle for the defined interval. This is also available when clicking on the Connect scripts.

The keep alive statement can not be a script, it can only be a single SQL statement (e.g. `SELECT version()` or `SELECT 42 FROM dual`). You may not enter the trailing semicolon.

The idle time is defined im milliseconds, but you can also enter the interval in seconds or minutes by appending the letter 's' (for seconds) or 'm' (for minutes) to the value. e.g.: `30000` (30 seconds), or `45s` (45 seconds), or `10m` (10 minutes).

You can disable the keep alive feature by deleting the entry for the interval but keeping the SQL statement. Thus you can quickly turn off the keep alive feature but keep the SQL statement for the next time.

#### 7.6.24. Schema and Catalog filters

If your database contains a lot of schema or catalogs that you don't want to be listed in the dropdown of the DbExplorer, you can define filter expressions to hide certain entries.

The filters are defined by clicking on the Schema/Catalog Filter button. The filter dialog contains two input fields, one to filter schema name and one to filter catalog names.

Each line of the filter definition defines a single regular expression of schema/catalog names to be excluded from the dropdown, i.e. if a schema/catalog matches the defined name, it will not be listed in the dropdown.

The filter items are treated as regular expressions, so the standard SQL wildcards will not work here. The basic expression is just a name (e.g. MDSYS). Comparison is always done case-insensitive. So mdsys and MDSYS will achieve the same thing.

If you want to filter all schemas that start with a certain value, the regular expression would be: `^pg_toast.*`. Note the dot followed by a * at the end. In a regular expression the dot matches any character, and the * will allow any number of characters to follow. The ^ specifies that the whole string must occur at the beginning of the value.

The regular expression must match completely in order to exclude the value from the drop down.

If you want to learn more about regular expressions, please have a look at http://www.regular-expressions.info/

#### 7.6.25. Variables

It is possible to setup variables that are automatically defined when the connection for the profile is created. These variables will be removed after the connection is closed.

Variables defined in the connection profile are overwritten by variables defined for the workspace.

### 7.7. Connecting through a SSH tunnel

It is possible to setup a SSH tunnel to be used to connect to a database server that is not directly reachable (without using a external tool like Putty to create the tunnel).

To configure a SSH tunnel click on the SSH button in the connection profile. The configuration of the SSH tunnel consists of three parts:

- Login information for the computer from which the database server can be reached (the "SSH host")
- The mapping definition of a local port to the remote port of the database server
- Rewriting the JDBC URL to make the driver connect to "localhost" and the local port established by the SSH tunnel

#### 7.7.1. Configure the remote login

Option | Description
--- | ---
Global SSH Host Configuration | You can select a pre-defined SSH Hosts to connect to. If a global SSH host is selected the individual elements of the SSH host can not be edited.
SSH Hostname | This is the remote computer that is used to establish the SSH connection and from which the remote database server is reachable
SSH Port | The port for the SSH connection. If this is empty the default port 22 is used.
Username | The username on the SSH host to be used for the login.
Private key file | If the SSH host is configured to use authentication through a SSH key file, the path to the key file can be entered here
Password | This is either the password for the remote user login, or, if a private key file is specified, the passphrase for that key file. If no password is provided, you will be prompted to enter one when connecting. If a password is entered, it is always stored in the profile. If no password is entered, you will be prompted for one when the connection is established. If the password is used as a passphrase for a private key file, the entered password will be remembered until the application is closed. It will be (re)used for other tunnels using the same private key file.
Authenticate through SSH agent | If this option is enabled SQL Workbench/J will try to use a running SSH agent to authenticate against the SSH host. Supported agents are `pageant.exe` for Windows® and `ssh-agent` for Linux systems. In this case supplying a private key file or a password is not necessary, but the user name is still required. In order to be able to communicate with the SSH agent, additional libraries are needed, which can be downloaded from https://www.sql-workbench.eu/jna.zip. Please unzip the archive and put the two jar files into the `ext` sub-directory where `sqlworkbench.jar` is located.

#### 7.7.2. Configure the tunnel

Option | Description
--- | ---
Local port | The local port to be used for the tunnel. If this is empty a port will be chose automatically. Automatically choosing a local port only works for certain JDBC drivers where the structure of the JDBC URL is know and can be automatically rewritten.
DB Hostname | The hostname (or IP address) of the database server. This is the name as the SSH host sees the database server.
DB Port | The port of the database server.

If the option "Rewrite JDBC URL" is selected, SQL Workbench/J will try to adjust the JDBC URL of the connection profile to reflect the SSH settings. This only works for the following JDBC drivers:

- PostgreSQL
- Oracle
- Microsoft SQL Server using the Microsoft JDBC driver or the jTDS driver
- MySQL
- All drivers that use the format `jdbc:xxxxx://servername:port/...`

If rewriting the JDBC URL was not successful, a local port must be specified in the SSH configuration and the JDBC URL must be changed manually to use that port.

If no local port was given, the URL will contain the port 0 (zero) which will be replaced with the actual port that was chosen when the SSH tunnel is established.

Setting up the SSH tunnel is essentially the same as manually creating a SSH tunnel using:

    ssh -p [SSHPort] -L[LocalPort]:[DB Hostname]:[DB Port] [SSH User]@[SSH Host]

on the commandline and then changing the JDBC URL to use `localhost` and the local port.

If you use a private key file with a strong encryption you might need to enable your Java installation to use that encryption. To do this, download the JCE extension for strong encryption from http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html and install it into your Java runtime.

If multiple profiles use the same SSH tunnel definition SQL Workbench/J will only open one tunnel even if multiple windows using different profiles are used.

### 7.8. Connect to Oracle with SYSDBA privilege

Connecting to Oracle with SYSDBA privilege can be done by checking the option `as SYSDBA` next to the username. When using this option, you have to use an Oracle user account that is allowed to connect as SYSDBA (e.g. `SYS`).

### 7.9. Using the quick filter

The behaviour of the quick filter depends on whether tags are defined or not.

If no tags are defined at all, the quick filter will only search in the profile name. The search is done case-insensitive. Search for `prod` will match any profile that has `PROD` or `prod` anywhere in the profile's name

If tags are defined, the input is first checked if its one or more tags. If that is the case, the profiles are only filtered based on the tags defined. If there is a tag named prod, and the filter value is `prod`, only profiles with that tag are displayed. The profile name is not taken into account then. If the value in the filter field is not a tag, then the profiles are filtered based on name.

Multiple tags are separated by a comma. To see a list of defined tags, press the Ctrl-Space key.

Prev |  | Next
6. JDBC Drivers | Home | 8. Using workspaces