Adding new JDBC drivers

BMC Discovery ships with the JTDS driver, which can connect to the MS SQL Server and Sybase. To connect to other databases, you must download and install JDBC drivers for the databases that you want to use.

If you want to connect to a database from the following list, you must download the driver from the appropriate web site (the URL is available from Uploading new JDBC drivers) and upload it using the information at Uploading new JDBC drivers. However, before you can use a new driver that is not in the list, you must provide a properties file for it. The properties file determines how the JDBC URL is constructed. The following properties files are shipped with BMC Discovery and are located in the $TIDEWAY/data/installed/jdbcdrivers directory:

Ingres
Microsoft SQL Server
MySQL
Oracle
PostgreSQL
Sybase
JTDS—IPv6 access using JTDS is not currently possible

Additional driver support

While it is possible to add new JDBC drivers not specified in the preceding list, these drivers have not been tested by BMC, and no guarantees can be made that they will work as expected with BMC Discovery. For more information, contact BMC Support.

The $TIDEWAY/data/custom/jdbcdrivers and $TIDEWAY/data/installed/jdbcdrivers directories are both checked for properties files.
When you save a driver to the $TIDEWAY/data/custom/jdbcdrivers directory, you can create a new properties file in the same directory, or you can edit one of the supplied properties files in the $TIDEWAY/data/installed/jdbcdrivers directory.

Installing driver files manually

If you copy files into either of these directories via a command line, you must restart Tideway services to make the change effective.

To write a properties file

Create a text file called name.properties where name is the same as the name of the driver that the properties file relates to.

For example, mysql-connector-java-5.0.7.properties is the properties file for mysql-connector-java-5.0.7.jar.

The following table describes the entries that you must put in the properties file, and additional optional entries:

Mandatory Entries
Entry Name	Description
`driver.name`	This field is displayed throughout the BMC Discovery UI to identify the driver.
`driver.class`	The main class that will be loaded from the relevant jar file in custom/jdbcdrivers. The user will need to get this from the documentation provided by the database/JDBC vendor. For example, `driver.class=com.mysql.jdbc.Driver`
`driver.url`	The format of the connection URL that this driver uses. There is no standard URL for the JDBC URL; every driver has its own format. BMC Discovery passes the assembled URL to each registered driver, and the driver responds, whether it recognizes the URL or not. The URL is made up of several parts, which are described in JDBC drivers.
Optional Entries
Entry Name	Description
`driver. default=true`	Specifies that this driver is the default driver and will be displayed first in lists when creating objects that use JDBC drivers; for example, `SQLIntegrationConnections`. If no default is specified across all the drivers, then the order in which they are displayed is random. If more than one driver is specified as the default, then the last driver to be loaded is marked as the default.
`driver. exceptionProcessor`	Specifies a Java class that can format SQL exceptions (`java.sql. SQLException`) that bubble up from the JDBC driver. This class must implement the `ExceptionProcessorIF` interface. When an SQL exception occurs, the specified class is called and the result of that call is published to the relevant source (which might be a log file) or to the UI. For example, `driver.exceptionProcessor= com.tideway.integrations.service.servants.MySqlExceptionProcessor`
`translation. variablename`	Translates a variable that is specified in the JDBC URL to a user-visible label. See the following table for a list of variable names. For example, translation.extra_parameters=Additional Parameters.
`validationregex. variablename`	(Used only with Integration Points and Software Credential Groups) Validates a given variable specified in the JDBC URL. When the user tries to save a connection, each of the properties is checked to see if it has an associated validation regex. If so, and if the Match on this check box is not selected or the connection is static, the value entered by the user is matched against the value specified here. If the values do not match, the user is prompted to re-enter the value. The endpoint is always validated, for static credentials, to ensure that it is a valid IPv4 address.

The following table shows the parameters used by each driver:

Field	MySQL	Postgres	Oracle (service)	Oracle (SID)	Ingres	Sybase	MS SQL Server	JTDS
`servertype`								Req
`endpoint`	Req	Req	Req	Req	Req	Req	Req	Req
`port`	Opt	Opt	Opt	Opt	Opt	Opt	Opt	Opt
`database`	Opt	Req			Req	Opt		Opt
`extra_parameters`	Opt	Opt			Opt		Opt	Opt
`instance_name`							Opt
`service`			Req
`sid`				Req

When you have added a new driver and written a properties file for it, you must restart the Tideway services. To do so, enter the following command:

$ tw_service_control --restart

Multiple drivers using the same JAR (Oracle)

There are two methods for connecting to Oracle: OracleService and OracleSID. These methods use the same driver JAR file but need two properties files to build the different connection URLs used. Rather than copying and renaming the JAR file, a better method is to use symbolic links.

The driver file is called ojdbc14.jar for Oracle 10g and earlier. For Oracle 11g, the driver file is called ojdbc15.jar which requires JRE 1.5 or later.

cd ~/data/installed/jdbcdrivers
ln -s ojdbc14.jar oracleService.jar
ln -s ojdbc14.jar oracleSID.jar

This creates a symbolic link called oracleService.jar for the oracleService.properties properties file and one called oracleSID.jar for the oracleSID.properties properties file.

Adding new JDBC drivers

To write a properties file

Multiple drivers using the same JAR (Oracle)

Comments