1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1760180 -->
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="connecting"><title>Connexion</title>
65 <p>Pour vous connecter à votre base de données, vous devez spécifier un
66 pilote et des paramètres de connexion qui diffèrent selon le moteur de base
67 de données. Par exemple, pour vous connecter à mysql, spécifiez ce qui suit
70 <highlight language="config">
72 DBDParams host=localhost,dbname=pony,user=shetland,pass=appaloosa
75 <p>Vous pourrez alors utiliser cette connexion dans de nombreux autres
76 modules comme <module>mod_rewrite</module>, <module>mod_authn_dbd</module>
77 et <module>mod_lua</module>. Vous trouverez des exemples d'utilisation dans
78 la documentation de ces modules.</p>
80 <p>Voir la syntaxe de la directive <directive>DBDParams</directive> pour les
81 informations à fournir dans la chaîne de connexion en fonction des
82 différents pilotes de base de données supportés.</p>
86 <section id="API"><title>API DBD d'Apache</title>
87 <p><module>mod_dbd</module> exporte cinq fonctions que d'autres
88 modules pourront utiliser. L'API se présente comme suit :</p>
90 <highlight language="c">
93 apr_dbd_driver_t *driver;
97 /* Fonctions exportées pour accéder à la base de données */
99 /* ouvre une connexion qui DEVRA être explicitement fermée.
100 * Renvoie NULL en cas d'erreur
102 AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
104 /* ferme une connexion ouverte avec ap_dbd_open */
105 AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
107 /* acquiert une connexion qui aura la durée de vie de la requête et qui
108 * NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
109 * d'erreur. C'est la fonction recommandée pour la plupart des
112 AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
114 /* acquiert une connexion qui aura la durée de vie d'une connexion et
115 * qui NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
118 AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
120 /* Prépare une requête qu'un module client pourra utiliser */
121 AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
123 /* Exporte aussi ces fonctions à titre optionnel mour les modules qui
124 * péfèreraient les utiliser */
125 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
126 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
127 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
128 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
129 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
133 <section id="prepared"><title>Requêtes SQL préparées</title>
134 <p><module>mod_dbd</module> supporte les requêtes SQL préparées pour
135 le compte des modules qui pourraient les utiliser. Chaque requête
136 préparée doit posséder un nom (étiquette), et est stockée dans un
137 condensé (hash) : les condensés sont du type
138 <code>apr_dbd_prepared_t</code> et s'utilisent dans toute requête
139 SQL ou commande select préparée par apr_dbd.</p>
141 <p>Il est du ressort des modules utilisateurs de dbd d'utiliser les
142 requêtes préparées et de préciser quelles requêtes doivent être
143 spécifiées dans httpd.conf, ou de fournir leurs propres directives
144 et d'utiliser <code>ap_dbd_prepare</code>.</p>
146 <note type="warning"><title>Avertissement</title>
147 Lorsqu'on utilise des requêtes préparées avec des bases de
148 données MySQL, il est préférable de définir
149 <code>reconnect</code> à 0 dans la chaîne de connexion, afin
150 d'éviter des erreurs provoquées par un client MySQL qui se
151 reconnecterait sans réinitialiser correctement les requêtes
152 préparées. Si <code>reconnect</code> est défini à 1, toute
153 connexion défectueuse sera sensée être réparée, mais comme
154 mod_dbd n'en est pas informé, les requêtes préparées seront
159 <section id="security">
160 <title>AVERTISSEMENT DE SECURITE</title>
161 <p>Toute application web impliquant une base de données doit se
162 protéger elle-même contre les attaques de type injection SQL. Dans
163 la plupart des cas Apache DBD est sûr, car les applications
164 utilisent des requêtes préparées, et les entrées non sûres ne seront
165 utilisées qu'à titre de données. Bien entendu, si vous l'utilisez
166 via un module tiers, vous devez être au fait des précautions à
168 <p>Cependant, le pilote <var>FreeTDS</var> est <strong>non
169 sûr</strong> de par sa nature même. Comme la bibliothèque
170 sous-jacente ne supporte pas les requêtes préparées, le pilote en
171 effectue une émulation, et les entrées non sûres sont fusionnées
172 avec la requête SQL.</p>
173 <p>Il peut être sécurisé en <em>décontaminant</em> toutes les
174 entrées : un processus inspiré de la recherche de contaminations de
175 Perl (NdT : <code>taint checking</code>). Chaque entrée est comparée
176 à une expression rationnelle, et
177 seules les entrées qui correspondent sont utilisées, en accord avec
178 le raccourci Perl :</p>
180 <pre><code> $untrusted =~ /([a-z]+)/;
181 $trusted = $1;</code></pre>
183 <p>Pour utiliser ceci, les expressions rationnelles de
184 décontamination doivent être incluses dans les requêtes préparées.
185 L'expression rationnelle doit se situer immédiatement après le
186 caractère % dans la requête préparée, et doit être entourée
187 d'accolades {}. Par exemple, si votre application attend une entrée
188 alphanumérique, vous pouvez utiliser :</p>
190 <code>"SELECT foo FROM bar WHERE input = %s"</code>
192 <p>avec d'autres pilotes, et ne risquer au pire qu'une requête
193 en échec. Mais avec FreeTDS, vous devez utiliser :</p>
195 <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
197 <p>tout ce qui ne correspond pas à l'expression rationnelle est
198 alors rejeté, et la requête est ainsi désormais sûre.</p>
199 <p>Alternativement, vous pouvez utiliser le pilote ODBC tiers, qui
200 offre la sécurité des requêtes préparées authentiques.</p>
203 <name>DBDriver</name>
204 <description>Spécifie un pilote SQL</description>
205 <syntax>DBDriver <var>nom</var></syntax>
206 <contextlist><context>server config</context><context>virtual host</context>
210 <p>Cette directive spécifie un pilote apr_dbd par son
211 nom. Le pilote doit être installé sur votre système (sur la plupart
212 des systèmes, il s'agit d'un objet partagé ou d'une dll). Par
213 exemple, <code>DBDriver mysql</code> va sélectionner le pilote MySQL
214 dans la bibliothèque apr_dbd_mysql.so.</p>
219 <name>DBDParams</name>
220 <description>Paramètres de la connexion à la base de
221 données</description>
223 <var>param1</var>=<var>valeur1</var>[,<var>param2</var>=<var>valeur2</var>]</syntax>
224 <contextlist><context>server config</context><context>virtual host</context>
228 <p>Cette directive spécifie des paramètres selon les
229 besoins du pilote concerné. En général, les paramètres à passer
230 concernent tout ce qui n'a pas de valeur par défaut comme le nom
231 d'utilisateur, le mot de passe, le nom de la base de données, le nom
232 d'hôte et le numéro de port de la connexion.</p>
233 <p>Les paramètres de la chaîne de connexion en fonction des
234 différents pilotes comprennent :</p>
236 <dt>FreeTDS (pour MSSQL et SyBase)</dt>
237 <dd>username, password, appname, dbname, host, charset, lang, server</dd>
239 <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
241 <dd>user, pass, dbname, server</dd>
243 <dd>La chaîne de connexion est passée directement à <code>PQconnectdb</code></dd>
245 <dd>La chaîne de connexion est scindée avec comme séparateur le
246 caractère ':', et <code>partie1:partie2</code> est utilisé dans
247 <code>sqlite_open(partie1, atoi(partie2), NULL)</code></dd>
249 <dd>La chaîne de connexion est passée directement à <code>sqlite3_open</code></dd>
251 <dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
257 <name>DBDPersist</name>
258 <description>Utiliser ou non des connexions persistentes</description>
259 <syntax>DBDPersist On|Off</syntax>
260 <contextlist><context>server config</context><context>virtual host</context>
264 <p>Si cette directive est définie à Off, les connexions persistentes
265 et les connexions groupées sont désactivées. À la demande d'un
266 client, une nouvelle connexion à la base de données est ouverte, et
267 fermée immédiatement à l'issue du traitement. Cette configuration ne
268 doit être utilisée qu'à des fins de débogage, ou sur des serveurs à
271 <p>Par défaut, les groupes de connexions persistentes sont activés
272 (ou une seule connexion persistente du style LAMP pour les serveurs
273 non threadés), et c'est la configuration qui devrait être utilisée
274 dans la plupart des cas sur un serveur en production.</p>
276 <p>Avant la version 2.2.2, cette directive n'acceptait que les
277 valeurs <code>0</code> et <code>1</code> au lieu de <code>Off</code>
278 et <code>On</code>, respectivement.</p>
283 <name>DBDPrepareSQL</name>
284 <description>Définit une requête SQL préparée</description>
285 <syntax>DBDPrepareSQL <var>"requête SQL"</var> <var>étiquette</var></syntax>
286 <contextlist><context>server config</context><context>virtual host</context>
290 <p>Pour les modules tels que les modules d'authentification, qui
291 utilisent de manière répétée la même requête SQL, on peut optimiser
292 les performances en préparant la requête une fois pour toutes au
293 démarrage, plutôt qu'à chaque utilisation. Cette directive permet de
294 préparer une requête SQL et de lui assigner une étiquette.</p>
300 <description>Nombre minimum de connexions</description>
301 <syntax>DBDMin <var>nombre</var></syntax>
302 <default>DBDMin 1</default>
303 <contextlist><context>server config</context><context>virtual host</context>
307 <p>Cette directive définit le nombre minimum de connexions
308 par processus (plates-formes threadées seulement).</p>
314 <description>Nombre maximum de connexions maintenues</description>
315 <syntax>DBDKeep <var>nombre</var></syntax>
316 <default>DBDKeep 2</default>
317 <contextlist><context>server config</context><context>virtual host</context>
321 <p>Cette directive définit le nombre maximum de connexions
322 à maintenir par processus, en dehors de celles servant à gérer les
323 pics de demandes (plates-formes threadées seulement).</p>
329 <description>Nombre maximum de connexions</description>
330 <syntax>DBDMax <var>nombre</var></syntax>
331 <default>DBDMax 10</default>
332 <contextlist><context>server config</context><context>virtual host</context>
336 <p>Cette directive définit le nombre maximum effectif de
337 connexions par processus (plates-formes threadées seulement).</p>
342 <name>DBDExptime</name>
343 <description>Durée de vie des connexions inactives</description>
344 <syntax>DBDExptime <var>durée en secondes</var></syntax>
345 <default>DBDExptime 300</default>
346 <contextlist><context>server config</context><context>virtual host</context>
350 <p>Cette directive définit la durée de vie des connexions
351 inactives lorsque le nombre de connexions spécifié par la directive
352 DBDKeep a été dépassé (plates-formes threadées seulement).</p>
357 <name>DBDInitSQL</name>
358 <description>Exécute une instruction SQL après connexion à une base de
359 données</description>
360 <syntax>DBDInitSQL <var>"instruction SQL"</var></syntax>
361 <contextlist><context>server config</context><context>virtual host</context>
365 <p>Les modules qui le souhaitent peuvent exécuter une ou plusieurs
366 instructions SQL après connexion à une base de données. Par exemple
367 initialiser certaines valeurs, ou ajouter une entrée dans le journal
368 lors d'une nouvelle connexion à la base de données.</p>