mod_dbd.xml.fr revision 19f840f39b0ac97f90f41a38d10af53ccae17f1e
<?xml version="1.0"?>
<!-- English Revision : 1421821 -->
<!-- French translation : Lucien GENTIS -->
<!-- Reviewed by : Vincent Deffontaines -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<modulesynopsis metafile="mod_dbd.xml.meta">
<name>mod_dbd</name>
<description>Gestion des connexions à une base de données SQL</description>
<status>Extension</status>
<identifier>dbd_module</identifier>
<summary>
<p>Le module <module>mod_dbd</module> gère les connexions
à une base de données SQL via <glossary>APR</glossary>. Il permet
aux modules qui requièrent des fonctions liées aux bases de données
SQL de se connecter à une base de données à la demande, et s'efforce
de conférer aux bases de données une efficacité et une
évolutivité optimales pour les MPMs threadés ou non threadés. Pour
plus de détails, voir le site web <a
href="http://apr.apache.org/">APR</a>,
ainsi que cette vue d'ensemble de l'<a
href="http://people.apache.org/~niq/dbd.html">environnement de
développement d'Apache DBD</a> par son développeur initial.
</p>
</summary>
passe</a></seealso>
<section id="pooling"><title>Regroupement des connexions</title>
<p>Ce module gère de manière optimisée en fonction de la plate-forme
les connexions aux bases de données. Sur les plates-formes non
threadées, il maintient une connexion persistente à la manière d'un
plates-formes threadées, il maintient un <em>groupe de
connexions</em> à la fois plus évolutif et plus efficace, comme
décrit dans <a href="http://www.apachetutor.org/dev/reslist">cet
article d'ApacheTutor</a>. Notez que <module>mod_dbd</module>
remplace les modules présentés dans cet article.</p>
</section>
<section id="API"><title>API DBD d'Apache</title>
<p><module>mod_dbd</module> exporte cinq fonctions que d'autres
modules pourront utiliser. L'API se présente comme suit :</p>
<highlight language="c">
typedef struct {
apr_dbd_t *handle;
apr_dbd_driver_t *driver;
apr_hash_t *prepared;
} ap_dbd_t;
/* Fonctions exportées pour accéder à la base de données */
/* ouvre une connexion qui DEVRA être explicitement fermée.
* Renvoie NULL en cas d'erreur
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
/* ferme une connexion ouverte avec ap_dbd_open */
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
/* acquiert une connexion qui aura la durée de vie de la requête et qui
* NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
* d'erreur. C'est la fonction recommandée pour la plupart des
* applications.
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
/* acquiert une connexion qui aura la durée de vie d'une connexion et
* qui NE DEVRA PAS être explicitement fermée. Renvoie NULL en cas
* d'erreur.
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
/* Prépare une requête qu'un module client pourra utiliser */
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
/* Exporte aussi ces fonctions à titre optionnel mour les modules qui
* péfèreraient les utiliser */
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
</highlight>
</section>
<section id="prepared"><title>Requêtes SQL préparées</title>
<p><module>mod_dbd</module> supporte les requêtes SQL préparées pour
le compte des modules qui pourraient les utiliser. Chaque requête
préparée doit posséder un nom (étiquette), et est stockée dans un
condensé (hash) : les condensés sont du type
<code>apr_dbd_prepared_t</code> et s'utilisent dans toute requête
SQL ou commande select préparée par apr_dbd.</p>
<p>Il est du ressort des modules utilisateurs de dbd d'utiliser les
requêtes préparées et de préciser quelles requêtes doivent être
spécifiées dans httpd.conf, ou de fournir leurs propres directives
et d'utiliser <code>ap_dbd_prepare</code>.</p>
<note type="warning"><title>Avertissement</title>
Lorsqu'on utilise des requêtes préparées avec des bases de
données MySQL, il est préférable de définir
<code>reconnect</code> à 0 dans la chaîne de connexion, afin
d'éviter des erreurs provoquées par un client MySQL qui se
reconnecterait sans réinitialiser correctement les requêtes
préparées. Si <code>reconnect</code> est défini à 1, toute
connexion défectueuse sera sensée être réparée, mais comme
mod_dbd n'en est pas informé, les requêtes préparées seront
invalidées.
</note>
</section>
<section id="security">
<title>AVERTISSEMENT DE SECURITE</title>
<p>Toute application web impliquant une base de données doit se
protéger elle-même contre les attaques de type injection SQL. Dans
la plupart des cas Apache DBD est sûr, car les applications
utilisent des requêtes préparées, et les entrées non sûres ne seront
utilisées qu'à titre de données. Bien entendu, si vous l'utilisez
via un module tiers, vous devez être au fait des précautions à
prendre.</p>
<p>Cependant, le pilote <var>FreeTDS</var> est <strong>non
sûr</strong> de par sa nature même. Comme la bibliothèque
sous-jacente ne supporte pas les requêtes préparées, le pilote en
effectue une émulation, et les entrées non sûres sont fusionnées
avec la requête SQL.</p>
<p>Il peut être sécurisé en <em>décontaminant</em> toutes les
entrées : un processus inspiré de la recherche de contaminations de
Perl (NdT : <code>taint checking</code>). Chaque entrée est comparée
à une expression rationnelle, et
seules les entrées qui correspondent sont utilisées, en accord avec
le raccourci Perl :</p>
<example>
<pre><code> $untrusted =~ /([a-z]+)/;
$trusted = $1;</code></pre>
</example>
<p>Pour utiliser ceci, les expressions rationnelles de
décontamination doivent être incluses dans les requêtes préparées.
L'expression rationnelle doit se situer immédiatement après le
caractère % dans la requête préparée, et doit être entourée
d'accolades {}. Par exemple, si votre application attend une entrée
alphanumérique, vous pouvez utiliser :</p>
<example>
<code>"SELECT foo FROM bar WHERE input = %s"</code>
</example>
<p>avec d'autres pilotes, et ne risquer au pire qu'une requête
en échec. Mais avec FreeTDS, vous devez utiliser :</p>
<example>
<code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
</example>
<p>tout ce qui ne correspond pas à l'expression rationnelle est
alors rejeté, et la requête est ainsi désormais sûre.</p>
<p>Alternativement, vous pouvez utiliser le pilote ODBC tiers, qui
offre la sécurité des requêtes préparées authentiques.</p>
</section>
<directivesynopsis>
<name>DBDriver</name>
<description>Spécifie un pilote SQL</description>
<syntax>DBDriver <var>nom</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive spécifie un pilote apr_dbd par son
nom. Le pilote doit être installé sur votre système (sur la plupart
des systèmes, il s'agit d'un objet partagé ou d'une dll). Par
exemple, <code>DBDriver mysql</code> va sélectionner le pilote MySQL
dans la bibliothèque apr_dbd_mysql.so.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDParams</name>
<description>Paramètres de la connexion à la base de
données</description>
<syntax>DBDParams
<var>param1</var>=<var>valeur1</var>[,<var>param2</var>=<var>valeur2</var>]</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive spécifie des paramètres selon les
besoins du pilote concerné. En général, les paramètres à passer
concernent tout ce qui n'a pas de valeur par défaut comme le nom
d'utilisateur, le mot de passe, le nom de la base de données, le nom
d'hôte et le numéro de port de la connexion.</p>
<p>Les paramètres de la chaîne de connexion en fonction des
différents pilotes comprennent :</p>
<dl>
<dt>FreeTDS (pour MSSQL et SyBase)</dt>
<dd>username, password, appname, dbname, host, charset, lang, server</dd>
<dt>MySQL</dt>
<dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
<dt>Oracle</dt>
<dd>user, pass, dbname, server</dd>
<dt>PostgreSQL</dt>
<dd>La chaîne de connexion est passée directement à <code>PQconnectdb</code></dd>
<dt>SQLite2</dt>
<dd>La chaîne de connexion est scindée avec comme séparateur le
caractère ':', et <code>partie1:partie2</code> est utilisé dans
<code>sqlite_open(partie1, atoi(partie2), NULL)</code></dd>
<dt>SQLite3</dt>
<dd>La chaîne de connexion est passée directement à <code>sqlite3_open</code></dd>
<dt>ODBC</dt>
<dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
</dl>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDPersist</name>
<description>Utiliser ou non des connexions persistentes</description>
<syntax>DBDPersist On|Off</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Si cette directive est définie à Off, les connexions persistentes
et les connexions groupées sont désactivées. À la demande d'un
client, une nouvelle connexion à la base de données est ouverte, et
fermée immédiatement à l'issue du traitement. Cette configuration ne
doit être utilisée qu'à des fins de débogage, ou sur des serveurs à
charge faible.</p>
<p>Par défaut, les groupes de connexions persistentes sont activés
(ou une seule connexion persistente du style LAMP pour les serveurs
non threadés), et c'est la configuration qui devrait être utilisée
dans la plupart des cas sur un serveur en production.</p>
<p>Avant la version 2.2.2, cette directive n'acceptait que les
valeurs <code>0</code> et <code>1</code> au lieu de <code>Off</code>
et <code>On</code>, respectivement.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDPrepareSQL</name>
<description>Définit une requête SQL préparée</description>
<syntax>DBDPrepareSQL <var>"requête SQL"</var> <var>étiquette</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Pour les modules tels que les modules d'authentification, qui
utilisent de manière répétée la même requête SQL, on peut optimiser
les performances en préparant la requête une fois pour toutes au
démarrage, plutôt qu'à chaque utilisation. Cette directive permet de
préparer une requête SQL et de lui assigner une étiquette.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDMin</name>
<description>Nombre minimum de connexions</description>
<syntax>DBDMin <var>nombre</var></syntax>
<default>DBDMin 1</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive définit le nombre minimum de connexions
par processus (plates-formes threadées seulement).</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDKeep</name>
<description>Nombre maximum de connexions maintenues</description>
<syntax>DBDKeep <var>nombre</var></syntax>
<default>DBDKeep 2</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive définit le nombre maximum de connexions
à maintenir par processus, en dehors de celles servant à gérer les
pics de demandes (plates-formes threadées seulement).</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDMax</name>
<description>Nombre maximum de connexions</description>
<syntax>DBDMax <var>nombre</var></syntax>
<default>DBDMax 10</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive définit le nombre maximum effectif de
connexions par processus (plates-formes threadées seulement).</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDExptime</name>
<description>Durée de vie des connexions inactives</description>
<syntax>DBDExptime <var>durée en secondes</var></syntax>
<default>DBDExptime 300</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Cette directive définit la durée de vie des connexions
inactives lorsque le nombre de connexions spécifié par la directive
DBDKeep a été dépassé (plates-formes threadées seulement).</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>DBDInitSQL</name>
<description>Exécute une instruction SQL après connexion à une base de
données</description>
<syntax>DBDInitSQL <var>"instruction SQL"</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
<usage>
<p>Les modules qui le souhaitent peuvent exécuter une ou plusieurs
instructions SQL après connexion à une base de données. Par exemple
initialiser certaines valeurs, ou ajouter une entrée dans le journal
lors d'une nouvelle connexion à la base de données.</p>
</usage>
</directivesynopsis>
</modulesynopsis>