Code source wiki de Ajout Pilote JDBC

Modifié par jhurst le 2022/04/28 16:42
Afficher les derniers auteurs
1 {{ddtoc}}{{/ddtoc}}
2
3 ----
4
5 Ce document décrit la procédure d'ajout d'un nouveau pilote JDBC dans DigDash Enterprise.
6
7 = Pré-requis =
8
9 Avoir le pilote JDBC sous la forme d'un ou plusieurs fichiers JAR et sa documentation. [[Propriétés spécifiques avancées>>||anchor="HPropriE9tE9sspE9cifiquesavancE9es"]]
10
11 = Installation =
12
13 == Déploiement des fichiers ==
14
15 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
16 1. Arrêtez le serveur
17 1. Copiez le ou les fichiers JAR du pilote JDBC dans les dossiers suivants :
18 **<DD Install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF/lib**
19 **<DD Install>/apache-tomcat/webapps/studio/WEB-INF/lib**
20 1. Le pilote JDBC doit maintenant être enregistré dans DigDash Enterprise Serveur.
21
22 == Enregistrement du pilote JDBC ==
23
24 Pour cela éditez le fichier suivant :
25
26 **<DD Install>/apache-tomcat/webapps/ddenterpriseapi/WEB-INF/classes/resources/config/sqldriverrepository.xml**
27
28 Ajoutez une entrée XML au fichier **sqldriverrepository.xml**, qui ressemble à l'exemple suivant :
29
30 {{code language="xml" cssClass="notranslate"}}
31 <SQLDriver id="MY_DRIVER"
32 name="My Driver"
33 url="mydriver:"
34 manufacturer="My Driver Company"
35 class="com.mydriver.MyDriver"
36 urlsample="jdbc:mydriver:<database>?<options>"
37 availability="both">
38 <properties></properties>
39 </SQLDriver>
40 {{/code}}
41
42 (% class="box warningmessage" %)
43 (((
44 //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.//
45 )))
46
47 Correspondances XML :
48
49 * **&** => **&amp;**
50 * **"** => **&quot;**
51 * **<** => **&lt;**
52 * **>** => **&gt;**
53
54 Exemple :
55
56 * (FAUX) urlsample="jdbc:mydriver:dbtest?opt1=0&opt2="value""
57 * (VRAI) urlsample="jdbc:mydriver:dbtest?opt1=0&amp;opt2=&quot;value&quot;"
58
59 Paramètres :
60
61 * **id **: un identifiant utilisé de manière interne par DigDash Enterprise, choisir une chaîne non existante, par convention en majuscule, sans espace
62 * **name **: Le nom du pilote JDBC affiché dans l'interface de la console d'administration
63 * **url **: Le préfixe de l'URL du pilote JDBC (sans "jdbc:"). Consulter la documentation fournie avec le pilote JDBC
64 * **manufacturer **: Le nom du vendeur/développeur du pilote JDBC
65 * **class**: chemin de la classe java principale du pilote. Consulter la documentation fournie avec le pilote JDBC.
66 //Optionnel: Les pilotes JDBC de norme JDBC 4 n'ont pas besoin de la classe java pour être pris en compte.//
67 * **urlsample **: Exemple d'URL affiché dans l'interface de la console d'administration
68 * **availability **: réservé. Laisser à "both".
69
70 (% class="box warningmessage" %)
71 (((
72 //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.//
73 )))
74
75 Dans le fichier **sqldriverrepository.xml** il y a quelques exemples de XML pour des pilotes non fournis avec DigDash.
76
77 == Propriétés spécifiques avancées ==
78
79 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 :
80
81 {{code cssClass="notranslate" language="xml"}}
82 <properties>
83
84 <property name="nom_propriété" value="valeur_propriété" ></property>
85
86 <properties>
87 {{/code}}
88
89 Les propriétés supportées sont :
90
91 === FORCE_FORWARD_ONLY (non défini | false | true) ===
92
93 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 :
94
95 * **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
96 * **true **: Le type de curseur utilisé par le Studio est TYPE_FORWARD_ONLY
97
98 === PING_SQL (non défini | requête SQL | chaîne vide) ===
99
100 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 ».
101
102 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 :
103
104 * **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
105 * **requête SQL non vide **: la requête spécifiée sera utilisée pour tester la connexion à la base de données. Exemple :
106 <property name="PING_SQL" value="select 1 from all_tables" />
107 * **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 :
108 \\{{code language="xml" cssClass="notranslate"}}<property name="PING_SQL" value="" ></property>{{/code}}
109
110 === USE_FETCH_FIRST_IN_STUDIO (non défini | false | true) ===
111
112 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[[image:icon:thumb_down]]**, comme par exemple le driver JDBC AS400. Les valeurs possibles sont :
113
114 * **false** (ou **propriété non définie**) : La limite de prévisualisation est spécifiée en utilisant la méthode JDBC **Statement.setMaxRows[[image:icon:thumb_down]]**
115 * **true **: La limite de prévisualisation est spécifiée en ajoutant FETCH FIRST n ROWS ONLY au SQL dans le Studio.
116
117 === FORBID_POOL_CONNECTION (non défini | false | true) ===
118
119 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 :
120
121 * **false** (ou **propriété non définie**) : Un pool de connexions JDBC peut être utilisé pour ce pilote
122 * **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
123
124 === POOL_VALIDATION_QUERY (non défini | requête SQL) ===
125
126 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 :
127
128 * **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)
129 * **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)
130
131 === DEFAULT_FETCH_SIZE (non défini | chiffre) ===
132
133 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.
134
135 = Drivers préconfigurés non inclus =
136
137 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 :
138
139 == MySQL ==
140
141 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/>>https://dev.mysql.com/downloads/connector/j/]]
142
143 (% class="box warningmessage" %)
144 (((
145 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.
146 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/>>https://mariadb.com/kb/en/about-mariadb-connector-j/]] pour plus d'informations.
147 )))
148
149 (% class="box warningmessage" %)
150 (((
151 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).
152 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.
153
154 {{code cssClass="XML" language="XML"}}
155 <SQLDriver id="MYSQL" name="MySQL"
156 url="mysql://"
157 class="com.mysql.cj.jdbc.Driver"
158 classOld="com.mysql.jdbc.Driver"
159 manufacturer="MySQL"
160 urlsample="$ui.DataBase.MySqlSampleUrl"
161 availability="both">
162 <properties>
163 </properties>
164 </SQLDriver>
165
166 {{/code}}
167 )))
168
169 == Teradata ==
170
171 Le driver JDBC Teradata est téléchargeable sur le site de Teradata à l'adresse suivante : [[https:~~/~~/downloads.teradata.com/download/connectivity/jdbc-driver>>https://downloads.teradata.com/download/connectivity/jdbc-driver]]. Le téléchargement nécessite un compte utilisateur chez Teradata.
172
173 == IBM DB2 ==
174
175 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>>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.
176
177 == Microsoft SQL Server ==
178
179 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>>https://docs.microsoft.com/fr-fr/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15]].
180
181 == Hadoop Hive ==
182
183 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) :
184
185 * Cloudera : [[https:~~/~~/www.cloudera.com/downloads/connectors/hive/jdbc/2-6-5.html>>url:https://www.cloudera.com/downloads/connectors/hive/jdbc/2-6-5.html]]
186 * Hortonworks : [[https:~~/~~/www.progress.com/jdbc/hortonworks-hive>>url:https://www.progress.com/jdbc/hortonworks-hive]]