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
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>
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.2</p>
17
<img alt="" src="../images/feather.gif" /></div>
18
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20
<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>
21
<div id="page-content">
22
<div id="preamble"><h1>Apache Module mod_dbd</h1>
24
<p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English"> en </a></p>
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>
33
<p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> manages SQL database connections using
34
<a href="http://people.apache.org/~niq/dbd.html">apr_dbd</a>.
35
It provides database connections on request to modules
36
requiring SQL database functions, and takes care of
37
managing databases with optimal efficiency and scalability
38
for both threaded and non-threaded MPMs.</p>
40
<div id="quickview"><h3 class="directives">Directives</h3>
42
<li><img alt="" src="../images/down.gif" /> <a href="#dbdexptime">DBDExptime</a></li>
43
<li><img alt="" src="../images/down.gif" /> <a href="#dbdkeep">DBDKeep</a></li>
44
<li><img alt="" src="../images/down.gif" /> <a href="#dbdmax">DBDMax</a></li>
45
<li><img alt="" src="../images/down.gif" /> <a href="#dbdmin">DBDMin</a></li>
46
<li><img alt="" src="../images/down.gif" /> <a href="#dbdparams">DBDParams</a></li>
47
<li><img alt="" src="../images/down.gif" /> <a href="#dbdpersist">DBDPersist</a></li>
48
<li><img alt="" src="../images/down.gif" /> <a href="#dbdpreparesql">DBDPrepareSQL</a></li>
49
<li><img alt="" src="../images/down.gif" /> <a href="#dbdriver">DBDriver</a></li>
53
<li><img alt="" src="../images/down.gif" /> <a href="#pooling">Connection Pooling</a></li>
54
<li><img alt="" src="../images/down.gif" /> <a href="#API">Apache DBD API</a></li>
55
<li><img alt="" src="../images/down.gif" /> <a href="#prepared">SQL Prepared Statements</a></li>
57
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
59
<h2><a name="pooling" id="pooling">Connection Pooling</a></h2>
60
<p>This module manages database connections, in a manner
61
optimised for the platform. On non-threaded platforms,
62
it provides a persistent connection in the manner of
63
classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
64
On threaded platform, it provides an altogether more
65
scalable and efficient <em>connection pool</em>, as
66
described in <a href="http://www.apachetutor.org/dev/reslist">this article at ApacheTutor</a>. <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> supersedes
67
the modules presented in that article.</p>
68
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
70
<h2><a name="API" id="API">Apache DBD API</a></h2>
71
<p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> exports five functions for other modules
72
to use. The API is as follows:</p>
74
<div class="example"><pre><code>typedef struct {
76
apr_dbd_driver_t *driver;
80
/* Export functions to access the database */
82
/* acquire a connection that MUST be explicitly closed.
83
* Returns NULL on error
85
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
87
/* release a connection acquired with ap_dbd_open */
88
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
90
/* acquire a connection that will have the lifetime of a request
91
* and MUST NOT be explicitly closed. Return NULL on error.
92
* This is the preferred function for most applications.
94
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
96
/* acquire a connection that will have the lifetime of a connection
97
* and MUST NOT be explicitly closed. Return NULL on error.
99
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(request_rec*);
101
/* Prepare a statement for use by a client module */
102
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
104
/* Also export them as optional functions for modules that prefer it */
105
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
106
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
107
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
108
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
109
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
111
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
112
<div class="section">
113
<h2><a name="prepared" id="prepared">SQL Prepared Statements</a></h2>
114
<p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> supports SQL prepared statements on behalf
115
of modules that may wish to use them. Each prepared statement
116
must be assigned a name (label), and they are stored in a hash:
117
the <code>prepared</code> field of an <code>ap_dbd_t</code>.
118
Hash entries are of type <code>apr_dbd_prepared_t</code>
119
and can be used in any of the apr_dbd prepared statement
120
SQL query or select commands.</p>
122
<p>It is up to dbd user modules to use the prepared statements
123
and document what statements can be specified in httpd.conf,
124
or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
126
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
127
<div class="directive-section"><h2><a name="DBDExptime" id="DBDExptime">DBDExptime</a> <a name="dbdexptime" id="dbdexptime">Directive</a></h2>
128
<table class="directive">
129
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Keepalive time for idle connections</td></tr>
130
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDExptime <var>time-in-seconds</var></code></td></tr>
131
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
132
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
133
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
135
<p>Set the time to keep idle connections alive where the number
136
of connections specified in DBDKeep has been exceeded (threaded
140
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
141
<div class="directive-section"><h2><a name="DBDKeep" id="DBDKeep">DBDKeep</a> <a name="dbdkeep" id="dbdkeep">Directive</a></h2>
142
<table class="directive">
143
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum sustained number of connections</td></tr>
144
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDKeep <var>number</var></code></td></tr>
145
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
146
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
147
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
149
<p>Set the maximum number of connections per process to be
150
sustained, other than for handling peak demand (threaded
154
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
155
<div class="directive-section"><h2><a name="DBDMax" id="DBDMax">DBDMax</a> <a name="dbdmax" id="dbdmax">Directive</a></h2>
156
<table class="directive">
157
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of connections</td></tr>
158
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMax <var>number</var></code></td></tr>
159
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
160
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
161
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
163
<p>Set the hard maximum number of connections per process
164
(threaded platforms only).</p>
167
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
168
<div class="directive-section"><h2><a name="DBDMin" id="DBDMin">DBDMin</a> <a name="dbdmin" id="dbdmin">Directive</a></h2>
169
<table class="directive">
170
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Minimum number of connections</td></tr>
171
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDMin <var>number</var></code></td></tr>
172
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
173
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
174
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
176
<p>Set the minimum number of connections per process (threaded
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="DBDParams" id="DBDParams">DBDParams</a> <a name="dbdparams" id="dbdparams">Directive</a></h2>
182
<table class="directive">
183
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parameters for database connection</td></tr>
184
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDParams
185
<var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</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>
190
<p>As required by the underlying driver. Typically this will be
191
used to pass whatever cannot be defaulted amongst username,
192
password, database name, hostname and port number for connection.</p>
193
<p>Connection string parameters for current drivers include:</p>
196
<dd>host, port, user, pass, dbname, sock</dd>
198
<dd>user, pass, dbname, server</dd>
200
<dd>The connection string is passed straight through to <code>PQconnectdb</code></dd>
202
<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>
204
<dd>The connection string is passed straight through to <code>sqlite3_open</code></dd>
208
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
209
<div class="directive-section"><h2><a name="DBDPersist" id="DBDPersist">DBDPersist</a> <a name="dbdpersist" id="dbdpersist">Directive</a></h2>
210
<table class="directive">
211
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to use persistent connections</td></tr>
212
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPersist 0|1</code></td></tr>
213
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
214
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
215
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
217
<p>If set to 0, persistent and pooled connections are disabled.
218
A new database connection is opened when requested by a client,
219
and closed immediately on release. This option is for debugging
220
and low-usage servers.</p>
222
<p>The default is to enable a pool of persistent connections
223
(or a single LAMP-style persistent connection in the case of a
224
non-threaded server), and should almost always be used in operation.</p>
227
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
228
<div class="directive-section"><h2><a name="DBDPrepareSQL" id="DBDPrepareSQL">DBDPrepareSQL</a> <a name="dbdpreparesql" id="dbdpreparesql">Directive</a></h2>
229
<table class="directive">
230
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an SQL prepared statement</td></tr>
231
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></code></td></tr>
232
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
233
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
234
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
236
<p>For modules such as authentication that use repeatedly use a
237
single SQL statement, optimum performance is achieved by preparing
238
the statement at startup rather than every time it is used.
239
This directive prepares an SQL statement and assigns it a label.</p>
242
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
243
<div class="directive-section"><h2><a name="DBDriver" id="DBDriver">DBDriver</a> <a name="dbdriver" id="dbdriver">Directive</a></h2>
244
<table class="directive">
245
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify an SQL driver</td></tr>
246
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>DBDriver <var>name</var></code></td></tr>
247
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
248
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
249
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_dbd</td></tr>
251
<p>Selects an apr_dbd driver by name. The driver must be installed
252
on your system (on most systems, it will be a shared object or dll).
253
For example, <code>DBDriver mysql</code> will select the MySQL
254
driver in apr_dbd_mysql.so.</p>
258
<div class="bottomlang">
259
<p><span>Available Languages: </span><a href="../en/mod/mod_dbd.html" title="English"> en </a></p>
260
</div><div id="footer">
261
<p class="apache">Copyright 2006 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>
262
<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>
b'\\ No newline at end of file'
added
removed
docs/manual/mod/mod_dbd.html.en
