Skip to main content

Dynamic JDBC Drivers

New in Txture 20

This feature was newly introduced in Txture 20.

In order to connect Txture to an external SQL Database during an Importer execution, a JDBC Driver which matches the target database is required. Txture ships with a variety of JDBC drivers for common databases, such as PostGreSQL or SQL Server. However, there may be cases where the JDBC driver for your database can not be included in Txture. For example:

  • The driver for your database may be subject to a license which prevents redistribution as part of Txture.
  • Your database may use an old version of the database which is not officially supported anymore.
  • You require a custom-written driver for your database.

For such cases, Txture provides a mechanism to dynamically load JDBC drivers at server startup from the Txture Home directory.

Got a Database we don't have a driver for? Contact us first.

In general, JDBC drivers tend to have open-source licenses that permit redistribution. In case that you encounter the need to import data from a database for which there is no built-in driver in Txture, please contact the Txture Support first before attempting to load it dynamically.

Security Disclaimer: Dynamic Class Loading

Dynamically loading classes from a folder is a major security concern. Txture has no way to verify those additional classes; they will be executed as trusted code. A malicious attacker might manage to inject code files into your Txture Home. When dynamic JDBC driver loading is enabled, this code will be executed as part of the Txture process and can result in arbitrary damage or failure, including (but not limited to) data corruption, data loss, system espionage, data leaks and remote controlling. Txture will not be held accountable for any damage that arises from dynamic classloading.

Dynamically loading a JDBC Driver​

If you encounter a case where you require to load a JDBC driver which is not included in Txture, the first step is to acquire the Java Archive (*.jar) file which contains the driver classes.

  • Driver JARs often ship as part of a database installation.
  • Maven Central is another good place to search for JDBC drivers.
  • The vendor of your database may also indicate potential driver sources.

Once you have acquired your driver, it needs to be placed in your Txture Home directory, in a directory called jdbcDrivers. For example, for myDriver.jar, the path is: <txtureHome>/jdbcDrivers/myDriver.jar.

By default, dynamic JDBC driver loading is disabled in Txture, as it requires dynamic class loading, which is a security concern. To enable dynamic JDBC driver loading, add the following line to your txture.properties file:

  # allow Txture to load JDBC drivers from txtureHome/jdbcDrivers
  txture.jdbc.dynamicdriverloading.enabled=true

Set up File Permissions​

Once your driver has been added to the jdbcDrivers directory, make sure that:

  • The Txture Server process has read-only file system access to the jdbcDrivers directory.
  • The Txture Server process has read-only file system access to the *.jar files within the directory.

Drivers will not be loaded if the Txture Server process has write access to the jdbcDrivers directory or the *.jar files within it. This restriction exists for security reasons and helps to prevent certain code injection scenarios.

Testing your Driver​

Finally, restart your Txture server if it is running. Upon restart, the server log should contain a list of all available JDBC drivers, including the one you added to the jdbcDrivers directory if it was loaded successfully. You can then proceed to use this driver for JDBC connections in your importers. In order to use your driver to connect your SQL importer with the external database, you'll require the proper JDBC database URL (starting with jdbc:). Your driver's documentation should indicate how to compose this URL, as well as how to authenticate the request.

Loading JDBC-3 Drivers​

Most modern JDBC drivers adhere to the JDBC-4 standard. JDBC-4 drivers can be loaded automatically as long as their corresponding *.jar file is present. However, older drivers (following the JDBC-3 standard) require additional configuration. To load a JDBC-3 driver, in addition to its *.jar file being present, the exact Java class name of the driver needs to be known. As this class name generally cannot be inferred from the *.jar file, it needs to be stated explicitly.

To load a JDBC-3 Driver:

  • Complete the general steps for dynamically loading a JDBC driver.
  • Inside your <txtureHome>/jdbcDrivers directory, create a file named jdbcDriverNames.txt (if it does not exist). In this file, you can specify the Java class names of your JDBC-3 drivers, one per line. Lines starting with // or # will be treated as comments and be ignored.
  • In jdbcDriverNames.txt, add a new line stating the Java class name of your driver. This class name is usually stated in the driver's documentation. Look for a Class.forName(...) statement in the documentation.

Caveats of Dynamic JDBC Drivers​

While dynamic JDBC driver loading offers a flexible way to access databases, there are a couple of things to keep in mind.

Security Implications​

When dynamic JDBC driver loading is enabled, Txture will load all *.jar files in the <txtureHome>/jdbcDrivers directory. There is no way to verify that these archives do not contain malicious code; in fact, any form of code injection will be applicable in this scenario. Be aware of this fact and make sure that access to this directory (in particular, network access) is as restricted as possible.

Transitive Driver Dependencies​

In general, it is considered good practice for a JDBC driver *.jar to be self-contained, i.e. all classes required to run the driver are contained in the archive. Unfortunately, this is not always the case. Some drivers require that additional classes must be present for the driver to work correctly. In such cases, the dependency *.jar file(s) must also be added to the <txtureHome>/jdbcDrivers directory. Note that such a *.jar may, in turn, have dependencies. Classes which are required by a driver but are missing will result in either in a NoClassDefFoundError or a ClassNotFoundException when attempting to use the driver.

Java Version​

Txture is running on the Java Virtual Machine (JVM) in version 8. If the driver you are trying to load was compiled for a newer version of the JVM, then the driver will fail to load. We recommend to look for an alternative version of the driver that is compatible with your JVM version.