apache/docs/manual/mod/mod_dbd.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_dbd - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_dbd</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Manages SQL database connections</td></tr>
  27 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  28 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>dbd_module</td></tr>
  29 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_dbd.c</td></tr>
  30 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.1 and later</td></tr></table>
  31 <h3>Summary</h3>
  32
  33     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> manages SQL database connections using
  34     <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a>.  It provides database connections on request
  35     to modules requiring SQL database functions, and takes care of
  36     managing databases with optimal efficiency and scalability
  37     for both threaded and non-threaded MPMs.  For details, see the
  38     <a href="http://apr.apache.org/">APR</a> website and this overview of the
  39     <a href="http://people.apache.org/~niq/dbd.html">Apache DBD Framework</a>
  40     by its original developer.
  41 </p>
  42 </div>
  43 <div id="quickview"><h3 class="directives">Directives</h3>
  44 <ul id="toc">
  45 <li><img alt="" src="../images/down.gif" /> <a href="#dbdexptime">DBDExptime</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#dbdkeep">DBDKeep</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#dbdmax">DBDMax</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#dbdmin">DBDMin</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#dbdparams">DBDParams</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#dbdpersist">DBDPersist</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#dbdpreparesql">DBDPrepareSQL</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#dbdriver">DBDriver</a></li>
  53 </ul>
  54 <h3>Topics</h3>
  55 <ul id="topics">
  56 <li><img alt="" src="../images/down.gif" /> <a href="#pooling">Connection Pooling</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#API">Apache DBD API</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#prepared">SQL Prepared Statements</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#security">SECURITY WARNING</a></li>
  60 </ul><h3>See also</h3>
  61 <ul class="seealso">
  62 <li><a href="../misc/password_encryptions.html">Password Formats</a></li>
  63 </ul></div>
  64 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  65 <div class="section">
  66 <h2><a name="pooling" id="pooling">Connection Pooling</a></h2>
  67     <p>This module manages database connections, in a manner
  68     optimised for the platform.  On non-threaded platforms,
  69     it provides a persistent connection in the manner of
  70     classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
  71     On threaded platform, it provides an altogether more
  72     scalable and efficient <em>connection pool</em>, as
  73     described in <a href="http://www.apachetutor.org/dev/reslist">this
  74     article at ApacheTutor</a>.  Note that <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>
  75     supersedes the modules presented in that article.</p>
  76 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  77 <div class="section">
  78 <h2><a name="API" id="API">Apache DBD API</a></h2>
  79     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules
  80     to use. The API is as follows:</p>
  81
  82     <div class="example"><pre><code>typedef struct {
  83     apr_dbd_t *handle;
  84     apr_dbd_driver_t *driver;
  85     apr_hash_t *prepared;
  86 } ap_dbd_t;
  87
  88 /* Export functions to access the database */
  89
  90 /* acquire a connection that MUST be explicitly closed.
  91  * Returns NULL on error
  92  */
  93 AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
  94
  95 /* release a connection acquired with ap_dbd_open */
  96 AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
  97
  98 /* acquire a connection that will have the lifetime of a request
  99  * and MUST NOT be explicitly closed.  Return NULL on error.
 100  * This is the preferred function for most applications.
 101  */
 102 AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
 103
 104 /* acquire a connection that will have the lifetime of a connection
 105  * and MUST NOT be explicitly closed.  Return NULL on error.
 106  */
 107 AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(request_rec*);
 108
 109 /* Prepare a statement for use by a client module */
 110 AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
 111
 112 /* Also export them as optional functions for modules that prefer it */
 113 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
 114 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
 115 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
 116 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
 117 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
 118 </code></pre></div>
 119 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 120 <div class="section">
 121 <h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2>
 122     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> supports SQL prepared statements on behalf
 123     of modules that may wish to use them.  Each prepared statement
 124     must be assigned a name (label), and they are stored in a hash:
 125     the <code>prepared</code> field of an <code>ap_dbd_t</code>.
 126     Hash entries are of type <code>apr_dbd_prepared_t</code>
 127     and can be used in any of the apr_dbd prepared statement
 128     SQL query or select commands.</p>
 129
 130     <p>It is up to dbd user modules to use the prepared statements
 131     and document what statements can be specified in httpd.conf,
 132     or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
 133 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 134 <div class="section">
 135 <h2><a name="security" id="security">SECURITY WARNING</a></h2>
 136
 137     <p>Any web/database application needs to secure itself against SQL
 138     injection attacks.  In most cases, Apache DBD is safe, because
 139     applications use prepared statements, and untrusted inputs are
 140     only ever used as data.  Of course, if you use it via third-party
 141     modules, you should ascertain what precautions they may require.</p>
 142     <p>However, the <var>FreeTDS</var> driver is inherently
 143     <strong>unsafe</strong>.  The underlying library doesn't support
 144     prepared statements, so the driver emulates them, and the
 145     untrusted input is merged into the SQL statement.</p>
 146     <p>It can be made safe by <em>untainting</em> all inputs:
 147     a process inspired by Perl's taint checking.  Each input
 148     is matched against a regexp, and only the match is used,
 149     according to the Perl idiom:</p>
 150     <div class="example"><pre><code>  $untrusted =~ /([a-z]+)/;
 151   $trusted = $1;</code></pre></div>
 152     <p>To use this, the untainting regexps must be included in the
 153     prepared statements configured.  The regexp follows immediately
 154     after the % in the prepared statement, and is enclosed in
 155     curly brackets {}.  For example, if your application expects
 156     alphanumeric input, you can use:</p>
 157     <div class="example"><p><code>
 158        <code>"SELECT foo FROM bar WHERE input = %s"</code>
 159     </code></p></div>
 160     <p>with other drivers, and suffer nothing worse than a failed query.
 161     But with FreeTDS you'd need:</p>
 162     <div class="example"><p><code>
 163        <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
 164     </code></p></div>
 165     <p>Now anything that doesn't match the regexp's $1 match is
 166     discarded, so the statement is safe.</p>
 167     <p>An alternative to this may be the third-party ODBC driver,
 168     which offers the security of genuine prepared statements.</p>
 169 </div>
 170 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 171 <div class="directive-section"><h2><a name="DBDExptime" id="DBDExptime">DBDExptime</a> <a name="dbdexptime" id="dbdexptime">Directive</a></h2>
 172 <table class="directive">
 173 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keepalive time for idle connections</td></tr>
 174 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDExptime <var>time-in-seconds</var></code></td></tr>
 175 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DBDExptime 300</code></td></tr>
 176 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 177 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 178 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 179 </table>
 180     <p>Set the time to keep idle connections alive when the number
 181     of connections specified in DBDKeep has been exceeded (threaded
 182     platforms only).</p>
 183
 184 </div>
 185 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 186 <div class="directive-section"><h2><a name="DBDKeep" id="DBDKeep">DBDKeep</a> <a name="dbdkeep" id="dbdkeep">Directive</a></h2>
 187 <table class="directive">
 188 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum sustained number of connections</td></tr>
 189 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDKeep <var>number</var></code></td></tr>
 190 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DBDKeep 2</code></td></tr>
 191 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 192 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 193 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 194 </table>
 195     <p>Set the maximum number of connections per process to be
 196     sustained, other than for handling peak demand (threaded
 197     platforms only).</p>
 198
 199 </div>
 200 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 201 <div class="directive-section"><h2><a name="DBDMax" id="DBDMax">DBDMax</a> <a name="dbdmax" id="dbdmax">Directive</a></h2>
 202 <table class="directive">
 203 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of connections</td></tr>
 204 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMax <var>number</var></code></td></tr>
 205 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DBDMax 10</code></td></tr>
 206 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 207 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 208 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 209 </table>
 210     <p>Set the hard maximum number of connections per process
 211     (threaded platforms only).</p>
 212
 213 </div>
 214 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 215 <div class="directive-section"><h2><a name="DBDMin" id="DBDMin">DBDMin</a> <a name="dbdmin" id="dbdmin">Directive</a></h2>
 216 <table class="directive">
 217 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimum number of connections</td></tr>
 218 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMin <var>number</var></code></td></tr>
 219 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DBDMin 1</code></td></tr>
 220 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 221 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 222 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 223 </table>
 224     <p>Set the minimum number of connections per process (threaded
 225     platforms only).</p>
 226
 227 </div>
 228 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 229 <div class="directive-section"><h2><a name="DBDParams" id="DBDParams">DBDParams</a> <a name="dbdparams" id="dbdparams">Directive</a></h2>
 230 <table class="directive">
 231 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parameters for database connection</td></tr>
 232 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDParams
 233 <var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</code></td></tr>
 234 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 235 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 236 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 237 </table>
 238     <p>As required by the underlying driver.  Typically this will be
 239     used to pass whatever cannot be defaulted amongst username,
 240     password, database name, hostname and port number for connection.</p>
 241     <p>Connection string parameters for current drivers include:</p>
 242     <dl>
 243     <dt>FreeTDS (for MSSQL and SyBase)</dt>
 244     <dd>username, password, appname, dbname, host, charset, lang, server</dd>
 245     <dt>MySQL</dt>
 246     <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
 247     <dt>Oracle</dt>
 248     <dd>user, pass, dbname, server</dd>
 249     <dt>PostgreSQL</dt>
 250     <dd>The connection string is passed straight through to <code>PQconnectdb</code></dd>
 251     <dt>SQLite2</dt>
 252     <dd>The connection string is split on a colon, and <code>part1:part2</code> is used as <code>sqlite_open(part1, atoi(part2), NULL)</code></dd>
 253     <dt>SQLite3</dt>
 254     <dd>The connection string is passed straight through to <code>sqlite3_open</code></dd>
 255     <dt>ODBC</dt>
 256     <dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
 257     </dl>
 258
 259 </div>
 260 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 261 <div class="directive-section"><h2><a name="DBDPersist" id="DBDPersist">DBDPersist</a> <a name="dbdpersist" id="dbdpersist">Directive</a></h2>
 262 <table class="directive">
 263 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to use persistent connections</td></tr>
 264 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPersist On|Off</code></td></tr>
 265 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 266 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 267 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 268 </table>
 269     <p>If set to Off, persistent and pooled connections are disabled.
 270     A new database connection is opened when requested by a client,
 271     and closed immediately on release.  This option is for debugging
 272     and low-usage servers.</p>
 273
 274     <p>The default is to enable a pool of persistent connections
 275     (or a single LAMP-style persistent connection in the case of a
 276     non-threaded server), and should almost always be used in operation.</p>
 277
 278     <p>Prior to version 2.2.2, this directive accepted only the values
 279     <code>0</code> and <code>1</code> instead of <code>Off</code> and
 280     <code>On</code>, respectively.</p>
 281
 282 </div>
 283 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 284 <div class="directive-section"><h2><a name="DBDPrepareSQL" id="DBDPrepareSQL">DBDPrepareSQL</a> <a name="dbdpreparesql" id="dbdpreparesql">Directive</a></h2>
 285 <table class="directive">
 286 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an SQL prepared statement</td></tr>
 287 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></code></td></tr>
 288 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 289 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 290 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 291 </table>
 292     <p>For modules such as authentication that repeatedly use a
 293     single SQL statement, optimum performance is achieved by preparing
 294     the statement at startup rather than every time it is used.
 295     This directive prepares an SQL statement and assigns it a label.</p>
 296
 297 </div>
 298 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 299 <div class="directive-section"><h2><a name="DBDriver" id="DBDriver">DBDriver</a> <a name="dbdriver" id="dbdriver">Directive</a></h2>
 300 <table class="directive">
 301 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify an SQL driver</td></tr>
 302 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDriver <var>name</var></code></td></tr>
 303 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 304 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 305 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
 306 </table>
 307     <p>Selects an apr_dbd driver by name.  The driver must be installed
 308     on your system (on most systems, it will be a shared object or dll).
 309     For example, <code>DBDriver mysql</code> will select the MySQL
 310     driver in apr_dbd_mysql.so.</p>
 311
 312 </div>
 313 </div>
 314 <div class="bottomlang">
 315 <p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
 316 </div><div id="footer">
 317 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 318 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 319 </body></html>