KNIME Documentation

Set up JDBC drivers on KNIME Hub and KNIME Server ​

Distribute JDBC drivers to KNIME Hub and KNIME Server executors using customization profiles. This ensures all executors and connected KNIME Analytics Platform clients use the same drivers without manual per-machine registration.

Before you begin ​

  • You have administrator access to KNIME Hub or KNIME Server.
  • You have obtained the JDBC driver .jar file from your database vendor.

Create a customization profile with the driver ​

Server-side steps ​

Create the customization profile on the KNIME Hub or KNIME Server repository.

  1. Create a profile folder inside <server-repository>/config/client-profiles. The folder name becomes the profile name.
  2. Copy the .jar file into the profile folder.
  3. In the profile folder, create a preferences file (.epf extension) with the following content:
text
/instance/org.knime.database/drivers/<DRIVER_ID>/database_type=<DATABASE>
/instance/org.knime.database/drivers/<DRIVER_ID>/driver_class=<DRIVER_CLASS_NAME>
/instance/org.knime.database/drivers/<DRIVER_ID>/paths/0=${profile:location}/<DRIVER_JAR>
/instance/org.knime.database/drivers/<DRIVER_ID>/url_template=<URL_TEMPLATE>
/instance/org.knime.database/drivers/<DRIVER_ID>/version=<DRIVER_VERSION>

Replace the placeholders as follows:

PlaceholderDescription
<DRIVER_ID>Unique identifier. Alphanumeric characters and underscores only.
<DATABASE>Database type (for example, mysql, postgresql). See the Databases preferences page for available types.
<DRIVER_CLASS_NAME>JDBC driver class (for example, oracle.jdbc.OracleDriver).
<DRIVER_JAR>Filename of the .jar file (including extension). ${profile:location} resolves to the profile folder on each client.
<URL_TEMPLATE>JDBC URL template. Escape colons (:) and backslashes (\) with a backslash. Example: jdbc\:oracle\:thin\:@<host>\:<port>/<database>. See JDBC driver reference for template syntax.
<DRIVER_VERSION>Driver version string (for example, 12.2.0).
  1. Configure KNIME Server executors to request the profile by adding the profile name to the knime.ini file of each executor. See the KNIME Server Administration Guide for details.

Client-side steps ​

KNIME Analytics Platform clients must be made aware of the customization profile to request it from KNIME Server.

  1. In KNIME Analytics Platform, go to File → Preferences → KNIME → Customization Profiles.
  2. Select the KNIME Server and the profile to apply.
  3. Restart KNIME Analytics Platform for the changes to take effect.

To verify the driver was added, go to File → Preferences → KNIME → Databases. Drivers added via a customization profile are marked as origin: profile after the driver ID.

Profile-sourced drivers can be edited but not deleted from this page. To remove a profile driver, deselect the profile on the Customization Profiles page.

Set default JDBC parameters ​

Hub administrators can inject JDBC parameters into all connections made from workflows running on KNIME Hub. These parameters take precedence over values set in the connector node.

Add the following lines to the .epf file of your customization profile:

text
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/<JDBC_PARAMETER>/type=<TYPE>
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/org.knime.database.util.DerivableProperties/knime.db.connection.jdbc.properties/<JDBC_PARAMETER>/value=<VALUE>

Supported <TYPE> values:

TypeValue description
CONTEXT_PROPERTYA workflow context property. See available variables below.
CREDENTIALS_LOGINUsername from a named credentials flow variable.
CREDENTIALS_PASSWORDPassword from a named credentials flow variable.
DELEGATED_GSS_CREDENTIALDelegated GSS credential (Kerberos, Hub execution only).
FLOW_VARIABLEName of a flow variable.
GSS_PRINCIPAL_NAMEKerberos principal name including the REALM.
GSS_PRINCIPAL_NAME_WITHOUT_REALMKerberos principal name without the REALM.
LITERALA literal string value.
LOCAL_URLA URL such as a knime: URL.

Available CONTEXT_PROPERTY variables:

  • context.workflow.name
  • context.workflow.path
  • context.workflow.absolute-path
  • context.workflow.username
  • context.workflow.temp.location
  • context.workflow.author.name
  • context.workflow.last.editor.name
  • context.workflow.creation.date
  • context.workflow.last.time.modified
  • context.job.id

Reserve JDBC parameters ​

Mark a JDBC parameter as reserved to prevent workflows from using it on KNIME Hub. This is useful for security-sensitive parameters such as DelegationUID.

text
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/reserved/*/knime.db.connection.jdbc.properties/<JDBC_PARAMETER>=true

Set a connection initialization statement ​

Inject a SQL statement that runs every time a JDBC connection is created from a workflow on KNIME Hub:

text
/instance/org.knime.database/drivers/<DRIVER_ID>/attributes/additional/java.lang.String/knime.db.connection.init_statement/value=<VALUE>

Use ${variable-name} syntax to include CONTEXT_PROPERTY variables in the statement. For example:

text
IMPERSONATE ${context.workflow.username};

Next steps ​