mod_dbd.html.en revision 9fbe25993a834701e7304ef46d72e28e10e720ff
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_dbd - Apache HTTP Server</title>
<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<body>
<div id="page-header">
<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>
<p class="apache">Apache HTTP Server Version 2.3</p>
<div id="path">
<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.3</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_dbd</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="/en/mod/mod_dbd.html" title="English"> en </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Manages SQL database connections</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>dbd_module</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.1 and later</td></tr></table>
<h3>Summary</h3>
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> manages SQL database connections using
<a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a>. It provides database connections on request
to modules requiring SQL database functions, and takes care of
managing databases with optimal efficiency and scalability
for both threaded and non-threaded MPMs. For details, see the
by its original developer.
</p>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
</ul>
<h3>Topics</h3>
<ul id="topics">
</ul><h3>See also</h3>
<ul class="seealso">
</ul></div>
<div class="section">
<h2><a name="pooling" id="pooling">Connection Pooling</a></h2>
<p>This module manages database connections, in a manner
optimised for the platform. On non-threaded platforms,
it provides a persistent connection in the manner of
On threaded platform, it provides an altogether more
scalable and efficient <em>connection pool</em>, as
described in <a href="http://www.apachetutor.org/dev/reslist">this
article at ApacheTutor</a>. Note that <code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code>
supersedes the modules presented in that article.</p>
<div class="section">
<h2><a name="API" id="API">Apache DBD API</a></h2>
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules
to use. The API is as follows:</p>
<div class="example"><pre><code>typedef struct {
apr_dbd_t *handle;
apr_dbd_driver_t *driver;
apr_hash_t *prepared;
} ap_dbd_t;
/* Export functions to access the database */
/* acquire a connection that MUST be explicitly closed.
* Returns NULL on error
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
/* release a connection acquired with ap_dbd_open */
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
/* acquire a connection that will have the lifetime of a request
* and MUST NOT be explicitly closed. Return NULL on error.
* This is the preferred function for most applications.
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
/* acquire a connection that will have the lifetime of a connection
* and MUST NOT be explicitly closed. Return NULL on error.
*/
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(request_rec*);
/* Prepare a statement for use by a client module */
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
/* Also export them as optional functions for modules that prefer it */
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*));
</code></pre></div>
<div class="section">
<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2>
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> supports SQL prepared statements on behalf
of modules that may wish to use them. Each prepared statement
must be assigned a name (label), and they are stored in a hash:
the <code>prepared</code> field of an <code>ap_dbd_t</code>.
Hash entries are of type <code>apr_dbd_prepared_t</code>
and can be used in any of the apr_dbd prepared statement
SQL query or select commands.</p>
<p>It is up to dbd user modules to use the prepared statements
and document what statements can be specified in httpd.conf,
or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
<div class="section">
<h2><a name="security" id="security">SECURITY WARNING</a></h2>
injection attacks. In most cases, Apache DBD is safe, because
applications use prepared statements, and untrusted inputs are
only ever used as data. Of course, if you use it via third-party
modules, you should ascertain what precautions they may require.</p>
<p>However, the <var>FreeTDS</var> driver is inherently
<strong>unsafe</strong>. The underlying library doesn't support
prepared statements, so the driver emulates them, and the
untrusted input is merged into the SQL statement.</p>
<p>It can be made safe by <em>untainting</em> all inputs:
a process inspired by Perl's taint checking. Each input
is matched against a regexp, and only the match is used,
according to the Perl idiom:</p>
<div class="example"><pre><code> $untrusted =~ /([a-z]+)/;
$trusted = $1;</code></pre></div>
<p>To use this, the untainting regexps must be included in the
prepared statements configured. The regexp follows immediately
after the % in the prepared statement, and is enclosed in
curly brackets {}. For example, if your application expects
alphanumeric input, you can use:</p>
<div class="example"><p><code>
<code>"SELECT foo FROM bar WHERE input = %s"</code>
</code></p></div>
<p>with other drivers, and suffer nothing worse than a failed query.
But with FreeTDS you'd need:</p>
<div class="example"><p><code>
<code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
</code></p></div>
<p>Now anything that doesn't match the regexp's $1 match is
discarded, so the statement is safe.</p>
<p>An alternative to this may be the third-party ODBC driver,
which offers the security of genuine prepared statements.</p>
</div>
<div class="directive-section"><h2><a name="DBDExptime" id="DBDExptime">DBDExptime</a> <a name="dbdexptime" id="dbdexptime">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keepalive time for idle connections</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDExptime <var>time-in-seconds</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>DBDExptime 300</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>Set the time to keep idle connections alive where the number
of connections specified in DBDKeep has been exceeded (threaded
platforms only).</p>
</div>
<div class="directive-section"><h2><a name="DBDKeep" id="DBDKeep">DBDKeep</a> <a name="dbdkeep" id="dbdkeep">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum sustained number of connections</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDKeep <var>number</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>Set the maximum number of connections per process to be
sustained, other than for handling peak demand (threaded
platforms only).</p>
</div>
<div class="directive-section"><h2><a name="DBDMax" id="DBDMax">DBDMax</a> <a name="dbdmax" id="dbdmax">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of connections</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMax <var>number</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>Set the hard maximum number of connections per process
(threaded platforms only).</p>
</div>
<div class="directive-section"><h2><a name="DBDMin" id="DBDMin">DBDMin</a> <a name="dbdmin" id="dbdmin">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimum number of connections</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMin <var>number</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>Set the minimum number of connections per process (threaded
platforms only).</p>
</div>
<div class="directive-section"><h2><a name="DBDParams" id="DBDParams">DBDParams</a> <a name="dbdparams" id="dbdparams">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parameters for database connection</td></tr>
<var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>As required by the underlying driver. Typically this will be
used to pass whatever cannot be defaulted amongst username,
password, database name, hostname and port number for connection.</p>
<p>Connection string parameters for current drivers include:</p>
<dl>
<dt>FreeTDS (for MSSQL and SyBase)</dt>
<dd>username, password, appname, dbname, host, charset, lang, server</dd>
<dt>MySQL</dt>
<dd>host, port, user, pass, dbname, sock</dd>
<dt>Oracle</dt>
<dd>user, pass, dbname, server</dd>
<dt>PostgreSQL</dt>
<dd>The connection string is passed straight through to <code>PQconnectdb</code></dd>
<dt>SQLite2</dt>
<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>
<dt>SQLite3</dt>
<dd>The connection string is passed straight through to <code>sqlite3_open</code></dd>
<dt>ODBC</dt>
author's project pages</a> for this third-party driver.</dd>
</dl>
</div>
<div class="directive-section"><h2><a name="DBDPersist" id="DBDPersist">DBDPersist</a> <a name="dbdpersist" id="dbdpersist">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to use persistent connections</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPersist On|Off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>If set to Off, persistent and pooled connections are disabled.
A new database connection is opened when requested by a client,
and closed immediately on release. This option is for debugging
and low-usage servers.</p>
<p>The default is to enable a pool of persistent connections
(or a single LAMP-style persistent connection in the case of a
non-threaded server), and should almost always be used in operation.</p>
<p>Prior to version 2.2.2, this directive accepted only the values
<code>0</code> and <code>1</code> instead of <code>Off</code> and
<code>On</code>, respectively.</p>
</div>
<div class="directive-section"><h2><a name="DBDPrepareSQL" id="DBDPrepareSQL">DBDPrepareSQL</a> <a name="dbdpreparesql" id="dbdpreparesql">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an SQL prepared statement</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>For modules such as authentication that use repeatedly use a
single SQL statement, optimum performance is achieved by preparing
the statement at startup rather than every time it is used.
This directive prepares an SQL statement and assigns it a label.</p>
</div>
<div class="directive-section"><h2><a name="DBDriver" id="DBDriver">DBDriver</a> <a name="dbdriver" id="dbdriver">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify an SQL driver</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDriver <var>name</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
</table>
<p>Selects an apr_dbd driver by name. The driver must be installed
on your system (on most systems, it will be a shared object or dll).
For example, <code>DBDriver mysql</code> will select the MySQL
driver in apr_dbd_mysql.so.</p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/mod/mod_dbd.html" title="English"> en </a></p>
</div><div id="footer">
<p class="apache">Copyright 2008 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>
<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>
</body></html>