granicus.if.org Git - apache/blob - docs/manual/mod/mod_dbd.xml.fr

   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 -->
   7
   8 <!--
   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
  15
  16      http://www.apache.org/licenses/LICENSE-2.0
  17
  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.
  23 -->
  24
  25 <modulesynopsis metafile="mod_dbd.xml.meta">
  26
  27 <name>mod_dbd</name>
  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>
  32
  33 <summary>
  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.
  45 </p>
  46 </summary>
  47
  48 <seealso><a href="../misc/password_encryptions.html">Formats des mots de
  49 passe</a></seealso>
  50
  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>
  61 </section>
  62
  63 <section id="connecting"><title>Connexion</title>
  64
  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
  68     :</p>
  69
  70 <highlight language="config">
  71 DBDriver mysql
  72 DBDParams host=localhost,dbname=pony,user=shetland,pass=appaloosa
  73 </highlight>
  74
  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>
  79
  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>
  83
  84 </section>
  85
  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>
  89
  90     <highlight language="c">
  91 typedef struct {
  92     apr_dbd_t *handle;
  93     apr_dbd_driver_t *driver;
  94     apr_hash_t *prepared;
  95 } ap_dbd_t;
  96
  97 /* Fonctions exportées pour accéder à la base de données */
  98
  99 /* ouvre une connexion qui DEVRA être explicitement fermée.
 100  * Renvoie NULL en cas d'erreur
 101  */
 102 AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
 103
 104 /* ferme une connexion ouverte avec ap_dbd_open */
 105 AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
 106
 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
 110  * applications.
 111  */
 112 AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
 113
 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
 116  * d'erreur.
 117  */
 118 AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
 119
 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*);
 122
 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*));
 130 </highlight>
 131 </section>
 132
 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>
 140
 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>
 145
 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
 155         invalidées.
 156         </note>
 157 </section>
 158
 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 à
 167     prendre.</p>
 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>
 179     <example>
 180         <pre><code>  $untrusted =~ /([a-z]+)/;
 181   $trusted = $1;</code></pre>
 182     </example>
 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>
 189     <example>
 190        <code>"SELECT foo FROM bar WHERE input = %s"</code>
 191     </example>
 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>
 194     <example>
 195        <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
 196     </example>
 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>
 201 </section>
 202 <directivesynopsis>
 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>
 207 </contextlist>
 208
 209 <usage>
 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>
 215 </usage>
 216 </directivesynopsis>
 217
 218 <directivesynopsis>
 219 <name>DBDParams</name>
 220 <description>Paramètres de la connexion à la base de
 221 données</description>
 222 <syntax>DBDParams
 223 <var>param1</var>=<var>valeur1</var>[,<var>param2</var>=<var>valeur2</var>]</syntax>
 224 <contextlist><context>server config</context><context>virtual host</context>
 225 </contextlist>
 226
 227 <usage>
 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>
 235     <dl>
 236     <dt>FreeTDS (pour MSSQL et SyBase)</dt>
 237     <dd>username, password, appname, dbname, host, charset, lang, server</dd>
 238     <dt>MySQL</dt>
 239     <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
 240     <dt>Oracle</dt>
 241     <dd>user, pass, dbname, server</dd>
 242     <dt>PostgreSQL</dt>
 243     <dd>La chaîne de connexion est passée directement à <code>PQconnectdb</code></dd>
 244     <dt>SQLite2</dt>
 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>
 248     <dt>SQLite3</dt>
 249     <dd>La chaîne de connexion est passée directement à <code>sqlite3_open</code></dd>
 250     <dt>ODBC</dt>
 251     <dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
 252     </dl>
 253 </usage>
 254 </directivesynopsis>
 255
 256 <directivesynopsis>
 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>
 261 </contextlist>
 262
 263 <usage>
 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 à
 269     charge faible.</p>
 270
 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>
 275
 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>
 279 </usage>
 280 </directivesynopsis>
 281
 282 <directivesynopsis>
 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>
 287 </contextlist>
 288
 289 <usage>
 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>
 295 </usage>
 296 </directivesynopsis>
 297
 298 <directivesynopsis>
 299 <name>DBDMin</name>
 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>
 304 </contextlist>
 305
 306 <usage>
 307     <p>Cette directive définit le nombre minimum de connexions
 308     par processus (plates-formes threadées seulement).</p>
 309 </usage>
 310 </directivesynopsis>
 311
 312 <directivesynopsis>
 313 <name>DBDKeep</name>
 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>
 318 </contextlist>
 319
 320 <usage>
 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>
 324 </usage>
 325 </directivesynopsis>
 326
 327 <directivesynopsis>
 328 <name>DBDMax</name>
 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>
 333 </contextlist>
 334
 335 <usage>
 336     <p>Cette directive définit le nombre maximum effectif de
 337     connexions par processus (plates-formes threadées seulement).</p>
 338 </usage>
 339 </directivesynopsis>
 340
 341 <directivesynopsis>
 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>
 347 </contextlist>
 348
 349 <usage>
 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>
 353 </usage>
 354 </directivesynopsis>
 355
 356 <directivesynopsis>
 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>
 362 </contextlist>
 363
 364 <usage>
 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>
 369 </usage>
 370 </directivesynopsis>
 371
 372
 373 </modulesynopsis>