2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1673947 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_dbd.xml.meta">
28 <description>Gestion des connexions à une base de données SQL</description>
29 <status>Extension</status>
30 <sourcefile>mod_dbd.c</sourcefile>
31 <identifier>dbd_module</identifier>
34 <p>Le module <module>mod_dbd</module> gère les connexions
35 à une base de données SQL via <glossary>APR</glossary>. Il permet
36 aux modules qui requièrent des fonctions liées aux bases de données
37 SQL de se connecter à une base de données à la demande, et s'efforce
38 de conférer aux bases de données une efficacité et une
39 évolutivité optimales pour les MPMs threadés ou non threadés. Pour
40 plus de détails, voir le site web <a
41 href="http://apr.apache.org/">APR</a>,
42 ainsi que cette vue d'ensemble de l'<a
43 href="http://people.apache.org/~niq/dbd.html">environnement de
44 développement d'Apache DBD</a> par son développeur initial.
48 <seealso><a href="../misc/password_encryptions.html">Formats des mots de
51 <section id="pooling"><title>Regroupement des connexions</title>
52 <p>Ce module gère de manière optimisée en fonction de la plate-forme
53 les connexions aux bases de données. Sur les plates-formes non
54 threadées, il maintient une connexion persistente à la manière d'un
55 LAMP classique (Linux, Apache, Mysql, Perl/PHP/Python). Sur les
56 plates-formes threadées, il maintient un <em>groupe de
57 connexions</em> à la fois plus évolutif et plus efficace, comme
58 décrit dans <a href="http://www.apachetutor.org/dev/reslist">cet
59 article d'ApacheTutor</a>. Notez que <module>mod_dbd</module>
60 remplace les modules présentés dans cet article.</p>
63 <section id="API"><title>API DBD d'Apache</title>
64 <p><module>mod_dbd</module> exporte cinq fonctions que d'autres
65 modules pourront utiliser. L'API se présente comme suit :</p>
67 <highlight language="c">
70 apr_dbd_driver_t *driver;
74 /* Fonctions exportées pour accéder à la base de données */
76 /* ouvre une connexion qui DEVRA être explicitement fermée.
77 * Renvoie NULL en cas d'erreur
79 AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
81 /* ferme une connexion ouverte avec ap_dbd_open */
82 AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
84 /* acquiert une connexion qui aura la durée de vie de la requête et qui
85 * NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
86 * d'erreur. C'est la fonction recommandée pour la plupart des
89 AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
91 /* acquiert une connexion qui aura la durée de vie d'une connexion et
92 * qui NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
95 AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
97 /* Prépare une requête qu'un module client pourra utiliser */
98 AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
100 /* Exporte aussi ces fonctions à titre optionnel mour les modules qui
101 * péfèreraient les utiliser */
102 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
103 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
104 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
105 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
106 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
110 <section id="prepared"><title>Requêtes SQL préparées</title>
111 <p><module>mod_dbd</module> supporte les requêtes SQL préparées pour
112 le compte des modules qui pourraient les utiliser. Chaque requête
113 préparée doit posséder un nom (étiquette), et est stockée dans un
114 condensé (hash) : les condensés sont du type
115 <code>apr_dbd_prepared_t</code> et s'utilisent dans toute requête
116 SQL ou commande select préparée par apr_dbd.</p>
118 <p>Il est du ressort des modules utilisateurs de dbd d'utiliser les
119 requêtes préparées et de préciser quelles requêtes doivent être
120 spécifiées dans httpd.conf, ou de fournir leurs propres directives
121 et d'utiliser <code>ap_dbd_prepare</code>.</p>
123 <note type="warning"><title>Avertissement</title>
124 Lorsqu'on utilise des requêtes préparées avec des bases de
125 données MySQL, il est préférable de définir
126 <code>reconnect</code> à 0 dans la chaîne de connexion, afin
127 d'éviter des erreurs provoquées par un client MySQL qui se
128 reconnecterait sans réinitialiser correctement les requêtes
129 préparées. Si <code>reconnect</code> est défini à 1, toute
130 connexion défectueuse sera sensée être réparée, mais comme
131 mod_dbd n'en est pas informé, les requêtes préparées seront
136 <section id="security">
137 <title>AVERTISSEMENT DE SECURITE</title>
138 <p>Toute application web impliquant une base de données doit se
139 protéger elle-même contre les attaques de type injection SQL. Dans
140 la plupart des cas Apache DBD est sûr, car les applications
141 utilisent des requêtes préparées, et les entrées non sûres ne seront
142 utilisées qu'à titre de données. Bien entendu, si vous l'utilisez
143 via un module tiers, vous devez être au fait des précautions à
145 <p>Cependant, le pilote <var>FreeTDS</var> est <strong>non
146 sûr</strong> de par sa nature même. Comme la bibliothèque
147 sous-jacente ne supporte pas les requêtes préparées, le pilote en
148 effectue une émulation, et les entrées non sûres sont fusionnées
149 avec la requête SQL.</p>
150 <p>Il peut être sécurisé en <em>décontaminant</em> toutes les
151 entrées : un processus inspiré de la recherche de contaminations de
152 Perl (NdT : <code>taint checking</code>). Chaque entrée est comparée
153 à une expression rationnelle, et
154 seules les entrées qui correspondent sont utilisées, en accord avec
155 le raccourci Perl :</p>
157 <pre><code> $untrusted =~ /([a-z]+)/;
158 $trusted = $1;</code></pre>
160 <p>Pour utiliser ceci, les expressions rationnelles de
161 décontamination doivent être incluses dans les requêtes préparées.
162 L'expression rationnelle doit se situer immédiatement après le
163 caractère % dans la requête préparée, et doit être entourée
164 d'accolades {}. Par exemple, si votre application attend une entrée
165 alphanumérique, vous pouvez utiliser :</p>
167 <code>"SELECT foo FROM bar WHERE input = %s"</code>
169 <p>avec d'autres pilotes, et ne risquer au pire qu'une requête
170 en échec. Mais avec FreeTDS, vous devez utiliser :</p>
172 <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
174 <p>tout ce qui ne correspond pas à l'expression rationnelle est
175 alors rejeté, et la requête est ainsi désormais sûre.</p>
176 <p>Alternativement, vous pouvez utiliser le pilote ODBC tiers, qui
177 offre la sécurité des requêtes préparées authentiques.</p>
180 <name>DBDriver</name>
181 <description>Spécifie un pilote SQL</description>
182 <syntax>DBDriver <var>nom</var></syntax>
183 <contextlist><context>server config</context><context>virtual host</context>
187 <p>Cette directive spécifie un pilote apr_dbd par son
188 nom. Le pilote doit être installé sur votre système (sur la plupart
189 des systèmes, il s'agit d'un objet partagé ou d'une dll). Par
190 exemple, <code>DBDriver mysql</code> va sélectionner le pilote MySQL
191 dans la bibliothèque apr_dbd_mysql.so.</p>
196 <name>DBDParams</name>
197 <description>Paramètres de la connexion à la base de
198 données</description>
200 <var>param1</var>=<var>valeur1</var>[,<var>param2</var>=<var>valeur2</var>]</syntax>
201 <contextlist><context>server config</context><context>virtual host</context>
205 <p>Cette directive spécifie des paramètres selon les
206 besoins du pilote concerné. En général, les paramètres à passer
207 concernent tout ce qui n'a pas de valeur par défaut comme le nom
208 d'utilisateur, le mot de passe, le nom de la base de données, le nom
209 d'hôte et le numéro de port de la connexion.</p>
210 <p>Les paramètres de la chaîne de connexion en fonction des
211 différents pilotes comprennent :</p>
213 <dt>FreeTDS (pour MSSQL et SyBase)</dt>
214 <dd>username, password, appname, dbname, host, charset, lang, server</dd>
216 <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
218 <dd>user, pass, dbname, server</dd>
220 <dd>La chaîne de connexion est passée directement à <code>PQconnectdb</code></dd>
222 <dd>La chaîne de connexion est scindée avec comme séparateur le
223 caractère ':', et <code>partie1:partie2</code> est utilisé dans
224 <code>sqlite_open(partie1, atoi(partie2), NULL)</code></dd>
226 <dd>La chaîne de connexion est passée directement à <code>sqlite3_open</code></dd>
228 <dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
234 <name>DBDPersist</name>
235 <description>Utiliser ou non des connexions persistentes</description>
236 <syntax>DBDPersist On|Off</syntax>
237 <contextlist><context>server config</context><context>virtual host</context>
241 <p>Si cette directive est définie à Off, les connexions persistentes
242 et les connexions groupées sont désactivées. À la demande d'un
243 client, une nouvelle connexion à la base de données est ouverte, et
244 fermée immédiatement à l'issue du traitement. Cette configuration ne
245 doit être utilisée qu'à des fins de débogage, ou sur des serveurs à
248 <p>Par défaut, les groupes de connexions persistentes sont activés
249 (ou une seule connexion persistente du style LAMP pour les serveurs
250 non threadés), et c'est la configuration qui devrait être utilisée
251 dans la plupart des cas sur un serveur en production.</p>
253 <p>Avant la version 2.2.2, cette directive n'acceptait que les
254 valeurs <code>0</code> et <code>1</code> au lieu de <code>Off</code>
255 et <code>On</code>, respectivement.</p>
260 <name>DBDPrepareSQL</name>
261 <description>Définit une requête SQL préparée</description>
262 <syntax>DBDPrepareSQL <var>"requête SQL"</var> <var>étiquette</var></syntax>
263 <contextlist><context>server config</context><context>virtual host</context>
267 <p>Pour les modules tels que les modules d'authentification, qui
268 utilisent de manière répétée la même requête SQL, on peut optimiser
269 les performances en préparant la requête une fois pour toutes au
270 démarrage, plutôt qu'à chaque utilisation. Cette directive permet de
271 préparer une requête SQL et de lui assigner une étiquette.</p>
277 <description>Nombre minimum de connexions</description>
278 <syntax>DBDMin <var>nombre</var></syntax>
279 <default>DBDMin 1</default>
280 <contextlist><context>server config</context><context>virtual host</context>
284 <p>Cette directive définit le nombre minimum de connexions
285 par processus (plates-formes threadées seulement).</p>
291 <description>Nombre maximum de connexions maintenues</description>
292 <syntax>DBDKeep <var>nombre</var></syntax>
293 <default>DBDKeep 2</default>
294 <contextlist><context>server config</context><context>virtual host</context>
298 <p>Cette directive définit le nombre maximum de connexions
299 à maintenir par processus, en dehors de celles servant à gérer les
300 pics de demandes (plates-formes threadées seulement).</p>
306 <description>Nombre maximum de connexions</description>
307 <syntax>DBDMax <var>nombre</var></syntax>
308 <default>DBDMax 10</default>
309 <contextlist><context>server config</context><context>virtual host</context>
313 <p>Cette directive définit le nombre maximum effectif de
314 connexions par processus (plates-formes threadées seulement).</p>
319 <name>DBDExptime</name>
320 <description>Durée de vie des connexions inactives</description>
321 <syntax>DBDExptime <var>durée en secondes</var></syntax>
322 <default>DBDExptime 300</default>
323 <contextlist><context>server config</context><context>virtual host</context>
327 <p>Cette directive définit la durée de vie des connexions
328 inactives lorsque le nombre de connexions spécifié par la directive
329 DBDKeep a été dépassé (plates-formes threadées seulement).</p>
334 <name>DBDInitSQL</name>
335 <description>Exécute une instruction SQL après connexion à une base de
336 données</description>
337 <syntax>DBDInitSQL <var>"instruction SQL"</var></syntax>
338 <contextlist><context>server config</context><context>virtual host</context>
342 <p>Les modules qui le souhaitent peuvent exécuter une ou plusieurs
343 instructions SQL après connexion à une base de données. Par exemple
344 initialiser certaines valeurs, ou ajouter une entrée dans le journal
345 lors d'une nouvelle connexion à la base de données.</p>