1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<?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">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
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" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<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>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<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#Status">Status:</a></th><td>Extension</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#SourceFile">Source File:</a></th><td>mod_dbd.c</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
<a href="http://apr.apache.org/">APR</a> website and this overview of the
<a href="http://people.apache.org/~niq/dbd.html">Apache DBD Framework</a>
by its original developer.
</p>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#dbdexptime">DBDExptime</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdkeep">DBDKeep</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdmax">DBDMax</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdmin">DBDMin</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdparams">DBDParams</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdpersist">DBDPersist</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdpreparesql">DBDPrepareSQL</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#dbdriver">DBDriver</a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#pooling">Connection Pooling</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#API">Apache DBD API</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#prepared">SQL Prepared Statements</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#security">SECURITY WARNING</a></li>
</ul><h3>See also</h3>
<ul class="seealso">
<li><a href="../misc/password_encryptions.html">Password Formats</a></li>
</ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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
classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="security" id="security">SECURITY WARNING</a></h2>
<p>Any web/database application needs to secure itself against SQL
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="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
</table>
<p>Set the time to keep idle connections alive when the number
of connections specified in DBDKeep has been exceeded (threaded
platforms only).</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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#Default">Default:</a></th><td><code>DBDKeep 2</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</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="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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#Default">Default:</a></th><td><code>DBDMax 10</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
</table>
<p>Set the hard maximum number of connections per process
(threaded platforms only).</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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#Default">Default:</a></th><td><code>DBDMin 1</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
</table>
<p>Set the minimum number of connections per process (threaded
platforms only).</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDParams
<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>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</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, flags, fldsz, group, reconnect</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>
<dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
</dl>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</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="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
</table>
<p>For modules such as authentication that 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="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</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 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>
<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>
|
