Ajout Pilote JDBC

Modifié par Aurelie Bertrand le 2023/06/12 15:53

Pré-requis
Installation
Drivers préconfigurés non inclus

Ce document décrit la procédure d'ajout d'un nouveau pilote JDBC dans DigDash Enterprise.

Pré-requis

Avoir le pilote JDBC sous la forme d'un ou plusieurs fichiers JAR et sa documentation. Propriétés spécifiques avancées

Installation

Déploiement des fichiers

(optionnel, si les webapps n'ont pas encore été déployées). Démarrez le serveur DigDash Enterprise et attendre le déploiement complet des webapps
Arrêtez le serveur
Copiez le ou les fichiers JAR du pilote JDBC dans les dossiers suivants :
/home/digdash/webapps/default/ddenterpriseapi/WEB-INF/lib
/home/digdash/webapps/default/studio/WEB-INF/lib
Le pilote JDBC doit maintenant être enregistré dans DigDash Enterprise Serveur.

Enregistrement du pilote JDBC

Pour cela éditez le fichier suivant :

<DD Install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF/classes/resources/config/sqldriverrepository.xml

Ajoutez une entrée XML au fichier sqldriverrepository.xml, qui ressemble à l'exemple suivant :

<SQLDriver id="MY_DRIVER"
name="My Driver"
url="mydriver:"
manufacturer="My Driver Company"
class="com.mydriver.MyDriver"
urlsample="jdbc:mydriver:<database>?<options>"
availability="both">
<properties></properties>
</SQLDriver>

Important : Certains caractères sont réservés en XML : '&', '"', '<' or '>'. Donc si vous utilisez certains de ces caractères, assurez-vous de les encoder vers leur entités XML correspondantes.

Correspondances XML :

& => &
" => "
< => <
> => >

Exemple :

(FAUX) urlsample="jdbc:mydriver:dbtest?opt1=0&opt2="value""
(VRAI) urlsample="jdbc:mydriver:dbtest?opt1=0&opt2="value""

Paramètres :

id : un identifiant utilisé de manière interne par DigDash Enterprise, choisir une chaîne non existante, par convention en majuscule, sans espace
name : Le nom du pilote JDBC affiché dans l'interface de la console d'administration
url : Le préfixe de l'URL du pilote JDBC (sans "jdbc:"). Consulter la documentation fournie avec le pilote JDBC
manufacturer : Le nom du vendeur/développeur du pilote JDBC
class: chemin de la classe java principale du pilote. Consulter la documentation fournie avec le pilote JDBC.
Optionnel: Les pilotes JDBC de norme JDBC 4 n'ont pas besoin de la classe java pour être pris en compte.
urlsample : Exemple d'URL affiché dans l'interface de la console d'administration
availability : réservé. Laisser à "both".

Important : Le déploiement est perdu lorsque vous mettez à jour le fichier ddenterpriseapi.war. Suivre cette procédure de déploiement du pilote à chaque fois que vous mettez DigDash Enterprise à jour.

Dans le fichier sqldriverrepository.xml il y a quelques exemples de XML pour des pilotes non fournis avec DigDash.

Propriétés spécifiques avancées

Il est possible de spécifier des propriétés spécifiques pour certains pilotes JDBC. Ces propriétés sont à écrire à l’intérieur du tag <properties></properties> sous la forme :

Les propriétés supportées sont :

FORCE_FORWARD_ONLY (non défini | false | true)

Description : spécifie le type de curseur JDBC utilisé par le Studio pour la prévisualisation des résultats d’une requête SQL. Par défaut le Studio utilise un curseur TYPE_INSENTIVE_SCROLL pour la prévisualisation des résultats, mais certaines bases de données ne le supporte pas. Si votre pilote/BDD ne supporte que les curseurs de TYPE_FORWARD_ONLY, vous pouvez le spécifier avec le propriété FORCE_FORWARD_ONLY. Les valeurs possibles sont :

false (ou propriété non définie) : Le type de curseur est automatique, TYPE_SCROLL_INSENTIVE dans la plupart des cas sauf pour HIVE, IMPALA et SAPHANA
true : Le type de curseur utilisé par le Studio est TYPE_FORWARD_ONLY

PING_SQL (non défini | requête SQL | chaîne vide)

Description : DigDash Enterprise teste la connexion avec la base de données en utilisant la méthode JDBC Connection.isValid(). Sur certains drivers JDBC cette méthode ne fonctionne pas. Dans ce cas, DigDash utilise une autre méthode alternative de sélection simple, la plupart du temps une requête « select 1 ».

La propriété PING_SQL permet de spécifier une requête simple pour tester la connexion à la BDD, en fonction de votre pilote. Les valeurs possibles sont :

Propriété non définie : La requête de ping alternative est automatiquement déterminée par DigDash Enteprise : « select 1 » sauf dans les cas de pilotes ORACLE, FIREBIRD, SAPHANA, DB2_AS400 et DB2
requête SQL non vide : la requête spécifiée sera utilisée pour tester la connexion à la base de données. Exemple :
<property name="PING_SQL" value="select 1 from all_tables" />
chaîne vide : Cas spécial où on désactive le ping alternatif. Si la méthode JDBC Connection.isValid() échoue, alors on considère quand même la base de données comme accessible. Exemple :

<property name="PING_SQL" value="" ></property>

USE_FETCH_FIRST_IN_STUDIO (non défini | false | true)

Description : Cette propriété n’est active que pour la prévisualisation du résultat de la requête SQL dans l’écran de configuration de la source de données (Studio). Elle modifie la requête et y ajoute "FETCH FIRST n ROWS ONLY" (n est remplacée par le nombre de lignes de prévisualisation). Elle est utile pour les pilotes qui ne supportent pas la fonctionnalité JDBC Statement.setMaxRows, comme par exemple le driver JDBC AS400. Les valeurs possibles sont :

false (ou propriété non définie) : La limite de prévisualisation est spécifiée en utilisant la méthode JDBC Statement.setMaxRows
true : La limite de prévisualisation est spécifiée en ajoutant FETCH FIRST n ROWS ONLY au SQL dans le Studio.

FORBID_POOL_CONNECTION (non défini | false | true)

Description : Interdit l’usage d’un pool de connexions JDBC par le serveur DigDash Enterprise. Un pool de connexion permet d’optimiser les accès à une base de données en laissant les connexions ouvertes et réutilisables pour d’autres requêtes. Dans certains cas il est souhaitable de forcer DigDash Enterprise à ne pas utiliser un pool de connexions JDBC, par exemple pour s’assurer que des connexions ne restent pas ouvertes trop longtemps sur la base de données. Cette propriété répond à ce besoin. Les valeurs possibles sont :

false (ou propriété non définie) : Un pool de connexions JDBC peut être utilisé pour ce pilote
true : Le pool de connexions JDBC n’est pas utilisé pour ce pilote et chaque requêtes SQL aura sa propre connexion JDBC indépendante

POOL_VALIDATION_QUERY (non défini | requête SQL)

Description : Permet de spécifier une requête de validation utilisée par le pool de connexions JDBC Apache DBCP2. Certains drivers JDBC ne spécifient pas cette requête (ex. « select 1 ») et peuvent donc dysfonctionner lorsqu’ils sont instanciés par le pool de connexions JDBC. Cette propriétés permet de spécifier cette requête de validation. Elle est similaire à la propriété validationQuery configurable via les propriétés du pool Apache DBCP2. Les valeurs possibles sont :

propriété non définie : Aucune requête de validation spécifique n’est configurée pour ce driver. Le pool utilisera la requête de validation par défaut pour ce driver (s’il en spécifie une)
requête SQL non vide : la requête spécifiée sera utilisée pour tester la connexion à la base de données par le pool de connexion Apache DBCP. (Exemple : select 1)

DEFAULT_FETCH_SIZE (non défini | chiffre)

Description : Permet de spécifier un nombre de lignes de données maximal par défaut à récupérer en une fois par DigDash Enterprise. Certains drivers JDBC (ex. Postgresql) récupèrent par défaut toutes les lignes d'une requête en une seule fois ce qui peut conduire à une utilisation élevée de mémoire vive et l'impossibilité d'annuler la synchronisation d'une source de données SQL qui utilise un de ces drivers. Ce paramètre permet d'éviter ce cas en spécifiant un nombre plus raisonnable de lignes à récupérer (ex. 100). Par example un DEFAULT_FETCH_SIZE de 1000 récupérera les premières 1000 lignes et lorsque DigDash aura besoin de récupérer la 1001ième ligne, le driver JDBC récupérera les prochaines 1000 lignes. Ce paramètre peut aussi être modifié au niveau d'une source de données de type SQL lors de sa création ou édition dans le studio.

TABLE_TYPES (non défini | types de tables séparés par des virgules)

Description : Permet de spécifier les types de tables à afficher dans l'assistant de requêtes SQL. Ce paramètre peut être utile dans les cas où certains types de tables spécifiques sont requis (par exemple "CALC VIEW" pour les external calculation views de SAP HANA). La valeur par défaut est "TABLE,VIEW" si la propriété n'est pas définie pour le driver utilisé.

Drivers préconfigurés non inclus

Les connectivités aux bases de données suivantes sont disponibles par défaut dans Digdash Enterprise, mais leur driver JDBC n'est pas livré et nécessite une installation supplémentaire :

MySQL

DigDash Enterprise peut se connecter à MySQL 5.5 et versions suivantes en utilisant le driver MariaDB Java connector. Dans la grande majorité des cas, ce driver est suffisant pour se connecter à une base de données MySQL (et MariaDB). Cependant, pour se connecter à une version de MySQL précédente, ou pour utiliser des fonctionnalités spécifiques uniquement disponible dans le driver MySQL natif correspondant à votre version de base de données, il faut télécharger ce dernier depuis le site de MySQL : https://dev.mysql.com/downloads/connector/j/

Le driver MariaDB inclus dans DigDash Enterprise prend en charge les connections jdbc:mysql:// et jdbc:mariadb://. Pour pouvoir utiliser le drive MySQL natif, il faut donc supprimer le driver MariaDB des webapps ddenterpriseapi et studio. Le fichier à supprimer est mariadb-java-client-*.jar. Garder les deux drivers JDBC peut entrainer des incompatibilités lors de la connexion à MySQL.
Cependant, il est possible de garder aussi le driver MariaDB, pour le cas où vous avez une base de données MySQL et une base de données MariaDB. Pour cela il faut ajouter le paramètre &disableMariaDbDriver dans la chaine de connexion vers votre base de données MySQL (jdbc:mysql://...&disableMariaDbDriver). Consultez le site https://mariadb.com/kb/en/about-mariadb-connector-j/ pour plus d'informations.

Si vous décidez d'installer le driver MySQL, vous pouvez constater que le fichier sqldriverrepository.xml fourni dans DigDash Enterprise contient déjà une définition commentée pour ce driver (voir ci-dessous). Il faut décommenter cette définition (et donc commenter celle qui référence le driver MariaDB).
Cette définition concerne les nouvelles versions du driver à partir de MySQL Connector/J 8.0. Les drivers MySQL les plus récents sont censés être compatibles avec toutes les versions des bases de données MySQL. Cependant, si vous préférez utiliser une version de driver plus ancienne, il faut supprimer la propriété class et renommer la propriétés classOld en class, car le nom de la classe du driver à changé en version Connector/J 8.0. Dans tous les cas, consultez la documentation du driver que vous utilisez pour confirmer ces informations.

Teradata

Le driver JDBC Teradata est téléchargeable sur le site de Teradata à l'adresse suivante : https://downloads.teradata.com/download/connectivity/jdbc-driver. Le téléchargement nécessite un compte utilisateur chez Teradata.

IBM DB2

Le driver JDBC IBM DB2 est téléchargeable sur le site de IBM à l'adresse suivante : https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads. Le téléchargement nécessite un compte utilisateur chez IBM. Le driver est constitué de 2 fichiers .jar, un pour le driver, un pour la license. Vous pouvez aussi trouver ces fichiers dans votre installation DB2.

Microsoft SQL Server

DigDash Enterprise est livré avec un driver open source jTDS compatible avec Microsoft SQL Server. Cependant si vous souhaitez utiliser des fonctionnalités spécifiques uniquement disponibles avec le driver natif SQL Server de Microsoft, il faut le télécharger sur le site : https://docs.microsoft.com/fr-fr/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15.

Hadoop Hive

L'installation du driver Hadoop Hive dépend de votre installation de Hadoop (Exemple: Cloudera, Hortonworks...). Il est préférable d'utiliser le driver fourni et correspondant à votre installation Hadoop (liste non exhaustive) :

Cloudera : https://www.cloudera.com/downloads/connectors/hive/jdbc/2-6-5.html
Hortonworks : https://www.progress.com/jdbc/hortonworks-hive

SAP HANA

Le driver JDBC pour SAP HANA peut être téléchargé ici : https://mvnrepository.com/artifact/com.sap.cloud.db.jdbc/ngdbc

Une configuration du driver SAP HANA est livrée par DigDash dans le fichier sqldriverrepository.xml. Pour activer l'affichage des external calculation views dans l'assistant de requêtes SQL, assurez-vous d'avoir configuré la propriété TABLE_TYPES pour qu'elle contienne le type "CALC VIEW". Notre configuration pour SAP HANA utilise "TABLE,VIEW,CALC VIEW" comme valeur pour la propriété TABLE_TYPES.