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