
[[install-jdbc-driver]]
= Install JDBC Driver on Minion

To detect, poll, or collect any JDBC service by a Minion, you must install the corresponding JDBC driver on that Minion.

We reference the `repository directory` relative to the Minion home directory.
Depending on your operating system, the home directory is `/opt/minion`.

. Download the JDBC driver JAR from a repository (for example, a public https://mvnrepository.com/artifact/mysql/mysql-connector-java/8.0.30[Maven repository]).
+
.Alternately, you can download using Maven, which will create the required directory structure for you, in your local Maven repository (typically  ~/.m2/repository/).
[source, console]
----
mvn dependency:get -Dartifact=mysql:mysql-connector-java:8.0.22
----

. Install the JAR file in the repository directory, following the Maven repository pattern.
+
For MySQL 8.0.30, the path would be `repositories/default/mysql/mysql-connector-java/8.0.30/mysql-connector-java-8.0.30.jar`.

. Create a Karaf feature for the MySQL JDBC driver.

.Create a features configuration file
[source, console]
----
sudo vi deploy/jdbc-mysql.xml
----

.Add the following content to download the MySQL JDBC driver
[source, jdbc-mysql.xml]
[subs="verbatim,attributes"]
-----
<?xml version="1.0" encoding="UTF-8"?>
<features name="opennms-{page-component-version}"<1>
          xmlns="http://karaf.apache.org/xmlns/features/v1.4.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.4.0 http://karaf.apache.org/xmlns/features/v1.4.0">
  <feature name="mysql-bundle" version="8.0.22" install="auto"><2>
    <bundle>wrap:mvn:mysql/mysql-connector-java/8.0.22</bundle><3>
  </feature>
</features>
-----
<1> The version should match your {page-component-title} Core version.
<2> The bundle is named `mysql-bundle`, and the version number is set to `8.0.30`.
<3> Bundle to download version `8.0.30` with Maven from official repositories.

As soon you write the file, Karaf picks up the feature and tries to install it.
You can troubleshoot the installation using `$\{MINION_HOME}/data/log/karaf.log`.

.Connect to the Karaf shell
[source,console]
----
ssh -p 8201 admin@localhost
----

.Verify feature installation and start-up
[source, karaf]
----
feature:list | grep mysql
----

.MySQL bundle is installed and available
[source, output]
[subs="verbatim,attributes"]
----
mysql-bundle   | 8.0.22   | x        | Started     | opennms-{page-component-version}  |
----

== Example features files for common JDBC drivers

.MS SQLServer using 12.10.1.jre11
[source, console]
[subs="verbatim,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<features name="opennms-{page-component-version}"
          xmlns="http://karaf.apache.org/xmlns/features/v1.4.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.4.0 http://karaf.apache.org/xmlns/features/v1.4.0">
  <feature name="mssql-bundle" version="12.10.1.jre11" install="auto">
    <bundle>wrap:mvn:com.microsoft.sqlserver/mssql-jdbc/12.10.1.jre11</bundle>
  </feature>
  <feature name="org.osgi.service.jdbc" version="1.1.0" install="auto">
    <bundle>wrap:mvn:org.osgi/org.osgi.service.jdbc/1.1.0</bundle><1>
  </feature>
</features>
----
<1> The MSSQL JDBC driver has an additional dependency on `org.osgi.service.jdbc/1.1.0`

.MariaDB using version 3.5.4
[source, console]
[subs="verbatim,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<features name="opennms-{page-component-version}"
          xmlns="http://karaf.apache.org/xmlns/features/v1.4.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.4.0 http://karaf.apache.org/xmlns/features/v1.4.0">
  <feature name="mariadb-bundle" version="3.5.4" install="auto">
      <bundle>wrap:mvn:org.mariadb.jdbc/mariadb-java-client/3.5.4</bundle>
  </feature>
</features>
----


.Oracle JDBC using version 23.8.0.25.04
[source, console]
[subs="verbatim,attributes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<features
        name="opennms-{page-component-version}"
        xmlns="http://karaf.apache.org/xmlns/features/v1.4.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.4.0 http://karaf.apache.org/xmlns/features/v1.4.0">
    <feature name="oracle-bundle" version="23.8.0.25.04" install="auto">
          <bundle>wrap:mvn:com.oracle.jdbc/jdbc/23.8.0.25.04</bundle><1>
    </feature>
</features>
----
. The Oracle JDBC driver jar must be renamed to `jdbc-$\{VERSION}.jar` in order to be resolved.
+
The repository path for current Oracle JDBC is `com/oracle/jdbc/jdbc/$\{VERSION}/jdbc-$\{VERSION}.jar`
