2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_dbd.xml.meta">
26 <description>Manages SQL database connections</description>
27 <status>Extension</status>
28 <sourcefile>mod_dbd.c</sourcefile>
29 <identifier>dbd_module</identifier>
32 <p><module>mod_dbd</module> manages SQL database connections using
33 <glossary>APR</glossary>. It provides database connections on request
34 to modules requiring SQL database functions, and takes care of
35 managing databases with optimal efficiency and scalability
36 for both threaded and non-threaded MPMs. For details, see the
37 <a href="http://apr.apache.org/">APR</a> website and this overview of the
38 <a href="http://people.apache.org/~niq/dbd.html">Apache DBD Framework</a>
39 by its original developer.
43 <seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
45 <section id="pooling"><title>Connection Pooling</title>
46 <p>This module manages database connections, in a manner
47 optimised for the platform. On non-threaded platforms,
48 it provides a persistent connection in the manner of
49 classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
50 On threaded platform, it provides an altogether more
51 scalable and efficient <em>connection pool</em>, as
52 described in <a href="http://www.apachetutor.org/dev/reslist">this
53 article at ApacheTutor</a>. Note that <module>mod_dbd</module>
54 supersedes the modules presented in that article.</p>
57 <section id="API"><title>Apache DBD API</title>
58 <p><module>mod_dbd</module> exports five functions for other modules
59 to use. The API is as follows:</p>
61 <highlight language="c">
64 apr_dbd_driver_t *driver;
68 /* Export functions to access the database */
70 /* acquire a connection that MUST be explicitly closed.
71 * Returns NULL on error
73 AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
75 /* release a connection acquired with ap_dbd_open */
76 AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
78 /* acquire a connection that will have the lifetime of a request
79 * and MUST NOT be explicitly closed. Return NULL on error.
80 * This is the preferred function for most applications.
82 AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
84 /* acquire a connection that will have the lifetime of a connection
85 * and MUST NOT be explicitly closed. Return NULL on error.
87 AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
89 /* Prepare a statement for use by a client module */
90 AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
92 /* Also export them as optional functions for modules that prefer it */
93 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
94 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
95 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
96 APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
97 APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
101 <section id="prepared"><title>SQL Prepared Statements</title>
102 <p><module>mod_dbd</module> supports SQL prepared statements on behalf
103 of modules that may wish to use them. Each prepared statement
104 must be assigned a name (label), and they are stored in a hash:
105 the <code>prepared</code> field of an <code>ap_dbd_t</code>.
106 Hash entries are of type <code>apr_dbd_prepared_t</code>
107 and can be used in any of the apr_dbd prepared statement
108 SQL query or select commands.</p>
110 <p>It is up to dbd user modules to use the prepared statements
111 and document what statements can be specified in httpd.conf,
112 or to provide their own directives and use <code>ap_dbd_prepare</code>.</p>
114 <note type="warning"><title>Caveat</title>
115 When using prepared statements with a MySQL database, it is preferred to set
116 <code>reconnect</code> to 0 in the connection string as to avoid errors that
117 arise from the MySQL client reconnecting without properly resetting the
118 prepared statements. If set to 1, any broken connections will be attempted
119 fixed, but as mod_dbd is not informed, the prepared statements will be invalidated.
123 <section id="security">
124 <title>SECURITY WARNING</title>
125 <p>Any web/database application needs to secure itself against SQL
126 injection attacks. In most cases, Apache DBD is safe, because
127 applications use prepared statements, and untrusted inputs are
128 only ever used as data. Of course, if you use it via third-party
129 modules, you should ascertain what precautions they may require.</p>
130 <p>However, the <var>FreeTDS</var> driver is inherently
131 <strong>unsafe</strong>. The underlying library doesn't support
132 prepared statements, so the driver emulates them, and the
133 untrusted input is merged into the SQL statement.</p>
134 <p>It can be made safe by <em>untainting</em> all inputs:
135 a process inspired by Perl's taint checking. Each input
136 is matched against a regexp, and only the match is used,
137 according to the Perl idiom:</p>
139 <pre><code> $untrusted =~ /([a-z]+)/;
140 $trusted = $1;</code></pre>
142 <p>To use this, the untainting regexps must be included in the
143 prepared statements configured. The regexp follows immediately
144 after the % in the prepared statement, and is enclosed in
145 curly brackets {}. For example, if your application expects
146 alphanumeric input, you can use:</p>
148 <code>"SELECT foo FROM bar WHERE input = %s"</code>
150 <p>with other drivers, and suffer nothing worse than a failed query.
151 But with FreeTDS you'd need:</p>
153 <code>"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"</code>
155 <p>Now anything that doesn't match the regexp's $1 match is
156 discarded, so the statement is safe.</p>
157 <p>An alternative to this may be the third-party ODBC driver,
158 which offers the security of genuine prepared statements.</p>
161 <name>DBDriver</name>
162 <description>Specify an SQL driver</description>
163 <syntax>DBDriver <var>name</var></syntax>
164 <contextlist><context>server config</context><context>virtual host</context>
168 <p>Selects an apr_dbd driver by name. The driver must be installed
169 on your system (on most systems, it will be a shared object or dll).
170 For example, <code>DBDriver mysql</code> will select the MySQL
171 driver in apr_dbd_mysql.so.</p>
176 <name>DBDParams</name>
177 <description>Parameters for database connection</description>
179 <var>param1</var>=<var>value1</var>[,<var>param2</var>=<var>value2</var>]</syntax>
180 <contextlist><context>server config</context><context>virtual host</context>
184 <p>As required by the underlying driver. Typically this will be
185 used to pass whatever cannot be defaulted amongst username,
186 password, database name, hostname and port number for connection.</p>
187 <p>Connection string parameters for current drivers include:</p>
189 <dt>FreeTDS (for MSSQL and SyBase)</dt>
190 <dd>username, password, appname, dbname, host, charset, lang, server</dd>
192 <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
194 <dd>user, pass, dbname, server</dd>
196 <dd>The connection string is passed straight through to <code>PQconnectdb</code></dd>
198 <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>
200 <dd>The connection string is passed straight through to <code>sqlite3_open</code></dd>
202 <dd>datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize</dd>
208 <name>DBDPersist</name>
209 <description>Whether to use persistent connections</description>
210 <syntax>DBDPersist On|Off</syntax>
211 <contextlist><context>server config</context><context>virtual host</context>
215 <p>If set to Off, persistent and pooled connections are disabled.
216 A new database connection is opened when requested by a client,
217 and closed immediately on release. This option is for debugging
218 and low-usage servers.</p>
220 <p>The default is to enable a pool of persistent connections
221 (or a single LAMP-style persistent connection in the case of a
222 non-threaded server), and should almost always be used in operation.</p>
224 <p>Prior to version 2.2.2, this directive accepted only the values
225 <code>0</code> and <code>1</code> instead of <code>Off</code> and
226 <code>On</code>, respectively.</p>
231 <name>DBDPrepareSQL</name>
232 <description>Define an SQL prepared statement</description>
233 <syntax>DBDPrepareSQL <var>"SQL statement"</var> <var>label</var></syntax>
234 <contextlist><context>server config</context><context>virtual host</context>
238 <p>For modules such as authentication that repeatedly use a
239 single SQL statement, optimum performance is achieved by preparing
240 the statement at startup rather than every time it is used.
241 This directive prepares an SQL statement and assigns it a label.</p>
247 <description>Minimum number of connections</description>
248 <syntax>DBDMin <var>number</var></syntax>
249 <default>DBDMin 1</default>
250 <contextlist><context>server config</context><context>virtual host</context>
254 <p>Set the minimum number of connections per process (threaded
261 <description>Maximum sustained number of connections</description>
262 <syntax>DBDKeep <var>number</var></syntax>
263 <default>DBDKeep 2</default>
264 <contextlist><context>server config</context><context>virtual host</context>
268 <p>Set the maximum number of connections per process to be
269 sustained, other than for handling peak demand (threaded
276 <description>Maximum number of connections</description>
277 <syntax>DBDMax <var>number</var></syntax>
278 <default>DBDMax 10</default>
279 <contextlist><context>server config</context><context>virtual host</context>
283 <p>Set the hard maximum number of connections per process
284 (threaded platforms only).</p>
289 <name>DBDExptime</name>
290 <description>Keepalive time for idle connections</description>
291 <syntax>DBDExptime <var>time-in-seconds</var></syntax>
292 <default>DBDExptime 300</default>
293 <contextlist><context>server config</context><context>virtual host</context>
297 <p>Set the time to keep idle connections alive when the number
298 of connections specified in DBDKeep has been exceeded (threaded
304 <name>DBDInitSQL</name>
305 <description>Execute an SQL statement after connecting to a database</description>
306 <syntax>DBDInitSQL <var>"SQL statement"</var></syntax>
307 <contextlist><context>server config</context><context>virtual host</context>
311 <p>Modules, that wish it, can have one or more SQL statements
312 executed when a connection to a database is created. Example
313 usage could be initializing certain values or adding a log
314 entry when a new connection is made to the database.</p>