• Pré-requis
• Installation
  • Déploiement des fichiers
  • Enregistrement du pilote JDBC
  • Propriétés spécifiques avancées
    • FORCE_FORWARD_ONLY (non défini | false | true)
    • PING_SQL (non défini | requête SQL | chaîne vide)
    • USE_FETCH_FIRST_IN_STUDIO (non défini | false | true)
    • FORBID_POOL_CONNECTION (non défini | false | true)
    • POOL_VALIDATION_QUERY (non défini | requête SQL)
    • DEFAULT_FETCH_SIZE (non défini | chiffre)
    • TABLE_TYPES (non défini | types de tables séparés par des virgules)
    • FORBIDDEN_KEYWORDS (non défini | mots clés séparés par des virgules)
    • FORBIDDEN_IN_URL (non défini | paramètres dans l'URL de la base de données séparés par des virgules )
• Drivers préconfigurés non inclus
  • MySQL
  • Teradata
  • IBM DB2
  • Microsoft SQL Server
  • Hadoop Hive
  • SAP HANA

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

1. (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
2. Arrêtez le serveur
3. 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
4. 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 :

Correspondances XML :

• & => &amp;
• " => &quot;
• < => &lt;
• > => &gt;

Exemple :

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

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".

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é.

FORBIDDEN_KEYWORDS (non défini | mots clés séparés par des virgules)

Propriété optionnelle
Description : Permet de spécifier des mots clés interdits dans les requêtes SQL. Le paramètre a pour valeur une liste de mots clés interdits séparés par des virgules (non sensible à la casse).

Exemple (driver H2) :

<property name="FORBIDDEN_KEYWORDS" value="CSVREAD,CSVWRITE,FILE_READ,FILE_WRITE"/>

Si la requête SQL contient un des mots clés interdits, pour le driver concerné, elle va échouer (SQLSecurityException) et l'évenement sera enregistré dans Security Auditor.

FORBIDDEN_IN_URL (non défini | paramètres dans l'URL de la base de données séparés par des virgules )

Propriété optionnelle
Description : Permet de spécifier des paramètres interdits dans l'URL de la base de données. La propriété a pour valeur une liste de paramètres interdits dans l'URL de la base de données, séparés par des virgules (non sensible à la casse).

Exemple (valeur par défaut pour le driver H2) :

 <property name="FORBIDDEN_IN_URL" value="INIT="/>

Si l'URL de la base de données contient un des paramètres interdits, pour le driver concerné, cela va échouer (SQLSecurityException) et l'événement sera enregistré dans Security Auditor.

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/

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.