Creating a custom JDBC connector

If IBM® Software Hub does not have a predefined connector for a particular data source, an administrator can create a custom JDBC connector for the data source. Users can use the custom JDBC connector to connect to multiple instances of the data source in a consistent way.

What roles and permissions do you need to complete this task?
  • To complete this task, you must have the Admin role for the Platform assets catalog.
  • For the required permissions to upload a JAR file to IBM Software Hub, see Importing JDBC drivers.
    Important: Uploading JDBC drivers is disabled by default and users cannot view the list of JDBC drivers in the web client.

    An instance administrator must enable users to upload or view JDBC drivers.

When do you need to complete this task?
Complete this task when you want users to be able to connect in a consistent way to a data source that does not have a predefined type in IBM Software Hub.

If you are connecting to only one data source and users do not need a repeatable method to connect to it, users can create a Generic JDBC connection.

Restriction
Any connections that are created from a custom JDBC connector will not work if you export the project and then import the project into a different IBM Software Hub instance. You must delete the connections and re-create the connector and the connections in the new instance.

Before you begin

Important: Confirm that the services and tools that you intend to use can work with connections that are created from a custom JDBC connector. See Supported services and tools for custom JDBC connectors.

As part of the setup, you will need one or more driver files (JDBC JAR files). Consult the documentation provided by the JDBC driver vendor for this information:

  • Identify and obtain the JAR file or files that are needed for the data source. You can upload the files in advance or while you create the connector.
  • Identify the driver class name. You can also find the driver class by inspecting the JAR files by following these steps:
    1. Open the JAR file as an archive file. If you do not have a program that can open a JAR archive, change the file extension to zip.
    2. Go to the META-INF/services/ directory within the archive.
    3. Extract the file that is named java.sql.Driver and open it in a text editor. The list of valid driver classes is listed in the java.sql.Driver file.
    Typically, drivers have one JAR file with one driver class name. If the driver contains multiple JAR files or defines multiple driver class names, consult the vendor documentation to determine the following information:
    • The name of the primary JAR file
    • The name of the primary driver class
    Any other JAR files in the driver are usually third-party dependencies for the primary JAR file.
  • Identify the format for the JDBC URL.
  • Identify the properties that are needed to connect to the data source. For each property, determine whether the property:
    • Has a variable or fixed value
    • Has a default value
    • Is required or optional
    • Is used to define credentials, such as a username or password
    • Is used for SSL support

Watch this video to see how to create a custom JDBC connector.

About this task

To create a custom JDBC connector, follow the steps to create a reusable connection form that users will use to create actual connections. You upload one or more JDBC driver JAR files. Then you create a JDBC URL template for the database and enter the properties for the JDBC driver. You customize and test the connection properties and the connection form layout. The connector is available to users after you complete all the steps and create it.

Procedure

  1. Log in to the IBM Software Hub web client. From the navigation menu, select Data > Connectivity.
  2. Select Connectors > Custom JDBC connectors, and then click New connector.
    Note: The Connectors tab is not visible by default. An instance administrator must enable users to upload or view JDBC drivers.
    The Create connector wizard opens.
  3. Display information: Enter values for the mandatory Connector name and Description fields.
    • In the Connector name field, enter a unique name that users will recognize. The name will appear in the New connection page that lists all connectors. It will also appear in the Create connection form that users will use to create the connection.
    • In the Description field, provide information that will help users identify the connector. The description will appear under Details in the side panel that opens when a user selects the connector in the New connection page. It will also be in the Connection overview section of the connection form.

    After you click Next, you can save the connector as a draft and return to finish it later.

  4. JDBC driver: Upload and select the JDBC driver files for the connector. Next, enter the driver class name.
  5. Define the properties for the connector Connection properties.

    Properties can be either variables or fixed values.

    • Variables: Users supply the values for the variables when they create a connection. Use syntax ${variable}. Variables must be one or more lowercase words separated by the underscore character (_). Variables cannot contain spaces or begin with an underscore character or a number. For example, valid variables are ${hostname} or ${host_name}.
    • Fixed values: Properties with specified values are hardcoded. They are used by the connection but are not displayed in the connection form.
    1. Enter the JDBC URL template. The JDBC URL identifies the database. The JDBC URL properties typically include variables for the hostname, port number, and database name. The URL must begin with the prefix jdbc:.
      Example JDBC URL templates:
      • jdbc:db2://${hostname}:${port}/${dbname}
      • jdbc:informix-sqli://${hostname}:${port}/${dbname}:informixserver=${informix_server_name}
      • jdbc:oracle:thin:@${hostname}:${port}:SID
      • jdbc:sqlserver://${hostname}:${port};databasename=${database_name}
    2. Select Predefined properties, such as the username and password authentication.

      If the server is set up for SSL, enter the property in the URL template. Select the Connector supports SSL checkbox to enable the fields needed for using SSL.
      Note: You will need to enter properties in the URL and in the additional properties section. For example, you will need to enter sslConnection=true.
    3. In the Performance properties section, select or enter properties that can improve the efficiency of the connection.
    4. Click Additional properties, and then enter any other properties to connect to the data source. Consult the driver vendor's documentation for supported properties. Use these fields to enter a different authentication method if the data source does not use username and password authentication.
      Example properties with fixed values. These properties will not be visible to users in the connection form.
      • loggerLevel=TRACE
      • encrypt=true
      Example properties with variables. These properties will be visible to users in the connection form. You specify the display name, default value, hover help, and placeholder text in the next step.
      • charset=${charset}
      • readtimeout=${read_timeout}
    Example
    • URL template: jdbc:db2://${hostname}:${port}/${dbname}
    • Predefined properties: Username and password authentication.

    Example values that the user will enter in the connection form:

    • hostname=server1
    • port=50000
    • dbname=my_database
    • username=user_1
    • password=*****

    The JDBC URL will be: jdbc:db2://server1:50000/my_database

    Properties with fixed values will not be in the connection form, but will be used by the connector.
  6. Connection form configuration: Define how each variable property will appear in the connection form. For example, here you can modify the display name, enter the default value, and specify whether a property is required or optional.
    Click Preview and test to see how the connection form will be displayed to users. You can enter values and click Test connection to confirm that the connector is configured correctly.

    The following fields are automatically included in all connection forms and cannot be deleted or changed:

    • Credential setting for Personal or Shared
    • Mask sensitive credentials retrieved through API calls
    • Input method for credentials and certificates. (This field determines the selection for entering values in plain text or by using secrets from a vault.)
    The form configuration settings are saved when you preview the connection or when you click Next.
  7. Summary: Review the display information, JDBC driver, connection properties, and connection form configuration, and then do one of the following actions:
    • Cancel the connector. The connector won't be created. If you are editing a draft, your changes will be lost but the draft will remain.
    • Click Back to return to the Connection form configuration step or click edit (Edit icon) to return to any previous step.
    • Save the connector as a draft.
    • Create the connector. If you create the connector, it will be active and available for users to select from in the list of connections in the New connection page.
      Important:
      • Not all fields or properties can be changed after you create the connector. See Managing custom JDBC connectors.
      • If you edit the connector after you create it, it might disrupt any connections, connected data assets, or jobs that users have already created with it.

What to do next

Test the connector to ensure that it works in the services and with the tools that you use to connect to the data source.